@webex/internal-plugin-call-ai-summary 0.0.0-next.1

package/.eslintrc.js

@@ -0,0 +1,6 @@
+const config = {
+  root: true,
+  extends: ['@webex/eslint-config-legacy'],
+};
+
+module.exports = config;

package/README.md

@@ -0,0 +1,257 @@
+# @webex/internal-plugin-call-ai-summary
+
+Internal Webex JS SDK plugin for retrieving AI-generated call summaries, notes, action items, and transcripts from completed calls.
+
+## Overview
+
+This plugin resolves AI summary containers via the **Pragya** service and fetches encrypted summary content from URLs returned by Pragya. All AI-generated content is decrypted using KMS keys provided in the container response.
+
+**Discovery flow:**
+
+1. **Janus** (call history) returns `extensionPayload.callingContainerIds` per call session
+2. **Pragya** resolves a container ID into metadata including content URLs and encryption key
+3. **Plugin** fetches content from those URLs and decrypts using `@webex/internal-plugin-encryption`
+
+## Install
+
+This plugin is part of the Webex JS SDK monorepo. It self-registers when imported — no changes to `packages/webex` are needed.
+
+```bash
+# From the SDK monorepo root
+yarn
+```
+
+To use in a consuming application:
+
+```javascript
+// Importing the plugin auto-registers it on webex.internal.aisummary
+import '@webex/internal-plugin-call-ai-summary';
+```
+
+## Prerequisites
+
+- An authenticated Webex SDK instance with a registered device
+- `@webex/internal-plugin-encryption` (pulled in automatically as a dependency)
+- A valid Pragya container ID (obtained from Janus call history `extensionPayload.callingContainerIds`)
+
+## API
+
+All methods are accessible via `webex.internal.aisummary`.
+
+### `getContainer({ containerId })`
+
+Resolves a Pragya container by ID. Returns container metadata with summary content URLs and the KMS encryption key.
+
+The raw Pragya response nests URLs under `summaryData.data` — this method flattens it so you can access `summaryData.summaryUrl` directly.
+
+```typescript
+const container = await webex.internal.aisummary.getContainer({
+  containerId: '34125120-13b5-11f1-9b36-adb685725098',
+});
+
+// container.summaryData.summaryUrl    — full summary URL
+// container.summaryData.transcriptUrl — transcript URL
+// container.summaryData.status        — "Active" when ready
+// container.encryptionKeyUrl          — KMS key for decryption
+```
+
+**Returns:** `Promise<PragyaContainerResponse>`
+
+### `getSummary({ containerInfo })`
+
+Fetches and decrypts all summary content (note, short note, and action items) in a single request via `summaryUrl?fields=note,shortnote,actionitems`.
+
+This is the **recommended** method for retrieving summary content.
+
+```typescript
+const summary = await webex.internal.aisummary.getSummary({
+  containerInfo: container,
+});
+
+console.log(summary.note);       // Decrypted full note
+console.log(summary.shortNote);  // Decrypted short note
+summary.actionItems.forEach((item) => {
+  console.log(item.aiGeneratedContent);  // Decrypted action item
+});
+```
+
+**Returns:** `Promise<SummaryContent>` — `{ id, note, shortNote, actionItems, feedbackUrl? }`
+
+### `getNotes({ containerInfo })`
+
+Fetches and decrypts notes from the standalone `notesUrl` endpoint. Only available if `notesUrl` is present in the Pragya response.
+
+```typescript
+const notes = await webex.internal.aisummary.getNotes({
+  containerInfo: container,
+});
+
+console.log(notes.content);  // Decrypted notes
+```
+
+**Returns:** `Promise<SummaryNotes>` — `{ id, content, feedbackUrl? }`
+
+### `getActionItems({ containerInfo })`
+
+Fetches and decrypts action items from the standalone `actionItemsUrl` endpoint. Only available if `actionItemsUrl` is present in the Pragya response.
+
+```typescript
+const actionItems = await webex.internal.aisummary.getActionItems({
+  containerInfo: container,
+});
+
+actionItems.snippets.forEach((snippet) => {
+  console.log(snippet.aiGeneratedContent);  // Decrypted
+  console.log(snippet.editedContent);       // User-edited version (if any)
+});
+```
+
+**Returns:** `Promise<SummaryActionItems>` — `{ id?, snippets[], feedbackUrl? }`
+
+### `getTranscriptUrl({ containerInfo })`
+
+Returns the transcript URL string without fetching or decrypting. Use this when you need the URL for downstream processing.
+
+```typescript
+const url = webex.internal.aisummary.getTranscriptUrl({
+  containerInfo: container,
+});
+```
+
+**Returns:** `string`
+
+### `getTranscript({ containerInfo })`
+
+Fetches and decrypts the full call transcript.
+
+```typescript
+const transcript = await webex.internal.aisummary.getTranscript({
+  containerInfo: container,
+});
+
+transcript.snippets.forEach((snippet) => {
+  console.log(`[${snippet.startTime}] ${snippet.speaker?.speakerName}: ${snippet.content}`);
+});
+```
+
+**Returns:** `Promise<TranscriptContent>` — `{ id, totalCount, snippets[] }`
+
+## Full Usage Example
+
+```typescript
+import '@webex/internal-plugin-call-ai-summary';
+
+// 1. Get call history (existing SDK API)
+const callHistory = await callHistoryInstance.getCallHistoryData(10, 50);
+const sessions = callHistory.data.userSessions;
+
+// 2. Find a session with AI summary
+const session = sessions.find(
+  (s) => s.extensionPayload?.callingContainerIds?.length > 0
+);
+if (!session) return;
+
+// 3. Resolve the container
+const containerId = session.extensionPayload.callingContainerIds[0];
+const container = await webex.internal.aisummary.getContainer({ containerId });
+
+if (container.summaryData.status !== 'Active') {
+  console.log('Summary not ready yet');
+  return;
+}
+
+// 4. Fetch all summary content in one call
+const summary = await webex.internal.aisummary.getSummary({ containerInfo: container });
+console.log('Note:', summary.note);
+console.log('Short Note:', summary.shortNote);
+summary.actionItems.forEach((item, i) => {
+  console.log(`Action ${i + 1}: ${item.aiGeneratedContent}`);
+});
+
+// 5. Fetch transcript
+const transcript = await webex.internal.aisummary.getTranscript({ containerInfo: container });
+transcript.snippets.forEach((s) => {
+  console.log(`[${s.startTime}] ${s.speaker?.speakerName}: ${s.content}`);
+});
+```
+
+## Manual Testing
+
+A manual integration test is provided for verifying against live APIs:
+
+```bash
+cd packages/@webex/internal-plugin-call-ai-summary
+
+# Provide a fresh token and container ID
+WEBEX_TOKEN='<token>' CONTAINER_ID='<id>' node src/manual-integration-test.js
+```
+
+This script registers a device (WDM), resolves the Pragya service via the SDK service catalog, fetches the container, decrypts summary content via KMS, and prints the results.
+
+## Error Handling
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| `containerId is required and must be a non-empty string` | Empty or missing containerId | Validate input before calling |
+| `containerInfo with valid summaryData and encryptionKeyUrl is required` | Missing container info or URL field | Call `getContainer()` first |
+| `Container not found` | 404 from Pragya | Verify containerId from Janus |
+| `Summary content not available or expired` | 404 from content endpoint | Content may have been deleted |
+| `Access denied: User not authorized to view this summary` | 403 | Check user permissions / org AI settings |
+| `Authentication failed: Invalid or expired token` | 401 | Re-authenticate the user |
+
+## Encryption
+
+All AI-generated content (`aiGeneratedContent` fields) is encrypted with KMS. The plugin decrypts automatically using:
+
+- **Key source:** `encryptionKeyUrl` from the Pragya container response, with fallback to `keyUrl` from the content response body
+- **Decryption method:** `webex.internal.encryption.decryptText(keyUrl, ciphertext)`
+
+This is the same pattern used by `@webex/internal-plugin-ai-assistant` and `@webex/internal-plugin-task`.
+
+## Development
+
+```bash
+cd packages/@webex/internal-plugin-call-ai-summary
+
+# Build
+yarn build
+
+# Lint
+yarn test:style
+
+# Unit tests
+yarn test:unit
+
+# All checks
+yarn test
+```
+
+## Package Structure
+
+```
+src/
+  index.ts          # Self-registration via registerInternalPlugin('aisummary', ...)
+  ai-summary.ts     # Plugin implementation (WebexPlugin.extend)
+  config.ts         # Plugin config
+  constants.ts      # Service name, error messages
+  types.ts          # TypeScript interfaces
+test/
+  unit/
+    spec/
+      ai-summary.ts # Unit tests (26 tests)
+    data/
+      responses.ts  # Mock API response fixtures
+ai-docs/
+  ARCHITECTURE.md   # Detailed architecture document
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@webex/webex-core` | Plugin infrastructure (`WebexPlugin`, `registerInternalPlugin`) |
+| `@webex/internal-plugin-encryption` | KMS content decryption via `decryptText()` |
+
+## Architecture
+
+See [ai-docs/ARCHITECTURE.md](ai-docs/ARCHITECTURE.md) for the full architecture document covering data flows, API request/response details, DTOs, security considerations, and testing strategy.

