docs(contact-center): add ai-docs SDD pattern documentation by ciscoRankush · Pull Request #4723 · webex/webex-js-sdk

ciscoRankush · 2026-02-19T09:30:30Z

COMPLETES #SPARK-775699

This pull request addresses

AI agents need reference documentation for the established coding patterns in the @webex/contact-center SDK so they can generate code that is consistent with existing conventions. Without pattern docs, agents
produce code that uses console.log instead of LoggerProxy, misses MetricsManager tracking, uses incorrect error handling, and deviates from established type conventions.

by making the following changes

Adds ai-docs/patterns/ with 5 pattern documentation files:
- typescript-patterns.md — Type conventions, LoggerProxy usage (not console.log), error handling with getErrorDetails, constant patterns, JSDoc conventions
- testing-patterns.md — Jest test structure, mocking patterns (LoggerProxy, services, WebSocket), test naming conventions, success/error/edge case coverage
- event-driven-patterns.md — Event emission patterns, listener registration/cleanup, event constant usage, WebSocket event handling
- websocket-patterns.md — WebSocket connection lifecycle, reconnection flow, silent relogin, message handling patterns
- sdk-plugin-patterns.md — WebexPlugin extension, service registration, initialization in READY block, public API exposure via cc.ts

Change Type

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tooling change
Internal code refactor

The following scenarios were tested

Pattern Compliance — Verified all code examples in pattern files follow SDK conventions (LoggerProxy, not console.log; getErrorDetails for errors; MetricsManager tracking)
console.log Fix — Confirmed typescript-patterns.md uses LoggerProxy.error() in error handling examples (previously had console.log which contradicted the no-console.log rule)
Cross-Reference Validation — Verified pattern files are correctly referenced from template 00-master.md files via ../../patterns/ relative paths
Type E Routing — Tested that architecture understanding prompts (e.g., "How does WebSocket reconnection work?") correctly route to these pattern docs via the Service Routing Table

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

I have read and followed contributing guidelines
I discussed changes with code owners prior to submitting this pull request
I have not skipped any automated checks
All existing and new tests passed
I have updated the documentation accordingly

Shreyas281299 · 2026-02-20T05:18:38Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb5d146901

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

packages/@webex/contact-center/AGENTS.md

packages/@webex/contact-center/ai-docs/patterns/sdk-plugin-patterns.md

Add pattern documentation for AI agents to reference during code generation: - typescript-patterns.md — type conventions, error handling, LoggerProxy usage - testing-patterns.md — Jest patterns, mocking, test structure - event-driven-patterns.md — event emission, listener patterns - websocket-patterns.md — WebSocket connection, reconnection patterns - sdk-plugin-patterns.md — WebexPlugin extension, service registration Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Shreyas281299 · 2026-02-23T08:48:09Z

packages/@webex/contact-center/ai-docs/patterns/typescript-patterns.md

+const event2: CC_EVENTS = 'InvalidEvent';        // ❌ Compile error
+```
+
+### Response Type Pattern


Lets remove this

Shreyas281299 · 2026-02-23T08:53:20Z

packages/@webex/contact-center/ai-docs/patterns/testing-patterns.md

+        getOrgId: jest.fn(() => 'mockOrgId'),
+      },
+      config: config,
+    }) as unknown as WebexSDK;


We should not use unkown, thie way LLM would put unknown everywhere

Shreyas281299 · 2026-02-23T08:54:40Z

packages/@webex/contact-center/ai-docs/patterns/testing-patterns.md

+
+```bash
+# Run tests with coverage
+yarn workspace @webex/contact-center test --coverage


Suggested change

yarn workspace @webex/contact-center test --coverage

yarn workspace @webex/contact-center test:unit --coverage

