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

package/ai-docs/templates/new-method/01-requirements.md

@@ -0,0 +1,232 @@
+# New Method - Requirements
+
+> **Purpose**: Gather requirements from the developer before implementing the new method.
+
+---
+
+## 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 start reading implementation code 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 implementation when all MANDATORY fields have explicit developer-provided answers.
+
+---
+
+## 1. Method Identity (MANDATORY)
+
+Ask the developer:
+
+1. **"Which file should this method be added to?"**
+   - e.g., `cc.ts`, `services/agent/index.ts`, `services/task/contact.ts`
+
+2. **"What should the method be named?"**
+   - Must be camelCase (e.g., `getTeamStats`, `getBuddyAgents`)
+
+3. **"What does this method do? Describe the expected behavior in one or two sentences."**
+
+---
+
+## 2. Method Signature (MANDATORY)
+
+Ask the developer:
+
+4. **"What parameters does this method accept? For each parameter, provide:"**
+   - Parameter name
+   - Type (string, number, object — if object, what fields?)
+   - Required or optional?
+
+5. **"What does this method return?"**
+   - Return type structure (e.g., `{ data: { agentList: Agent[] }, trackingId: string }`)
+   - What fields will consumers use?
+
+---
+
+## 3. API Integration (MANDATORY if the method calls a backend API, otherwise skip)
+
+Ask the developer:
+
+6. **"Does this method call a backend API?"**
+   - If YES, for each API call ask:
+
+   | Field | What to Ask |
+   |---|---|
+   | HTTP Method | "Is this a GET, POST, PUT, or DELETE?" |
+   | Endpoint | "What is the full endpoint path?" |
+   | Request Payload | "What fields does the request body contain? Which are required vs optional?" |
+   | Response Channel | "Is the response received in the HTTP response itself, or via a WebSocket message?" |
+   | Response Structure | "What does the response look like?" |
+   | Error Shape | "What error reason codes can this return?" |
+
+   > **Note**: Some methods receive their response directly in the HTTP response (e.g., `getBuddyAgents` returns data in the API response). Others initiate an operation via HTTP and receive the result asynchronously through a WebSocket message (e.g., `stationLogin` sends HTTP request, then receives `AGENT_STATION_LOGIN_SUCCESS` or `AGENT_STATION_LOGIN_FAILED` via WebSocket). Clarify which pattern applies.
+
+   **If any API field is unknown, STOP and ask the developer. Do not guess.**
+
+   - If NO (e.g., local computation, state change only): note "No API call" and skip to section 4.
+
+---
+
+## 4. Event Contract (MANDATORY if the method emits or listens to events, otherwise skip)
+
+Ask the developer:
+
+7. **"Does this method emit any events or listen to events?"**
+   - If YES, for each event ask:
+
+   | Field | What to Ask |
+   |---|---|
+   | Event Name | "What is the event name?" (e.g., `agent:buddyListSuccess`) |
+   | Direction | "Is this incoming (WebSocket) or outgoing (emitted by SDK)?" |
+   | Listen/Emit Object | "Where do consumers subscribe?" (`cc`, `task`, `taskManager`, service) |
+   | Payload Type/Shape | "What data does the event carry?" |
+   | Emitted From | "Which class/file emits this?" |
+   | Emission Trigger | "What causes this event to fire?" (e.g., API success, WebSocket message) |
+
+   **If the developer needs new event constants, note the constant names and values.**
+
+   - If NO: note "No events" and skip to section 5.
+
+---
+
+## 5. Metrics (MANDATORY)
+
+Ask the developer:
+
+8. **"What should the success and failure metric event names be?"**
+   - e.g., `FETCH_BUDDY_AGENTS_SUCCESS` / `FETCH_BUDDY_AGENTS_FAILED`
+   - If the developer is unsure, suggest names following the convention: `[ACTION]_[OPERATION]_SUCCESS` / `[ACTION]_[OPERATION]_FAILED`
+
+9. **"Do new metric constants need to be added to `src/metrics/constants.ts`?"**
+
+---
+
+## 6. Behavior Details (MANDATORY)
+
+Ask the developer:
+
+10. **"What should happen on success? (e.g., return data, emit event, update state)"**
+
+11. **"What should happen on failure? (e.g., throw error, emit failure event, retry)"**
+
+12. **"Are there any edge cases or special scenarios to handle?"**
+    - e.g., empty results, missing permissions, specific error codes
+
+---
+
+## Completion Gate
+
+**Before proceeding, verify:**
+
+- [ ] Target file identified by developer
+- [ ] Method name provided by developer
+- [ ] Purpose/behavior described by developer
+- [ ] Parameters fully specified (names, types, required/optional)
+- [ ] Return type fully specified
+- [ ] API contract captured (or developer confirmed no API call)
+- [ ] Event contract captured (or developer confirmed no events)
+- [ ] Metric event names defined
+- [ ] Success and failure behavior described
+
+**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 implementation:
+
+```
+## Spec Summary — New Method
+
+**Method**: `[methodName]([params]): Promise<[ReturnType]>`
+**Target file**: [file path]
+**Purpose**: [from Q3]
+
+### Parameters:
+| Name | Type | Required | Description |
+|---|---|---|---|
+| [param] | [type] | [Yes/No] | [description] |
+
+### API Contract:
+- HTTP: [METHOD] [endpoint]
+- Request: [payload structure]
+- Response: [response structure]
+- Errors: [reason codes]
+(or "No API call")
+
+### Events:
+| Event | Direction | Object | Payload | Trigger |
+|---|---|---|---|---|
+| [event] | [in/out] | [object] | [payload] | [trigger] |
+(or "No events")
+
+### Metrics:
+- Success: [METRIC_NAME_SUCCESS]
+- Failure: [METRIC_NAME_FAILED]
+- New constants needed: [Yes/No]
+
+### Behavior:
+- On success: [description]
+- On failure: [description]
+- Edge cases: [list or "None"]
+
+---
+Does this match your intent? (Yes / No / Adjust)
+```
+
+**Wait for developer approval. Do not proceed to [`02-implementation.md`](02-implementation.md) until confirmed.**
+
+---
+
+## Example: Adding getBuddyAgents
+
+```
+## Spec Summary — New Method
+
+**Method**: `getBuddyAgents(data: BuddyAgents): Promise<BuddyAgentsResponse>`
+**Target file**: cc.ts
+**Purpose**: Get list of available agents for consult/transfer
+**Types to create**: Define `BuddyAgents` (request params) and `BuddyAgentsResponse` (response) in the appropriate types file (`src/types.ts` for public types, or `src/services/[service]/types.ts` for internal types). Export public types from `src/types.ts`.
+
+### Parameters:
+| Name | Type | Required | Description |
+|---|---|---|---|
+| mediaType | 'telephony' \| 'chat' \| 'social' \| 'email' | Yes | Media type channel filter |
+| state | 'Available' \| 'Idle' | No | Optional agent state filter |
+
+### API Contract:
+- HTTP: POST /v1/agents/buddyList
+- Request: { agentProfileId: string, mediaType: string, state?: string }
+- Response channel: HTTP response (synchronous)
+- Response: { data: { agentList: BuddyDetails[] }, trackingId: string }
+- Errors: INVALID_STATE, UNAUTHORIZED
+
+### Events: No events (promise-based only)
+
+### Metrics:
+- Success: FETCH_BUDDY_AGENTS_SUCCESS
+- Failure: FETCH_BUDDY_AGENTS_FAILED
+- New constants needed: Yes
+
+### Behavior:
+- On success: return response data
+- On failure: throw augmented error via getErrorDetails
+- Edge cases: empty agentList returns { data: { agentList: [] } }
+
+### Type Definitions:
+- **Input type `BuddyAgents`**: Defined in `src/types.ts` (public, consumer-facing)
+  and `src/services/agent/types.ts` (internal, includes `agentProfileId` added by cc.ts)
+- **Response type `BuddyAgentsResponse`**: Defined in `src/types.ts` as
+  `Agent.BuddyAgentsSuccess | Error`
+- **Internal types `BuddyAgentsSuccess`, `BuddyDetails`**: Defined in
+  `src/services/agent/types.ts`
+- **Pattern**: Public types (what consumers see) go in `src/types.ts`.
+  Internal/service types (with extra fields like `agentProfileId`) go in
+  `src/services/[service]/types.ts`.
+```
+
+---
+
+## Next Step
+
+Once the developer approves the spec summary, proceed to:
+[`02-implementation.md`](02-implementation.md)