package/ai-docs/AGENTS.md

@@ -0,0 +1,300 @@
+# @webex/internal-plugin-call-ai-summary
+
+This is an internal Cisco Webex plugin. As such, it does not strictly adhere to semantic versioning. Use at your own risk. If you're not working on one of our first party clients, please look at our developer api and stick to our public plugins.
+Internal Webex JS SDK plugin for retrieving AI-generated call summaries, notes, action items, and transcript URLs from the Pragya and AI Bridge services.
+
+## Overview
+
+This plugin provides methods to:
+
+1. Resolve a **Pragya container** by ID (returns metadata, summary URLs, and encryption key)
+2. Fetch and decrypt **AI-generated summaries** (note, short note, action items) in a single call
+3. Fetch and decrypt **AI-generated notes** via a dedicated notes endpoint
+4. Fetch and decrypt **AI-generated action items** via a dedicated action items endpoint
+5. Retrieve the **transcript URL** for a call
+
+All AI-generated content is **JWE-encrypted** and decrypted via the KMS (Key Management Service) using `@webex/internal-plugin-encryption`.
+
+## Architecture
+
+```
+Pragya Service                     AI Bridge Service
+(container metadata)               (summary content)
+       |                                  |
+  getContainer()                   getSummary() / getNotes() / getActionItems()
+       |                                  |
+       v                                  v
+  PragyaContainerResponse          Encrypted JWE content
+  (summaryData, encryptionKeyUrl)         |
+                                          v
+                                   KMS Decryption
+                                   (internal-plugin-encryption)
+                                          |
+                                          v
+                                   Decrypted plaintext (HTML)
+```
+
+**Note:** The Pragya API returns summary URLs nested under `summaryData.data`. The `getContainer()` method normalizes this automatically, flattening `summaryData.data` into `summaryData` so consumers can access `summaryData.summaryUrl` directly.
+
+## Registration
+
+The plugin registers itself as `aisummary` on the internal namespace:
+
+```typescript
+import '@webex/internal-plugin-call-ai-summary';
+
+// Accessed via:
+webex.internal.aisummary.getContainer({ containerId: '...' });
+```
+
+## Source Files
+
+| File | Description |
+|------|-------------|
+| `src/index.ts` | Entry point. Registers the plugin via `registerInternalPlugin('aisummary', ...)`. |
+| `src/ai-summary.ts` | Main plugin class extending `WebexPlugin`. Contains all public and private methods. |
+| `src/types.ts` | TypeScript interfaces for request/response DTOs. |
+| `src/constants.ts` | Service name, resource path, and error message constants. |
+| `src/config.ts` | Plugin configuration (currently empty). |
+
+## API Reference
+
+### `getContainer(options: GetContainerOptions): Promise<PragyaContainerResponse>`
+
+Resolves a Pragya container by ID. Returns container metadata including summary URLs and the KMS encryption key URL. Normalizes the response by flattening `summaryData.data` into `summaryData`.
+
+```typescript
+const container = await webex.internal.aisummary.getContainer({
+  containerId: '34125120-13b5-11f1-9b36-adb685725098',
+});
+
+// After normalization, URLs are directly on summaryData:
+console.log(container.summaryData.summaryUrl);    // https://aibridge-.../summaries/...
+console.log(container.summaryData.transcriptUrl); // https://aibridge-.../transcripts/...
+```
+
+**Request**: `GET {pragya-service}/containers/{containerId}`
+
+**Response fields**:
+- `summaryData` — Contains summary URLs (`summaryUrl`, `transcriptUrl`, `status`, `summarizeAfterCall`)
+- `encryptionKeyUrl` — KMS key URL for decrypting content (e.g., `kms://kms-aore.wbx2.com/keys/...`)
+- `kmsResourceObjectUrl`, `aclUrl`, `forkSessionId`, `callSessionId`, `ownerUserId`, `orgId`, `start`, `end`
+
+### `getSummary(options: GetSummaryContentOptions): Promise<SummaryContent>`
+
+Fetches all AI-generated summary content (note, short note, and action items) from a single request to the summary URL, and decrypts each field via KMS. This is the primary method for retrieving summary content.
+
+```typescript
+const summary = await webex.internal.aisummary.getSummary({
+  containerInfo: container,
+});
+
+console.log(summary.note);        // Decrypted full note (HTML)
+console.log(summary.shortNote);   // Decrypted short note (HTML)
+console.log(summary.actionItems); // Array of decrypted action item snippets
+console.log(summary.feedbackUrl); // Feedback URL from links (if available)
+```
+
+**Request**: `GET {summaryUrl}?fields=note,shortnote,actionitems`
+
+**Response structure** (from AI Bridge, before decryption):
+```json
+{
+  "id": "...",
+  "keyUrl": "kms://...",
+  "note": { "aiGeneratedContent": "<JWE>" },
+  "shortnote": { "aiGeneratedContent": "<JWE>" },
+  "actionitems": {
+    "snippets": [
+      { "id": "...", "aiGeneratedContent": "<JWE>" }
+    ]
+  },
+  "links": [
+    { "rel": "feedback", "href": "https://..." }
+  ]
+}
+```
+
+**Return type** (`SummaryContent`):
+- `id` — Summary identifier
+- `note` — Decrypted full note (HTML string)
+- `shortNote` — Decrypted short note (HTML string)
+- `actionItems` — Array of `ActionItemSnippet` objects
+- `feedbackUrl` — Extracted from `links` array (`rel: "feedback"`), if available
+
+### `getNotes(options: GetSummaryContentOptions): Promise<SummaryNotes>`
+
+Fetches AI-generated notes from the dedicated notes endpoint and decrypts via KMS. Requires `notesUrl` to be present in the container's `summaryData`.
+
+```typescript
+const notes = await webex.internal.aisummary.getNotes({
+  containerInfo: container,
+});
+
+console.log(notes.content); // Decrypted notes content
+```
+
+**Request**: `GET {notesUrl}`
+
+> **Note:** The `notesUrl` may not be present in all API versions. Prefer `getSummary()` which returns notes, short notes, and action items in a single call.
+
+### `getActionItems(options: GetSummaryContentOptions): Promise<SummaryActionItems>`
+
+Fetches AI-generated action items from the dedicated action items endpoint and decrypts each snippet via KMS. Requires `actionItemsUrl` to be present in the container's `summaryData`.
+
+```typescript
+const actionItems = await webex.internal.aisummary.getActionItems({
+  containerInfo: container,
+});
+
+actionItems.snippets.forEach((item) => {
+  console.log(item.aiGeneratedContent); // Decrypted action item
+});
+```
+
+**Request**: `GET {actionItemsUrl}`
+
+> **Note:** The `actionItemsUrl` may not be present in all API versions. Prefer `getSummary()` which returns notes, short notes, and action items in a single call.
+
+### `getTranscriptUrl(options: GetSummaryContentOptions): string`
+
+Returns the transcript URL from the container info. Does not fetch or decrypt content.
+
+```typescript
+const transcriptUrl = webex.internal.aisummary.getTranscriptUrl({
+  containerInfo: container,
+});
+```
+
+## Types
+
+### Request Types
+
+```typescript
+interface GetContainerOptions {
+  containerId: string; // Pragya container ID
+}
+
+interface GetSummaryContentOptions {
+  containerInfo: PragyaContainerResponse; // Resolved container from getContainer()
+}
+```
+
+### Response Types
+
+```typescript
+interface PragyaContainerResponse {
+  summaryData: PragyaSummaryData;
+  encryptionKeyUrl: string;
+  kmsResourceObjectUrl: string;
+  aclUrl: string;
+  forkSessionId: string;
+  callSessionId: string;
+  ownerUserId: string;
+  orgId: string;
+  start: string;
+  end: string;
+}
+
+interface PragyaSummaryData {
+  status: string;
+  summaryUrl: string;
+  transcriptUrl: string;
+  summarizeAfterCall: boolean;
+  notesUrl?: string;       // May not be present in all API versions
+  actionItemsUrl?: string; // May not be present in all API versions
+}
+
+interface SummaryContent {
+  id: string;
+  note: string;           // Decrypted full note (HTML)
+  shortNote: string;      // Decrypted short note (HTML)
+  actionItems: ActionItemSnippet[];
+  feedbackUrl?: string;   // From links array (rel="feedback")
+}
+
+interface SummaryNotes {
+  id: string;
+  content: string;        // Decrypted notes content
+  feedbackUrl?: string;
+}
+
+interface SummaryActionItems {
+  id: string;
+  snippets: ActionItemSnippet[];
+  feedbackUrl?: string;
+}
+
+interface ActionItemSnippet {
+  id: string;
+  editedContent?: string;      // User-edited version (if available)
+  aiGeneratedContent: string;  // Decrypted AI-generated content
+}
+```
+
+## Error Handling
+
+The plugin normalizes HTTP errors into descriptive messages:
+
+| Status Code | Error Message |
+|-------------|---------------|
+| 401 | `Authentication failed: Invalid or expired token` |
+| 403 | `Access denied: User not authorized to view this summary` |
+| 404 | `Container not found` |
+| Other | `{methodName} failed: {error.message}` |
+
+Validation errors are thrown synchronously:
+- Missing or empty `containerId` throws `containerId is required and must be a non-empty string`
+- Missing `containerInfo`, `summaryData` URL, or `encryptionKeyUrl` throws `containerInfo with valid summaryData and encryptionKeyUrl is required`
+
+## Encryption / Decryption
+
+All AI-generated content from the AI Bridge service is JWE-encrypted. Decryption uses:
+
+```
+webex.internal.encryption.decryptText(encryptionKeyUrl, encryptedContent)
+```
+
+This requires:
+1. A registered device (`webex.internal.device.register()`)
+2. Mercury WebSocket connection (initiated automatically during KMS key fetch)
+3. ECDHE key exchange with KMS
+4. Key retrieval from KMS using the `encryptionKeyUrl`
+
+The SDK handles steps 1-4 automatically when `decryptText` is called.
+
+## Dependencies
+
+- `@webex/webex-core` — Base plugin class, request handling, auth interceptor
+- `@webex/internal-plugin-encryption` — KMS decryption
+
+## Token Requirements
+
+The Pragya and AI Bridge APIs require a valid Webex access token. The SDK's auth interceptor automatically attaches the token for URLs in the service catalog or on allowed domains (e.g., `wbx2.com`, `webex.com`).
+
+## Manual Testing
+
+Two manual test scripts are provided in `src/`:
+
+### `manual-pragya-api-test.js`
+Validates the Pragya container response structure (34 checks).
+
+```bash
+cd packages/@webex/internal-plugin-call-ai-summary
+WEBEX_TOKEN='<token>' node src/manual-pragya-api-test.js
+```
+
+### `manual-integration-test.js`
+Tests the full end-to-end flow using the SDK service catalog:
+1. Device registration (WDM) to populate the service catalog
+2. `getContainer` via plugin (resolves `service: 'pragya'` from the catalog)
+3. `getSummary` via plugin (fetches + decrypts note, short note, and action items via KMS)
+4. `getTranscriptUrl` via plugin
+5. Transcript content fetch
+
+```bash
+cd packages/@webex/internal-plugin-call-ai-summary
+WEBEX_TOKEN='<token>' CONTAINER_ID='<id>' node src/manual-integration-test.js
+```
+
+Both scripts require a valid Webex access token. Set `WEBEX_TOKEN` and optionally `CONTAINER_ID` as environment variables, or update the placeholder values in the scripts.