Shreyas281299 · 2026-02-23T08:57:47Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+### Message Reception
+
+```
+WebSocket → WebSocketManager → cc.handleWebsocketMessage → Event Emission


Mermaid diagram. This is a very speicifc flow. We can add a generic flow to explain the generic event reception

this is more machine readable statement , so lets keep it

Shreyas281299 · 2026-02-23T09:03:25Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+### From Plugin Class
+
+```typescript
+// Using WebexPlugin's emit method
+this.emit(AGENT_EVENTS.AGENT_STATE_CHANGE, eventData);
+
+// Using trigger for some events (alternative method)
+this.trigger(TASK_EVENTS.TASK_INCOMING, task);
+```
+
+### From TaskManager
+
+```typescript
+// TaskManager extends EventEmitter
+export default class TaskManager extends EventEmitter {
+  private emitTaskEvent(eventType: string, task: ITask) {
+    this.emit(eventType, task);
+  }
+
+  public handleIncomingTask(taskData: TaskData) {
+    const task = this.createTask(taskData);
+    this.emit(TASK_EVENTS.TASK_INCOMING, task);
+  }
+}
+```
+
+---


We dont need subheading

What we need?

How we emit events. Two ways

We need to differntiate when to use trigger and when to use emit
P.S: emit is used when the class is extendin EventEmitter and trigger is used in the other case-trigger is very speicifc for cc object as it extends WebexPlugin

Code example of each way

Shreyas281299 · 2026-02-23T09:07:02Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+### In Application Code
+
+```typescript
+// Subscribe to events
+const cc = webex.cc;
+
+cc.on('agent:stateChange', (event) => {
+  console.log('Agent state changed:', event.state);
+});
+
+cc.on('task:incoming', (task) => {
+  console.log('New task:', task.interactionId);
+});
+
+// Unsubscribe
+const handler = (event) => { /* handle */ };
+cc.on('agent:stateChange', handler);
+cc.off('agent:stateChange', handler);
+```
+
+### Internal Subscription
+
+```typescript
+// In constructor
+constructor() {
+  this.$webex.once(READY, () => {
+    this.services.webSocketManager.on('message', this.handleWebsocketMessage);
+    this.services.connectionService.on('connectionLost', this.handleConnectionLost);
+
+    this.taskManager.on(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
+    this.taskManager.on(TASK_EVENTS.TASK_HYDRATE, this.handleTaskHydrate);
+  });
+}
+
+// Cleanup in deregister
+public async deregister() {
+  this.taskManager.off(TASK_EVENTS.TASK_INCOMING, this.handleIncomingTask);
+  this.services.webSocketManager.off('message', this.handleWebsocketMessage);
+}
+```
+


What we need?

How to add/remove an event listener?

Examples
2.1 Internal event listening
2.2 Events sent to application (from cc,task)

Shreyas281299 · 2026-02-23T09:10:34Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+## Connection Events
+
+### Connection Lost/Reconnected
+
+```typescript
+// services/core/websocket/types.ts
+export type ConnectionLostDetails = {
+  isConnectionLost: boolean;
+  isSocketReconnected: boolean;
+};
+
+// Handling in cc.ts
+private async handleConnectionLost(msg: ConnectionLostDetails): Promise<void> {
+  if (msg.isConnectionLost) {
+    LoggerProxy.info('Connection lost', {
+      module: CC_FILE,
+      method: 'handleConnectionLost',
+    });
+  } else if (msg.isSocketReconnected) {
+    LoggerProxy.info('Connection reconnected', {
+      module: CC_FILE,
+      method: 'handleConnectionLost',
+    });
+
+    if (this.$config?.allowAutomatedRelogin) {
+      await this.silentRelogin();
+    }
+  }
+}
+```


This is not part of SDK. Lets remove this

packages/@webex/contact-center/ai-docs/patterns/testing-patterns.md

…tern docs Apply reviewer feedback from Shreyas and Kesari plus source code validation: - Delete sdk-plugin-patterns.md (too cc.ts-specific) and websocket-patterns.md (lifecycle content folded into event-driven-patterns.md) - Fix AGENT_EVENTS/TASK_EVENTS to use enum syntax with correct values - Fix Failure type to use Msg<T> wrapper matching actual GlobalTypes.ts - Fix interface naming convention to acknowledge I prefix for contracts - Fix MetricsManager mock, file tree paths, test command, and event testing patterns - Genericize event flow, document trigger vs emit accurately, add WebSocket Lifecycle - Remove all broken links to deleted files across AGENTS.md, RULES.md, README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add 5 missing CC_AGENT_EVENTS members (AGENT_DN_REGISTERED, AGENT_BUDDY_AGENTS, AGENT_BUDDY_AGENTS_SUCCESS, AGENT_BUDDY_AGENTS_RETRIEVE_FAILED, AGENT_CONTACT_RESERVED) to match config/types.ts - Fix arrow function claim: document both arrow property and .bind(this) patterns used in cc.ts - Fix getActiveTasks → getAllTasks in testing-patterns.md mock Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Kesari3008 · 2026-02-24T11:55:34Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+
+## Event Emission
+
+There are **two methods** for emitting events: `trigger` and `emit`. Both work on the `cc` object (which extends `WebexPlugin`), but they should be used in different contexts.


emit doesn't work on cc object because it doesn't extend event emitter class. We are adding @ts-ignore to be able to invoke it. Emphasis here should be that classes which extend EventEmitter can use emit for event emission but for classes like cc.ts can use trigger for emission

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

Kesari3008 · 2026-02-24T12:07:43Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+const cc = webex.cc;
+
+// Agent events (from cc)
+cc.on(AGENT_EVENTS.AGENT_STATE_CHANGE, (event) => {


In these examples, we should have callbacks while listening because .off won;t work if we don;t have separate callback function

… doc emit does not work on cc object (extends WebexPlugin, not EventEmitter). Use trigger for WebexPlugin classes, emit for EventEmitter classes. Also adds named callbacks in examples so .off() works properly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f5cd0f03c9

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-02-25T05:56:22Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+}
+
+// Register with .bind(this)
+this.services.connectionService.on('connectionLost', this.handleConnectionLost.bind(this));


Keep a stable callback when binding connectionLost listener

The on('connectionLost', this.handleConnectionLost.bind(this)) pattern creates a new function instance at registration time, but the cleanup examples later use off(..., this.handleConnectionLost). Because those are different references, the listener cannot be removed, so repeated register/deregister cycles can accumulate duplicate reconnection handlers and fire relogin logic multiple times.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-02-25T05:56:22Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+// Register listeners after SDK is ready
+this.$webex.once(READY, () => {
+  this.services.webSocketManager.on('message', this.handleWebsocketMessage);
+  this.services.connectionService.on('connectionLost', this.handleConnectionLost);


Bind handleConnectionLost in the internal listener example

This example subscribes this.handleConnectionLost without binding even though the handler is shown as a regular class method; with EventEmitter-style callbacks, this inside the handler will be the emitter, not the ContactCenter instance. That breaks access to instance members like $config/silentRelogin, so reconnection recovery logic can silently stop working if generated code follows this snippet.

Useful? React with 👍 / 👎.

Kesari3008 · 2026-02-25T06:36:10Z

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md

+this.trigger(TASK_EVENTS.TASK_HYDRATE, task);
+```
+
+> **Note**: `trigger` requires `// @ts-ignore` because WebexPlugin's TypeScript type definitions don't expose it.


This should be emit here, it should say that we can still use emit but with @ts-ignore. We can address this PRs which are not merged yet

ciscoRankush requested a review from a team as a code owner February 19, 2026 09:30

ciscoRankush changed the title ~~feat(contact-center): add ai-docs SDD pattern documentation~~ doc(contact-center): add ai-docs SDD pattern documentation Feb 19, 2026

Shreyas281299 added the validated If the pull request is validated for automation. label Feb 20, 2026

chatgpt-codex-connector bot reviewed Feb 20, 2026

View reviewed changes

packages/@webex/contact-center/AGENTS.md Show resolved Hide resolved

packages/@webex/contact-center/AGENTS.md Show resolved Hide resolved

ciscoRankush changed the title ~~doc(contact-center): add ai-docs SDD pattern documentation~~ docs(contact-center): add ai-docs SDD pattern documentation Feb 20, 2026

Shreyas281299 reviewed Feb 23, 2026

View reviewed changes

packages/@webex/contact-center/ai-docs/patterns/sdk-plugin-patterns.md Outdated Show resolved Hide resolved

ciscoRankush force-pushed the SPARK-775699Patterns branch from fb5d146 to 8b25a96 Compare February 23, 2026 08:57

Shreyas281299 reviewed Feb 23, 2026

View reviewed changes

Kesari3008 reviewed Feb 23, 2026

View reviewed changes

Shreyas281299 approved these changes Feb 24, 2026

View reviewed changes

Kesari3008 reviewed Feb 24, 2026

View reviewed changes

packages/@webex/contact-center/ai-docs/patterns/event-driven-patterns.md Show resolved Hide resolved

Kesari3008 reviewed Feb 24, 2026

View reviewed changes

Kesari3008 approved these changes Feb 24, 2026

View reviewed changes

chatgpt-codex-connector bot reviewed Feb 25, 2026

View reviewed changes

ciscoRankush merged commit 83d401d into webex:task-refactor Feb 25, 2026
11 checks passed

Kesari3008 reviewed Feb 25, 2026

View reviewed changes

	yarn workspace @webex/contact-center test --coverage
	yarn workspace @webex/contact-center test:unit --coverage


		## Event Emission

		There are two methods for emitting events: `trigger` and `emit`. Both work on the `cc` object (which extends `WebexPlugin`), but they should be used in different contexts.

Conversation

ciscoRankush commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

COMPLETES #SPARK-775699

This pull request addresses

by making the following changes

Change Type

The following scenarios were tested

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

Uh oh!

Shreyas281299 commented Feb 20, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kesari3008 Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ciscoRankush commented Feb 19, 2026 •

edited

Loading

Kesari3008 Feb 24, 2026 •

edited

Loading