@microsoft/omnichannel-chat-sdk 1.11.9-main.e47a43c → 2.0.0-main.307c235

package/README.md

@@ -2,12 +2,12 @@
 
 [![npm version](https://badge.fury.io/js/%40microsoft%2Fomnichannel-chat-sdk.svg)](https://badge.fury.io/js/%40microsoft%2Fomnichannel-chat-sdk)
 [![install size](https://packagephobia.com/badge?p=@microsoft/omnichannel-chat-sdk)](https://packagephobia.com/result?p=@microsoft/omnichannel-chat-sdk)
-![Release CI](https://github.com/microsoft/omnichannel-chat-sdk/workflows/Release%20CI/badge.svg)
+[![npm Release](https://github.com/microsoft/omnichannel-chat-sdk/actions/workflows/npm-release.yml/badge.svg)](https://github.com/microsoft/omnichannel-chat-sdk/actions/workflows/npm-release.yml)
 ![npm](https://img.shields.io/npm/dm/@microsoft/omnichannel-chat-sdk)
 
-> ❗ We recommend using official release versions in production as listed [here](#releases). Support will be provided only on official versions.
-
-> 📢 Try out our new React component library [omnichannel-chat-widget](https://github.com/microsoft/omnichannel-chat-widget) with Chat SDK
+> [!IMPORTANT]
+> * We recommend using official release versions in production as listed [here](#releases). Support will be provided only on official versions.
+> * Microsoft provides this SDK to ensure a scaleable and secure use of our platform. Do not directly access the APIs used in this repository — you may experience breaking changes, and we will not be able to provide support for any issues.
 
 Headless Chat SDK to build your own chat widget against Dynamics 365 Omnichannel Services.
 
@@ -22,6 +22,7 @@ Please make sure you have a chat widget configured before using this package or
 - [SDK Methods](#sdk-methods)
   - [Initialization](#initialization)
   - [Start Chat](#start-chat)
+  - [Authenticate Chat](#authenticate-chat)
   - [End Chat](#end-chat)
   - [Get Pre-Chat Survey](#get-pre-chat-survey)
   - [Get Live Chat Config](#get-live-chat-config)
@@ -34,6 +35,7 @@ Please make sure you have a chat widget configured before using this package or
   - [Get Messages](#get-messages)
   - [Send Messages](#send-messages)
   - [On New Message](#on-new-message)
+  - [On Streaming Message](#on-streaming-message)
   - [On Typing Event](#on-typing-event)
   - [On Agent End Session](#on-agent-end-session)
   - [Send Typing Event](#send-typing-event)
@@ -44,6 +46,9 @@ Please make sure you have a chat widget configured before using this package or
   - [Create Chat Adapter](#create-chat-adapter)
   - [Get Voice & Video Calling](#get-voice--video-calling)
   - [Get Post Chat Survey Context](#get-post-chat-survey-context)
+  - [Get Persistent Chat History](#get-persistent-chat-history)
+  - [Send Read Receipt](#send-read-receipt)
+  - [Get Unread Message Count](#get-unread-message-count)
 - [Common Scenarios](#common-scenarios)
   - [Using BotFramework-WebChat](#using-botframework-webchat)
   - [Escalation to Voice & Video](#escalation-to-voice--video)
@@ -52,9 +57,10 @@ Please make sure you have a chat widget configured before using this package or
   - [Reconnect to existing Chat](#reconnect-to-existing-chat)
   - [Authenticated Chat](#authenticated-chat)
   - [Persistent Chat](#persistent-chat)
+  - [Persistent Chat History](#persistent-chat-history)
   - [Chat Reconnect with Authenticated User](#chat-reconnect-with-authenticated-user)
   - [Chat Reconnect with Unauthenticated User](#chat-reconnect-with-unauthenticated-user)
-  - [Best Practices for Chat Session Management: Handling Disconnections and Network Instabilit(#best-practices-for-chat-session-management:-handling-disconnections-and-network-instability)
+  - [Best Practices for Chat Session Management: Handling Disconnections and Network Instability](#best-practices-for-chat-session-management-handling-disconnections-and-network-instability)
   - [Operating Hours](#operating-hours)
   - [Single Sign-on for Bots](/docs/scenarios/SINGLE_SIGN_ON_FOR_BOTS.md)
 - [Sample Apps](https://github.com/microsoft/omnichannel-chat-sdk-samples)
@@ -104,22 +110,39 @@ Omnichannel offers a live chat widget (LCW) by default. You can use the Chat SDK
 
 New releases are published on a regular basis to ensure the product quality.
 
-for a detailed tracking of the releases, please refer to the [Changelog document](https://github.com/microsoft/omnichannel-chat-sdk/blob/main/CHANGELOG.md)
-
-_**Important Note:**_ Versions below 1.11.0 will not be supported after November 1st, 2025. Please update to recent versions to ensure you have the latest features and bug fixes.
+For a detailed tracking of the releases, please refer to the [Changelog document](https://github.com/microsoft/omnichannel-chat-sdk/blob/main/CHANGELOG.md)
 
+_**Important Note:**_ Versions below 1.11.0 are no longer supported after November 1st, 2025. Please update to recent versions to ensure you have the latest features and bug fixes.
 
 | Version | Docs | Release Date | End of Support | Deprecated |
 | -- | -- | -- | -- | -- |
+| 2.0.0 | [Migration Guide](docs/MIGRATION_2.0.md) / [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v2.0.0) | Aug 13th 2026 | Aug 13th 2027 | |
 | 1.11.4 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.4) | Jul 17th 2025 | Jul 17th 2026 | |
 | 1.11.3 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.3) | Jul 14th 2025 | Jul 14th 2026 | |
 | 1.11.2 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.2) | Jun 24th 2025 | Jun 24th 2026 | |
 | 1.11.1 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.1) | Jun 5th 2025 | Jun 5th 2026 | |
 | 1.11.0 | [Release Notes](https://github.com/microsoft/omnichannel-chat-sdk/releases/tag/v1.11.0) | May 27th 2025 | May 27th 2026 | |
 
+### Upgrade to 2.0.0
+
+Version `2.0.0` requires Node.js `>=22.12.0`. This requirement also applies to the official OC SDK and AMS client dependencies.
+
+```bash
+npm install @microsoft/omnichannel-chat-sdk@2.0.0 --save-exact
+```
+
+The npm `latest` dist-tag can point to a `main` prerelease. Use the exact version for production.
+
+Regenerate the application lockfile after the update. Then run the application build and tests on Node.js 22.
+
+Version `2.0.0` adds progressive bot-message streaming, mid-conversation authentication, read receipts, and unread-message counts. Existing `onNewMessage` handlers continue to receive final streaming messages.
+
+See the [2.0 migration guide](docs/MIGRATION_2.0.md) for the complete upgrade and validation procedure.
 
 ## Installation
 
+Node.js `>=22.12.0` is required.
+
 ```console
 npm install @microsoft/omnichannel-chat-sdk --save
 ```
@@ -308,6 +331,32 @@ const optionalParams = {
 await chatSDK.startChat(optionalParams);
 ```
 
+### Authenticate Chat
+
+It authenticates an active unauthenticated conversation. Enable optional authenticated sign-in for the workstream before you use this method.
+
+Call `initialize()` and `startChat()` before `authenticateChat()`. The first argument can be a token or an asynchronous token provider.
+
+```ts
+await chatSDK.initialize();
+await chatSDK.startChat();
+
+await chatSDK.authenticateChat(async () => {
+    const response = await fetch("https://contoso.example/token");
+    if (!response.ok) {
+        throw new Error("Token request failed");
+    }
+
+    return response.text();
+}, {
+    refreshChatToken: true
+});
+```
+
+Set `refreshChatToken` to `true` when subsequent SDK calls must use a refreshed authenticated chat token.
+
+The method throws `InvalidConversation` when no conversation is active. It throws `MidConversationAuthFailure` when token resolution or authentication fails.
+
 ### End Chat
 
 It ends the current Omnichannel conversation.
@@ -452,6 +501,38 @@ chatSDK.onNewMessage((message) => {
 }, optionalParams);
 ```
 
+### On Streaming Message
+
+It subscribes to progressive ACS bot-message updates. This API is available only for Live Chat version 2.
+
+Enable streaming when you start the conversation. Then register the handler after `startChat()` completes.
+
+```ts
+await chatSDK.initialize();
+await chatSDK.startChat({
+    supportsLcwStreaming: true
+});
+
+await chatSDK.onStreamingMessage((message) => {
+    const { streamingMessageType, streamEndReason } = message.streamingMetadata;
+
+    // Each event contains the full assembled content, not only the new text.
+    renderStreamingMessage(message.id, message.content);
+
+    if (message.policyViolation) {
+        handlePolicyViolation(message.policyViolation.result);
+    }
+
+    if (streamingMessageType === "final") {
+        completeStreamingMessage(message.id, streamEndReason);
+    }
+});
+```
+
+`streamingMessageType` can be `start`, `informative`, `streaming`, or `final`. A final message also reaches existing `onNewMessage` handlers.
+
+Calling this method before `startChat()` throws `UninitializedConversation`. Calling it for another Live Chat version throws `UnsupportedLiveChatVersion`.
+
 ### On Typing Event
 
 It subscribes to an agent typing event.
@@ -579,6 +660,24 @@ It gets the participant type that should be used for the survey and both the def
 const postChatSurveyContext = await chatSDK.getPostChatSurveyContext();
 ```
 
+### Get Persistent Chat History
+
+It fetches paginated chat history from previous persistent chat conversations for authenticated users. Returns messages in chronological order along with a pagination token to fetch the next page.
+
+> :warning: Requires **persistent chat** to be enabled and the user must be **authenticated**.
+
+```ts
+const optionalParams = {
+    pageSize: 25, // Number of messages per page (optional)
+    pageToken: '' // Token from a previous response to fetch the next page (optional, omit for first call)
+};
+
+const response = await chatSDK.getPersistentChatHistory(optionalParams);
+
+// response.chatMessages: PersistentChatHistoryMessage[] — Array of chat messages
+// response.nextPageToken: string | null — Token to pass in the next call; null means no more history
+```
+
 ### Get Agent Availability
 
 It gets information on whether a queue is available, and whether there are agents available in that queue, as well as queue position and average wait time. This call only supports authenticated chat.
@@ -587,6 +686,27 @@ It gets information on whether a queue is available, and whether there are agent
 const agentAvailability = await chatSDK.getAgentAvailability();
 ```
 
+### Send Read Receipt
+
+Logs a particular message (and all previous messages) as read by the user. Read indicators will appear for Contact Center Representatives and Admins in the Admin Center.
+
+Authenticated chat sends the receipt through Messaging Runtime. Unauthenticated chat sends it through ACS and requires Live Chat version 2.
+
+```ts
+await chatSDK.sendReadReceipt(messageId: string);
+```
+
+### Get Unread Message Count
+
+Returns unread-message data for an authenticated user. An active chat session is not required. This call is **authenticated-only** — the user must be authenticated, otherwise an `UndefinedAuthToken` error is thrown.
+
+```ts
+const response = await chatSDK.getUnreadMessageCount();
+
+// response.unreadMessageCount: number — Number of unread messages in the conversation
+// response.mostRecentUnreadMessage: object | null — The most recent unread message, or null if there are none
+```
+
 ## Common Scenarios
 
 ### Pre-Chat Survey
@@ -735,6 +855,200 @@ await chatSDK.initialize();
 // from this point, this acts like a persistent chat
 ```
 
+### Persistent Chat History
+
+> See <https://docs.microsoft.com/en-us/dynamics365/customer-service/persistent-chat> on how to set up persistent chat
+
+When persistent chat is enabled, you can retrieve the chat history from previous conversations using `getPersistentChatHistory()`. This method returns paginated results, allowing you to load history incrementally (e.g., as the user scrolls up).
+
+> :warning: **Prerequisites:**
+> - Persistent chat must be **enabled** in the admin portal (conversation mode set to Persistent Chat) and in the SDK config (`persistentChat.disable: false`)
+> - The user must be **authenticated** (`getAuthToken` must be configured)
+> - `chatSDK.initialize()` and `chatSDK.startChat()` must be called before fetching history
+> - Chat history is available for up to **12 months**
+
+#### Page Size
+
+The `pageSize` parameter controls how many messages are returned per call.
+
+| | Value |
+| --- | --- |
+| **Default** | `50` (used when `pageSize` is omitted) |
+| **Minimum** | `1` |
+| **Maximum** | `100` |
+
+If `pageSize` is not provided, the backend defaults to **50**. Values outside the 1–100 range will be rejected with an error.
+
+#### How Pagination Works
+
+| Call | `pageToken` param | What happens |
+| --- | --- | --- |
+| **First call** | Omit or `undefined` | Fetches the most recent page of messages. The response includes `nextPageToken` if older messages exist. |
+| **Subsequent calls** | Pass the `nextPageToken` from the previous response | Fetches the next (older) page. Again returns `nextPageToken` if more messages remain. |
+| **Last page** | Pass the `nextPageToken` from the previous response | Returns the remaining messages. `nextPageToken` is `null`, indicating there are no more messages in the history. |
+
+In short: keep passing the `nextPageToken` from each response into the next call until the backend returns `nextPageToken: null` — that signals the entire history has been retrieved.
+
+#### Basic Usage
+
+```ts
+const chatSDKConfig = {
+    persistentChat: {
+        disable: false,
+        tokenUpdateTime: 21600000
+    },
+    getAuthToken: async () => {
+        const response = await fetch("http://contosohelp.com/token");
+        if (response.ok) {
+            return await response.text();
+        }
+        else {
+            return null
+        }
+    }
+}
+
+const chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, chatSDKConfig);
+await chatSDK.initialize();
+
+await chatSDK.startChat();
+
+// Fetch the first page of chat history
+const history = await chatSDK.getPersistentChatHistory({
+    pageSize: 25
+});
+
+if (history) {
+    // Render messages
+    history.chatMessages.forEach((message) => {
+        console.log(`[${message.createdDateTime}] ${message.content}`);
+    });
+
+    // Check if more history is available
+    if (history.nextPageToken) {
+        console.log("More history available");
+    }
+}
+```
+
+#### Pagination — Loading More History on Scroll Up
+
+After the first call returns a `nextPageToken`, you can fetch older pages on demand — for example, each time the customer scrolls up in the chat window. The loop below shows fetching all remaining history, but in practice you would call `getPersistentChatHistory` once per scroll-up action, passing the `nextPageToken` from the previous response.
+
+```ts
+// After the first call (Basic Usage above), save the nextPageToken
+let pageToken: string | undefined = history?.nextPageToken ?? undefined;
+
+// Example: fetch the next page when the customer scrolls up
+const loadMoreHistory = async () => {
+    if (!pageToken) {
+        console.log("No more history to load");
+        return;
+    }
+
+    const response = await chatSDK.getPersistentChatHistory({
+        pageSize: 25,
+        pageToken
+    });
+
+    if (response && response.chatMessages.length > 0) {
+        // Render the older messages in the chat UI
+        response.chatMessages.forEach((message) => {
+            console.log(`[${message.createdDateTime}] ${message.content}`);
+        });
+
+        // Update the token for the next scroll-up action
+        pageToken = response.nextPageToken ?? undefined;
+    }
+};
+
+// Bind to your scroll-up event (e.g., user reaches the top of the chat container)
+chatContainer.addEventListener('scroll', () => {
+    if (chatContainer.scrollTop === 0) {
+        loadMoreHistory();
+    }
+});
+```
+
+Alternatively, to fetch all history at once in a loop:
+
+```ts
+let token: string | undefined = history?.nextPageToken ?? undefined;
+let allMessages = [...(history?.chatMessages ?? [])];
+
+while (token) {
+    const response = await chatSDK.getPersistentChatHistory({
+        pageSize: 25,
+        pageToken: token
+    });
+
+    if (response && response.chatMessages.length > 0) {
+        allMessages = [...allMessages, ...response.chatMessages];
+        token = response.nextPageToken ?? undefined;
+    } else {
+        break;
+    }
+}
+
+console.log(`Total messages retrieved: ${allMessages.length}`);
+```
+
+#### Response Shape
+
+The response type is exported from the SDK and can be imported for TypeScript usage:
+
+```ts
+import { GetPersistentChatHistoryResponse } from '@microsoft/omnichannel-chat-sdk';
+```
+
+```ts
+type GetPersistentChatHistoryResponse = {
+    chatMessages: PersistentChatHistoryMessage[];
+    nextPageToken: string | null; // null when no more pages
+}
+
+type PersistentChatHistoryMessage = {
+    content: string;                  // Message text
+    contentType: number;              // Content type identifier
+    createdDateTime: string;          // ISO 8601 timestamp
+    from: {
+        application: {                // Sender application info
+            displayName: string;      // e.g., agent name or bot name
+            id: string;
+        } | null;
+    };
+    id: string;                       // Unique message identifier
+    attachments: unknown[];           // File attachments if any
+    additionalData: {
+        deliveryMode: string;         // Delivery channel
+        ConversationId: string;       // Conversation the message belongs to
+        tags: string;                 // Message tags
+    };
+}
+```
+
+#### Error Handling
+
+```ts
+try {
+    const history = await chatSDK.getPersistentChatHistory({ pageSize: 25 });
+    // Process messages...
+} catch (error) {
+    if (error.message === 'ChatSDKNotInitialized') {
+        // SDK not initialized — call chatSDK.initialize() first
+    }
+    if (error.message === 'PersistentChatNotEnabled') {
+        // Persistent chat is not enabled for this widget
+    }
+    if (error.message === 'AuthenticatedUserTokenNotFound') {
+        // User is not authenticated — configure getAuthToken
+    }
+    if (error.message === 'PersistentChatConversationRetrievalFailure') {
+        // Server error fetching history — retry or handle gracefully
+    }
+}
+```
+
 ### Chat Reconnect with Authenticated User
 
 > See <https://docs.microsoft.com/en-us/dynamics365/customer-service/configure-reconnect-chat?tabs=customerserviceadmincenter#enable-reconnection-to-a-previous-chat-session> on how to set up chat reconnect
@@ -1088,11 +1402,11 @@ const chatSDK = new OmnichannelChatSDK.OmnichannelChatSDK(omnichannelConfig, cha
 await chatSDK.initialize();
 ```
 
-# Releasing
+## Releasing
 
-See [docs/RELEASING.md](docs/RELEASING.md) for how to publish new versions to npm.
+See [docs/RELEASING.md](docs/RELEASING.md) for development builds, official npm and GitHub releases, release notes, and hotfixes.
 
-# Contributing
+## Contributing
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us

package/lib/OmnichannelChatSDK.d.ts

@@ -30,7 +30,9 @@ import InitializeOptionalParams from "./core/InitializeOptionalParams";
 import LiveWorkItemDetails from "./core/LiveWorkItemDetails";
 import OmnichannelConfig from "./core/OmnichannelConfig";
 import OmnichannelMessage from "./core/messaging/OmnichannelMessage";
+import OmnichannelStreamingMessage from "./core/messaging/OmnichannelStreamingMessage";
 import OnNewMessageOptionalParams from "./core/messaging/OnNewMessageOptionalParams";
+import OnStreamingMessageOptionalParams from "./core/messaging/OnStreamingMessageOptionalParams";
 import PostChatContext from "./core/PostChatContext";
 import StartChatOptionalParams from "./core/StartChatOptionalParams";
 declare class OmnichannelChatSDK {
@@ -171,7 +173,36 @@ declare class OmnichannelChatSDK {
     sendMessage(message: ChatSDKMessage): Promise<OmnichannelMessage | void>;
     onNewMessage(onNewMessageCallback: CallableFunction, optionalParams?: OnNewMessageOptionalParams): Promise<void>;
     sendTypingEvent(): Promise<void>;
+    /**
+     * Fetches unread message count for the authenticated user.
+     * Auth-only — does not require an active chat session.
+     */
+    getUnreadMessageCount(): Promise<object>;
+    /**
+     * Sends a read receipt for a specific message.
+     * Authenticated: calls MRT (updates NRD + forwards to ACS).
+     * Unauthenticated: calls ACS directly.
+     */
+    sendReadReceipt(messageId: string): Promise<void>;
     onTypingEvent(onTypingEventCallback: CallableFunction): Promise<void>;
+    /**
+     * Subscribes to ACS-driven streaming message chunks for progressive bot message rendering.
+     * Each chunk contains the full assembled text so far (not just the delta).
+     * Existing onNewMessage consumers continue receiving final messages without changes.
+     *
+     * Available only in LiveChatVersion.V2. Must call startChat() before registering.
+     *
+     * @param onStreamingMessageCallback - Called for each streaming chunk
+     * @param optionalParams - Reserved for future configuration
+     * @example
+     * chatSDK.onStreamingMessage((message) => {
+     *     switch (message.streamingMetadata.streamingMessageType) {
+     *         case "streaming": // Update bubble with message.content
+     *         case "final":     // Stream complete
+     *     }
+     * });
+     */
+    onStreamingMessage(onStreamingMessageCallback: (message: OmnichannelStreamingMessage) => void, optionalParams?: OnStreamingMessageOptionalParams): Promise<void>;
     onAgentEndSession(onAgentEndSessionCallback: (message: IRawThread | ParticipantsRemovedEvent) => void): Promise<void>;
     uploadFileAttachment(fileInfo: IFileInfo | File): Promise<UploadFileAttachmentResponse>;
     downloadFileAttachment(fileMetadata: FileMetadata | IFileMetadata): Promise<Blob>;
@@ -198,6 +229,13 @@ declare class OmnichannelChatSDK {
     private setCallingOptionConfiguration;
     private setLiveChatVersionConfiguration;
     private setWidgetSnippetBaseUrl;
+    /**
+     * Creates diagnostic data for getChatConfig errors using the error classifier
+     * @param e The error object
+     * @param clientElapsedMs Optional elapsed time in milliseconds from client's perspective
+     * @returns Diagnostic data with clientElapsedMs, online status, and cancellation reason
+     */
+    private createGetChatConfigDiagnosticData;
     private getChatConfig;
     private buildConfigurations;
     private resolveIC3ClientUrl;