package/ai-docs/templates/new-method/02-implementation.md

@@ -0,0 +1,295 @@
+# New Method - Implementation
+
+> **Purpose**: Implement the new method following SDK patterns.
+
+---
+
+## Method Invocation Patterns
+
+There are two common patterns for where methods are implemented. The public method lives on whichever object owns the feature's scope (currently `cc` for SDK-level operations, `task` for per-interaction operations, or a public service accessor for domain-specific queries). New public objects may be introduced in the future.
+
+1. **Public wrapper + internal service call**: The public method is defined on the owning object, but the actual implementation lives in a service module. The public method delegates internally.
+   ```typescript
+   // Example A: cc.ts — SDK-level method delegates to agent service
+   public async getBuddyAgents(data: BuddyAgents): Promise<BuddyAgentsResponse> {
+     const resp = await this.services.agent.buddyAgents({
+       data: {agentProfileId: this.agentConfig.agentProfileID, ...data},
+     });
+     return resp;
+   }
+
+   // Example B: Task.ts — per-interaction method delegates to contact service
+   public async hold(): Promise<TaskResponse> {
+     return this.contact.hold({...});
+   }
+   ```
+
+2. **Direct service access**: Sometimes consumers call a service method directly via a public service accessor on `cc`.
+   ```typescript
+   // Consumer code calling service directly via public accessor
+   const queues = await cc.queue.getQueues();
+   const entries = await cc.addressBook.getEntries();
+   ```
+   > **Note:** Use `cc.<serviceName>` (e.g., `cc.queue`, `cc.addressBook`), NOT `cc.services.<serviceName>`. The `services` object is internal.
+
+Determine which pattern applies based on the requirements gathered in Step 1.
+
+---
+
+## Method Template
+
+```typescript
+/**
+ * Brief description of what this method does.
+ *
+ * @description
+ * Detailed description including:
+ * - What the method accomplishes
+ * - When to use it
+ * - Prerequisites (e.g., must be logged in)
+ *
+ * @param {ParamType} data - Description of parameters
+ * @param {string} data.requiredField - Description
+ * @param {number} [data.optionalField] - Optional field description
+ *
+ * @returns {Promise<ReturnType>} Description including:
+ *   - field1: What this field contains
+ *   - field2: What this field contains
+ *
+ * @throws {Error} When operation fails with reason in error.message
+ *
+ * @public
+ *
+ * @example
+ * ```typescript
+ * const cc = webex.cc;
+ * await cc.register();
+ * await cc.stationLogin({ teamId: 'team123', loginOption: 'BROWSER' });
+ *
+ * // Basic usage
+ * const result = await cc.methodName({
+ *   requiredField: 'value',
+ * });
+ *
+ * // With optional params
+ * const result = await cc.methodName({
+ *   requiredField: 'value',
+ *   optionalField: 42,
+ * });
+ * ```
+ */
+public async methodName(data: ParamType): Promise<ReturnType> {
+  // 1. Log start of operation
+  LoggerProxy.info('Starting operation', {
+    module: CC_FILE,
+    method: METHODS.METHOD_NAME,
+  });
+  
+  try {
+    // 2. Start timing for metrics
+    this.metricsManager.timeEvent([
+      METRIC_EVENT_NAMES.OPERATION_SUCCESS,
+      METRIC_EVENT_NAMES.OPERATION_FAILED,
+    ]);
+    
+    // 3. Validate input if needed
+    if (!data.requiredField) {
+      throw new Error('requiredField is required');
+    }
+    
+    // 4. Call service method
+    const result = await this.services.someService.method({
+      data: {
+        ...data,
+        // Add any additional fields from agentConfig if needed
+        agentId: this.agentConfig.agentId,
+      },
+    });
+    
+    // 5. Track success metrics
+    this.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.OPERATION_SUCCESS,
+      {
+        ...MetricsManager.getCommonTrackingFieldForAQMResponse(result),
+        // Add operation-specific fields
+        customField: data.requiredField,
+      },
+      ['behavioral', 'operational']  // Adjust metric types as needed
+    );
+    
+    // 6. Log success
+    LoggerProxy.log('Operation completed successfully', {
+      module: CC_FILE,
+      method: METHODS.METHOD_NAME,
+      trackingId: result.trackingId,
+    });
+    
+    // 7. Return result (transform if needed)
+    return result;
+    
+  } catch (error) {
+    // 8. Cast error details
+    const failure = error.details as Failure;
+    
+    // 9. Track failure metrics
+    this.metricsManager.trackEvent(
+      METRIC_EVENT_NAMES.OPERATION_FAILED,
+      {
+        ...MetricsManager.getCommonTrackingFieldForAQMResponseFailed(failure),
+        customField: data.requiredField,
+      },
+      ['behavioral', 'operational']
+    );
+    
+    // 10. Get detailed error (this logs and uploads logs automatically)
+    const {error: detailedError} = getErrorDetails(
+      error,
+      METHODS.METHOD_NAME,
+      CC_FILE
+    );
+    
+    // 11. Throw augmented error
+    throw detailedError;
+  }
+}
+```
+
+---
+
+## Event Emission (if applicable)
+
+If the method needs to emit events, understand the two-step flow used in the SDK:
+
+### How it works: WebSocket trigger → EventEmitter emit
+
+For methods that go through `aqm-reqs` (used by all AQM-integrated services — agent, task, etc., except config service GET methods), the flow is:
+
+1. **cc.ts** public method calls a service method (e.g., `this.services.agent.stationLogin()`)
+2. **aqm-reqs.ts** sends an HTTP request AND registers pending handlers for the expected WebSocket success/fail messages (via `notifSuccess`/`notifFail` bindings)
+3. **Backend** processes the request and sends the result back via **WebSocket**
+4. **aqm-reqs.onMessage()** receives the WS message, matches it to the pending request, and resolves/rejects the Promise
+5. **cc.ts `handleWebsocketMessage()`** also receives the same WS message and uses `trigger` to fire events for consumers
+
+```
+HTTP request → Backend → WS message
+                            ├─→ aqm-reqs.onMessage() → resolves/rejects Promise
+                            └─→ cc.ts handleWebsocketMessage() → this.trigger(EVENT)
+```
+
+### Real example: `setAgentState` in cc.ts
+
+**Step 1 — Service defines WS bindings** (in `services/agent/index.ts`):
+```typescript
+stateChange: routing.req((p: {data: Agent.StateChange}) => ({
+  url: '/v1/agents/state',
+  host: WCC_API_GATEWAY,
+  data: p.data,
+  err,
+  notifSuccess: {
+    bind: { type: CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS },
+    msg: {} as Agent.StateChangeSuccess,
+  },
+  notifFail: {
+    bind: { type: CC_EVENTS.AGENT_STATE_CHANGE_FAILED },
+    errId: 'Service.aqm.agent.stateChange',
+  },
+})),
+```
+
+**Step 2 — WS message triggers event** (in `cc.ts handleWebsocketMessage()`):
+```typescript
+case CC_EVENTS.AGENT_STATE_CHANGE_SUCCESS:
+  // cc.ts extends WebexPlugin — use trigger, not emit
+  // @ts-ignore
+  this.trigger(AGENT_EVENTS.AGENT_STATE_CHANGE_SUCCESS, eventData.data);
+  break;
+case CC_EVENTS.AGENT_STATE_CHANGE_FAILED:
+  // @ts-ignore
+  this.trigger(AGENT_EVENTS.AGENT_STATE_CHANGE_FAILED, eventData.data);
+  break;
+```
+
+**Step 3 — Consumer listens** using `.on()`:
+```typescript
+const handleStateChangeSuccess = (data) => {
+  // Handle state change success
+};
+cc.on(AGENT_EVENTS.AGENT_STATE_CHANGE_SUCCESS, handleStateChangeSuccess);
+```
+
+### Task-level events (method-level emit)
+
+For Task methods (which extend `EventEmitter`), events are emitted directly using `emit`:
+```typescript
+// Task.ts extends EventEmitter — emit works natively
+// On success, emit directly:
+this.emit(TASK_EVENTS.TASK_AUTO_ANSWERED, this);
+```
+
+> **When to emit events**: Emit events when consumers need to react asynchronously to state changes (WS-driven methods like `stationLogin`, `setAgentState`). For simple request-response methods (like `getBuddyAgents`), the returned Promise is sufficient — no events needed.
+
+---
+
+## Adding Method Constants
+
+In `src/constants.ts`, add method name:
+
+```typescript
+export const METHODS = {
+  // ... existing
+  METHOD_NAME: 'methodName',
+} as const;
+```
+
+---
+
+## Adding Metric Constants
+
+In `src/metrics/constants.ts`:
+
+```typescript
+export const METRIC_EVENT_NAMES = {
+  // ... existing
+  OPERATION_SUCCESS: 'operation success',
+  OPERATION_FAILED: 'operation failed',
+} as const;
+```
+
+---
+
+## Adding Types
+
+In `src/types.ts` or appropriate service types file:
+
+```typescript
+/**
+ * Parameters for methodName operation
+ * @public
+ */
+export type ParamType = {
+  /** Description of required field */
+  requiredField: string;
+  /** Description of optional field */
+  optionalField?: number;
+};
+
+/**
+ * Response from methodName operation
+ * @public
+ */
+export type ReturnType = {
+  /** Description of data */
+  data: {
+    /** Field description */
+    field: string;
+  };
+  /** Request tracking ID */
+  trackingId: string;
+};
+```
+
+---
+
+## Next Step
+
+Proceed to: [`03-tests.md`](03-tests.md)