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

Shreyas281299 · 2026-02-23T07:24:11Z

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

We can remove this

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

Kesari3008 · 2026-02-23T17:45:10Z

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

+
+---
+
+## Event Testing


Here I believe we need few tweaks, event listeners and their callback invocations are tested by spying on it and fetch the callback and invoking it using mock.calls. So phrasing this section like that would be helpful

Kesari3008 · 2026-02-23T17:46:40Z

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

+  });
+
+  // Assert
+  expect(result).toEqual(expect.objectContaining({


Also I would not encourage using expect.objectContaiining in tests. We prefer to do exact matches as much as possible in SDK unit testing

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>

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

Copy link

Contributor

Shreyas281299 Feb 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can remove this

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

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

Comments

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ciscoRankush commented Feb 19, 2026 •

edited

Loading