@microsoft/omnichannel-chat-sdk 2.0.0-main.b82e941 → 2.0.0-main.be72877

package/README.md

@@ -2,7 +2,7 @@
 
 [![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)
 
 > [!IMPORTANT]
@@ -34,6 +34,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)
@@ -112,18 +113,35 @@ For a detailed tracking of the releases, please refer to the [Changelog document
 
 _**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, 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
 ```
@@ -456,6 +474,38 @@ chatSDK.onNewMessage((message) => {
 }, optionalParams);
 ```
 
+### On Streaming Message
+
+It subscribes to progressive ACS bot-message updates.
+
+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`. If the conversation does not use ACS, this method throws `UnsupportedLiveChatVersion`.
+
 ### On Typing Event
 
 It subscribes to an agent typing event.
@@ -613,13 +663,15 @@ const agentAvailability = await chatSDK.getAgentAvailability();
 
 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 the receipt through ACS.
+
 ```ts
 await chatSDK.sendReadReceipt(messageId: string);
 ```
 
 ### Get Unread Message Count
 
-Returns the number of unread messages in an authenticated persistent conversation. This call is **authenticated-only** — the user must be authenticated, otherwise an `UndefinedAuthToken` error is thrown.
+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();
@@ -1323,11 +1375,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.js

@@ -109,6 +109,7 @@ var startPolling_1 = require("./commands/startPolling");
 var stopPolling_1 = require("./commands/stopPolling");
 var urlResolvers_1 = require("./utils/urlResolvers");
 var OmnichannelConfigValidator_1 = require("./validators/OmnichannelConfigValidator");
+var prefetchedConfigValidator_1 = require("./validators/prefetchedConfigValidator");
 var OmnichannelChatSDK = /** @class */ (function () {
     function OmnichannelChatSDK(omnichannelConfig, chatSDKConfig) {
         if (chatSDKConfig === void 0) { chatSDKConfig = SDKConfigValidators_1.defaultChatSDKConfig; }
@@ -1281,10 +1282,10 @@ var OmnichannelChatSDK = /** @class */ (function () {
     };
     OmnichannelChatSDK.prototype.closeChat = function (endChatOptionalParams) {
         return __awaiter(this, void 0, void 0, function () {
-            var cleanupMetadata, sessionCloseOptionalParams, isReconnectChat, isChatReconnect, error_14;
-            var _a, _b;
-            return __generator(this, function (_c) {
-                switch (_c.label) {
+            var cleanupMetadata, sessionCloseOptionalParams, sessionCloseRequestId, isReconnectChat, isChatReconnect, error_14;
+            var _a, _b, _c, _d, _e, _f;
+            return __generator(this, function (_g) {
+                switch (_g.label) {
                     case 0:
                         cleanupMetadata = {
                             RequestId: this.requestId,
@@ -1294,34 +1295,43 @@ var OmnichannelChatSDK = /** @class */ (function () {
                         // in case a session was ended by agent or disconnected, there is no need to close the session
                         this.scenarioMarker.startScenario(TelemetryEvent_1.default.CloseChatSession, cleanupMetadata);
                         if (!!(endChatOptionalParams === null || endChatOptionalParams === void 0 ? void 0 : endChatOptionalParams.isSessionEnded)) return [3 /*break*/, 5];
-                        _c.label = 1;
+                        _g.label = 1;
                     case 1:
-                        _c.trys.push([1, 3, , 4]);
+                        _g.trys.push([1, 3, , 4]);
                         sessionCloseOptionalParams = {};
+                        sessionCloseRequestId = this.requestId;
                         if (this.isPersistentChat && !((_a = this.chatSDKConfig.persistentChat) === null || _a === void 0 ? void 0 : _a.disable)) {
                             isReconnectChat = this.reconnectId !== null ? true : false;
                             sessionCloseOptionalParams.isPersistentChat = this.isPersistentChat;
                             sessionCloseOptionalParams.isReconnectChat = isReconnectChat;
+                            if ((0, parsers_1.parseLowerCaseString)((_c = (_b = this.liveChatConfig) === null || _b === void 0 ? void 0 : _b.LiveWSAndLiveChatEngJoin) === null || _c === void 0 ? void 0 : _c.msdyn_enablecustomerclosepersistentchat) === "true" &&
+                                isReconnectChat &&
+                                typeof this.reconnectId === "string" &&
+                                this.reconnectId.length > 0 &&
+                                (0, parsers_1.parseLowerCaseString)((_e = (_d = this.liveChatConfig) === null || _d === void 0 ? void 0 : _d.LcwFcbConfiguration) === null || _e === void 0 ? void 0 : _e.lcwPersistentChatCustomerEndEnabled) === "true") {
+                                sessionCloseRequestId = this.reconnectId;
+                            }
                         }
-                        if (this.isChatReconnect && !((_b = this.chatSDKConfig.chatReconnect) === null || _b === void 0 ? void 0 : _b.disable) && !this.isPersistentChat) {
+                        if (this.isChatReconnect && !((_f = this.chatSDKConfig.chatReconnect) === null || _f === void 0 ? void 0 : _f.disable) && !this.isPersistentChat) {
                             isChatReconnect = this.reconnectId !== null ? true : false;
                             this.requestId = isChatReconnect ? this.reconnectId : this.requestId; // Chat Reconnect session to close
+                            sessionCloseRequestId = this.requestId;
                             sessionCloseOptionalParams.isReconnectChat = isChatReconnect;
                         }
                         if (this.authenticatedUserToken) {
                             sessionCloseOptionalParams.authenticatedUserToken = this.authenticatedUserToken;
                         }
-                        return [4 /*yield*/, this.OCClient.sessionClose(this.requestId, sessionCloseOptionalParams)];
+                        return [4 /*yield*/, this.OCClient.sessionClose(sessionCloseRequestId, sessionCloseOptionalParams)];
                     case 2:
-                        _c.sent();
+                        _g.sent();
                         return [3 /*break*/, 4];
                     case 3:
-                        error_14 = _c.sent();
+                        error_14 = _g.sent();
                         exceptionThrowers_1.default.throwConversationClosureFailure(error_14, this.scenarioMarker, TelemetryEvent_1.default.CloseChatSession, __assign(__assign({}, cleanupMetadata), { isSessionEnded: String(!(endChatOptionalParams === null || endChatOptionalParams === void 0 ? void 0 : endChatOptionalParams.isSessionEnded)) }));
                         return [3 /*break*/, 4];
                     case 4:
                         this.scenarioMarker.completeScenario(TelemetryEvent_1.default.CloseChatSession, cleanupMetadata);
-                        _c.label = 5;
+                        _g.label = 5;
                     case 5: return [2 /*return*/];
                 }
             });
@@ -3395,53 +3405,95 @@ var OmnichannelChatSDK = /** @class */ (function () {
     };
     OmnichannelChatSDK.prototype.getChatConfig = function () {
         return __awaiter(this, arguments, void 0, function (optionalParams) {
-            var sendCacheHeaders, bypassCache, liveChatConfig, startTime, error_30, clientElapsedMs, _a;
-            var _b, _c;
+            var sendCacheHeaders, _a, prefetchedLiveChatConfig, prefetchedConfigAttestation, bypassCache, prefetchAttempted, prefetchResult, prefetchError_1, liveChatConfig, startTime, error_30, clientElapsedMs, _b;
+            var _c, _d;
             if (optionalParams === void 0) { optionalParams = {}; }
-            return __generator(this, function (_d) {
-                switch (_d.label) {
+            return __generator(this, function (_e) {
+                switch (_e.label) {
                     case 0:
                         sendCacheHeaders = optionalParams.sendCacheHeaders;
+                        _a = optionalParams, prefetchedLiveChatConfig = _a.prefetchedLiveChatConfig, prefetchedConfigAttestation = _a.prefetchedConfigAttestation;
                         bypassCache = sendCacheHeaders === true;
-                        startTime = typeof performance !== 'undefined' ? performance.now() : undefined;
-                        _d.label = 1;
+                        prefetchAttempted = prefetchedLiveChatConfig !== undefined && prefetchedLiveChatConfig !== null;
+                        if (!prefetchAttempted) return [3 /*break*/, 5];
+                        _e.label = 1;
                     case 1:
-                        _d.trys.push([1, 3, , 8]);
-                        return [4 /*yield*/, this.OCClient.getChatConfig(this.requestId, bypassCache)];
+                        _e.trys.push([1, 4, , 5]);
+                        prefetchResult = (0, prefetchedConfigValidator_1.default)(prefetchedLiveChatConfig, prefetchedConfigAttestation, { orgId: this.omnichannelConfig.orgId, widgetId: this.omnichannelConfig.widgetId }, bypassCache, this.omnichannelConfig.orgUrl);
+                        if (!prefetchResult.accepted) return [3 /*break*/, 3];
+                        // Ordered so nothing is latched from a payload we may still
+                        // reject: building the configuration is the step that can
+                        // throw, and evaluating attachment support flips a flag that
+                        // is never turned back off.
+                        return [4 /*yield*/, this.buildConfigurations(prefetchedLiveChatConfig)];
                     case 2:
-                        liveChatConfig = _d.sent();
+                        // Ordered so nothing is latched from a payload we may still
+                        // reject: building the configuration is the step that can
+                        // throw, and evaluating attachment support flips a flag that
+                        // is never turned back off.
+                        _e.sent();
+                        this.liveChatConfig = prefetchedLiveChatConfig;
+                        this.evaluateAMSAvailability();
+                        this.scenarioMarker.singleRecord(TelemetryEvent_1.default.PrefetchedLiveChatConfigUsed, {
+                            RequestId: this.requestId || ""
+                        });
+                        return [2 /*return*/, this.liveChatConfig];
+                    case 3:
+                        this.scenarioMarker.singleRecord(TelemetryEvent_1.default.PrefetchedLiveChatConfigRejected, {
+                            RequestId: this.requestId || "",
+                            ExceptionDetails: JSON.stringify({ reason: prefetchResult.reason })
+                        });
+                        return [3 /*break*/, 5];
+                    case 4:
+                        prefetchError_1 = _e.sent();
+                        // Adoption itself failed (e.g. buildConfigurations rejected the
+                        // payload). Fall through rather than surface it: the network fetch
+                        // below is the correct, working behavior.
+                        this.scenarioMarker.singleRecord(TelemetryEvent_1.default.PrefetchedLiveChatConfigRejected, {
+                            RequestId: this.requestId || "",
+                            ExceptionDetails: JSON.stringify({ reason: "Exception", error: "".concat(prefetchError_1) })
+                        });
+                        return [3 /*break*/, 5];
+                    case 5:
+                        startTime = typeof performance !== 'undefined' ? performance.now() : undefined;
+                        _e.label = 6;
+                    case 6:
+                        _e.trys.push([6, 8, , 13]);
+                        return [4 /*yield*/, this.OCClient.getChatConfig(this.requestId, bypassCache)];
+                    case 7:
+                        liveChatConfig = _e.sent();
                         this.liveChatConfig = liveChatConfig;
                         this.evaluateAMSAvailability();
                         this.buildConfigurations(liveChatConfig);
                         /* istanbul ignore next */
                         this.debug && console.log("[OmnichannelChatSDK][getChatConfig][liveChatVersion] ".concat(this.liveChatVersion));
                         return [2 /*return*/, this.liveChatConfig];
-                    case 3:
-                        error_30 = _d.sent();
+                    case 8:
+                        error_30 = _e.sent();
                         clientElapsedMs = startTime !== undefined
                             ? Math.round(performance.now() - startTime)
                             : undefined;
                         // Attach timing info to error object for outer catch blocks to use
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
                         error_30.__chatConfigElapsedMs = clientElapsedMs;
-                        if (!(0, internalUtils_1.isCoreServicesOrgUrlDNSError)(error_30, this.coreServicesOrgUrl, this.dynamicsLocationCode)) return [3 /*break*/, 6];
+                        if (!(0, internalUtils_1.isCoreServicesOrgUrlDNSError)(error_30, this.coreServicesOrgUrl, this.dynamicsLocationCode)) return [3 /*break*/, 11];
                         this.omnichannelConfig.orgUrl = this.unqServicesOrgUrl;
-                        _a = this;
+                        _b = this;
                         return [4 /*yield*/, ocsdk_1.SDKProvider.getSDK(this.omnichannelConfig, (0, createOcSDKConfiguration_1.default)(false), this.ocSdkLogger)];
-                    case 4:
-                        _a.OCClient = _d.sent();
+                    case 9:
+                        _b.OCClient = _e.sent();
                         return [4 /*yield*/, this.OCClient.getChatConfig(this.requestId, bypassCache)];
-                    case 5:
-                        liveChatConfig = _d.sent(); // Bubble up error by default to throw ChatConfigRetrievalFailure
-                        return [3 /*break*/, 7];
-                    case 6:
+                    case 10:
+                        liveChatConfig = _e.sent(); // Bubble up error by default to throw ChatConfigRetrievalFailure
+                        return [3 /*break*/, 12];
+                    case 11:
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        if (((_c = (_b = error_30.response) === null || _b === void 0 ? void 0 : _b.headers) === null || _c === void 0 ? void 0 : _c.errorcode) && parseInt(error_30.response.headers.errorcode) === OmnichannelErrorCodes_1.default.WidgetNotFound) {
+                        if (((_d = (_c = error_30.response) === null || _c === void 0 ? void 0 : _c.headers) === null || _d === void 0 ? void 0 : _d.errorcode) && parseInt(error_30.response.headers.errorcode) === OmnichannelErrorCodes_1.default.WidgetNotFound) {
                             console.warn("No widget with the given app id is present in the system.");
                         }
                         throw error_30; // Bubble up error by default to throw ChatConfigRetrievalFailure
-                    case 7: return [3 /*break*/, 8];
-                    case 8: return [2 /*return*/, this.liveChatConfig];
+                    case 12: return [3 /*break*/, 13];
+                    case 13: return [2 /*return*/, this.liveChatConfig];
                 }
             });
         });
@@ -3451,18 +3503,23 @@ var OmnichannelChatSDK = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             var dataMaskingConfig, authSettings, liveWSAndLiveChatEngJoin, liveChatVersion, chatWidgetLanguage;
             return __generator(this, function (_a) {
-                dataMaskingConfig = liveChatConfig.DataMaskingInfo, authSettings = liveChatConfig.LiveChatConfigAuthSettings, liveWSAndLiveChatEngJoin = liveChatConfig.LiveWSAndLiveChatEngJoin, liveChatVersion = liveChatConfig.LiveChatVersion, chatWidgetLanguage = liveChatConfig.ChatWidgetLanguage;
-                Promise.all([
-                    this.setDataMaskingConfiguration(dataMaskingConfig),
-                    this.setPrechatConfigurations(liveWSAndLiveChatEngJoin),
-                    this.setAuthSettingConfig(authSettings),
-                    this.setPersistentChatConfiguration(liveWSAndLiveChatEngJoin),
-                    this.setCallingOptionConfiguration(liveWSAndLiveChatEngJoin),
-                    this.setLocaleIdConfiguration(chatWidgetLanguage),
-                    this.setLiveChatVersionConfiguration(liveChatVersion),
-                    this.setWidgetSnippetBaseUrl(liveWSAndLiveChatEngJoin)
-                ]);
-                return [2 /*return*/];
+                switch (_a.label) {
+                    case 0:
+                        dataMaskingConfig = liveChatConfig.DataMaskingInfo, authSettings = liveChatConfig.LiveChatConfigAuthSettings, liveWSAndLiveChatEngJoin = liveChatConfig.LiveWSAndLiveChatEngJoin, liveChatVersion = liveChatConfig.LiveChatVersion, chatWidgetLanguage = liveChatConfig.ChatWidgetLanguage;
+                        return [4 /*yield*/, Promise.all([
+                                this.setDataMaskingConfiguration(dataMaskingConfig),
+                                this.setPrechatConfigurations(liveWSAndLiveChatEngJoin),
+                                this.setAuthSettingConfig(authSettings),
+                                this.setPersistentChatConfiguration(liveWSAndLiveChatEngJoin),
+                                this.setCallingOptionConfiguration(liveWSAndLiveChatEngJoin),
+                                this.setLocaleIdConfiguration(chatWidgetLanguage),
+                                this.setLiveChatVersionConfiguration(liveChatVersion),
+                                this.setWidgetSnippetBaseUrl(liveWSAndLiveChatEngJoin)
+                            ])];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
             });
         });
     };