@nlxai/core 1.2.3 → 1.2.4-alpha.10

package/lib/index.cjs

@@ -6,7 +6,7 @@ var ReconnectingWebSocket = require('reconnecting-websocket');
 var uuid = require('uuid');
 
 var name = "@nlxai/core";
-var version$1 = "1.2.3";
+var version$1 = "1.2.4-alpha.10";
 var description = "Low-level SDK for building NLX experiences";
 var type = "module";
 var main = "lib/index.cjs";
@@ -34,14 +34,21 @@ var scripts = {
 var author = "Peter Szerzo <peter@nlx.ai>";
 var license = "MIT";
 var devDependencies = {
+	"@rollup/plugin-commonjs": "^25.0.7",
+	"@rollup/plugin-json": "^6.0.1",
+	"@rollup/plugin-node-resolve": "^15.2.3",
+	"@rollup/plugin-replace": "^5.0.5",
+	"@rollup/plugin-terser": "^0.4.4",
+	"@rollup/plugin-typescript": "^11.1.5",
 	"@types/isomorphic-fetch": "^0.0.39",
 	"@types/node": "^24.10.1",
 	"@types/ramda": "0.31.1",
 	"@types/uuid": "^9.0.7",
-	"concat-md": "^0.5.1",
 	"eslint-config-nlx": "*",
 	prettier: "^3.1.0",
+	rollup: "^4.3.0",
 	"rollup-config-nlx": "*",
+	"rollup-plugin-node-polyfills": "^0.2.1",
 	typedoc: "^0.28.14",
 	"typedoc-plugin-markdown": "^4.9.0",
 	typescript: "^5.5.4"
@@ -55,7 +62,7 @@ var dependencies = {
 var publishConfig = {
 	access: "public"
 };
-var gitHead = "3902161e95745dd4a9cfb68bb469755a62b421f5";
+var gitHead = "9a1bfacce5cc21ca2d64e79c86805dab37568de3";
 var packageJson = {
 	name: name,
 	version: version$1,
@@ -81,6 +88,24 @@ var packageJson = {
 const version = packageJson.version;
 // use a custom Console to indicate we really want to log to the console and it's not incidental. `console.log` causes an eslint error
 const Console = console;
+/**
+ * The protocol used to communicate with the application
+ */
+exports.Protocol = void 0;
+(function (Protocol) {
+    /**
+     * Regular encrypted HTTPS, without support for post-escalation message handling, interim messages and other streaming features.
+     */
+    Protocol["Https"] = "https";
+    /**
+     * Encrypted HTTPS with streaming enabled. This is the default setting and supports interim messages. Does not support post-escalation message handling.
+     */
+    Protocol["HttpsWithStreaming"] = "httpsWithStreaming";
+    /**
+     * Websocket, with support for post-escalation message handling.
+     */
+    Protocol["Websocket"] = "websocket";
+})(exports.Protocol || (exports.Protocol = {}));
 /**
  * Response type
  */
@@ -127,42 +152,181 @@ const safeJsonParse = (val) => {
         return null;
     }
 };
-const getBaseDomain = (url) => url.match(/(bots\.dev\.studio\.nlx\.ai|bots\.studio\.nlx\.ai|apps\.nlx\.ai|dev\.apps\.nlx\.ai)/g)?.[0] ?? "apps.nlx.ai";
+const getHost = (url) => url.match(/(bots\.dev\.studio\.nlx\.ai|bots\.studio\.nlx\.ai|apps\.nlx\.ai|dev\.apps\.nlx\.ai)/g)?.[0] ?? "apps.nlx.ai";
 /**
- * When a HTTP URL is provided, deduce the websocket URL. Otherwise, return the argument.
- * @param applicationUrl - the websocket URL
- * @returns httpUrl - the HTTP URL
+ * Parse configuration into structured connection information, taking into account `applicationUrl`-based configs.
+ * @param config - client configuration.
+ * @returns connection - connection information, or `null` if the configuration is invalid.
  */
-const normalizeToWebsocket = (applicationUrl) => {
+const parseConnection = (config) => {
+    const applicationUrl = config.applicationUrl ?? "";
+    const apiKey = config.apiKey ?? config.headers?.["nlx-api-key"] ?? "";
+    const protocol = config.protocol ??
+        /**
+         * Backwards-compatibility: if a websocket URL was specified, assume it's websocket. Otherwise, look at the legacy experimental streamsetting
+         * and only assume non-streaming if it's explicitly set to false.
+         */
+        (isWebsocketUrl(applicationUrl)
+            ? exports.Protocol.Websocket
+            : config.experimental?.streamHttp === false
+                ? exports.Protocol.Https
+                : exports.Protocol.HttpsWithStreaming);
+    if (config.host != null &&
+        config.channelKey != null &&
+        config.deploymentKey != null) {
+        return {
+            protocol,
+            apiKey,
+            host: config.host,
+            channelKey: config.channelKey,
+            deploymentKey: config.deploymentKey,
+        };
+    }
+    // `applicationUrl`-based definition: websocket case
     if (isWebsocketUrl(applicationUrl)) {
-        return applicationUrl;
+        const host = getHost(applicationUrl);
+        const url = new URL(applicationUrl);
+        const params = new URLSearchParams(url.search);
+        const channelKey = params.get("channelKey");
+        const deploymentKey = params.get("deploymentKey");
+        if (channelKey != null && deploymentKey != null) {
+            return { protocol, channelKey, deploymentKey, host, apiKey };
+        }
+        return null;
     }
-    const base = getBaseDomain(applicationUrl);
-    const url = new URL(applicationUrl);
-    const pathChunks = url.pathname.split("/");
-    const deploymentKey = pathChunks[2];
-    const channelKey = pathChunks[3];
-    return `wss://us-east-1-ws.${base}?deploymentKey=${deploymentKey}&channelKey=${channelKey}`;
-};
-/**
- * When a websocket URL is provided, deduce the HTTP URL. Otherwise, return the argument.
- * @param applicationUrl - the websocket URL
- * @returns httpUrl - the HTTP URL
- */
-const normalizeToHttp = (applicationUrl) => {
-    if (!isWebsocketUrl(applicationUrl)) {
-        return applicationUrl;
+    // `applicationUrl`-based definition: http case
+    const host = getHost(applicationUrl);
+    const parseResult = new URLPattern({
+        pathname: "/c/:deploymentKey/:channelKey",
+    }).exec(applicationUrl);
+    if (parseResult?.pathname.groups.channelKey != null &&
+        parseResult?.pathname.groups.deploymentKey != null) {
+        return {
+            protocol,
+            channelKey: parseResult.pathname.groups.channelKey,
+            deploymentKey: parseResult.pathname.groups.deploymentKey,
+            host,
+            apiKey,
+        };
     }
-    const base = getBaseDomain(applicationUrl);
-    const url = new URL(applicationUrl);
-    const params = new URLSearchParams(url.search);
-    const channelKey = params.get("channelKey");
-    const deploymentKey = params.get("deploymentKey");
-    return `https://${base}/c/${deploymentKey}/${channelKey}`;
+    return null;
+};
+const toWebsocketUrl = (connection) => {
+    return `wss://us-east-1-ws.${connection.host}?deploymentKey=${connection.deploymentKey}&channelKey=${connection.channelKey}&apiKey=${connection.apiKey}`;
+};
+const toHttpUrl = (connection) => {
+    return `https://${connection.host}/c/${connection.deploymentKey}/${connection.channelKey}`;
 };
 const isWebsocketUrl = (url) => {
     return url.indexOf("wss://") === 0;
 };
+const fetchUserMessage = async ({ fullApplicationUrl, apiKey, headers, body, stream, eventListeners, }) => {
+    const streamRequest = async (body) => {
+        const response = await fetch(fullApplicationUrl, {
+            method: "POST",
+            headers: {
+                ...headers,
+                "nlx-api-key": apiKey,
+                "Content-Type": "application/json",
+                // Legacy header
+                "nlx-sdk-version": packageJson.version,
+                "nlx-core-version": packageJson.version,
+            },
+            body: JSON.stringify({ ...body, stream: true }),
+        });
+        if (!response.ok || response.body == null)
+            throw new Error(`HTTP Error: ${response.status}`);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        const messages = [];
+        let finalResponse = {};
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            while (true) {
+                const openBrace = buffer.indexOf("{");
+                if (openBrace === -1)
+                    break;
+                let foundObject = false;
+                for (let i = 0; i < buffer.length; i++) {
+                    if (buffer[i] === "}") {
+                        const candidate = buffer.substring(openBrace, i + 1);
+                        try {
+                            const json = JSON.parse(candidate);
+                            if (json.type === "interim") {
+                                const text = json.text;
+                                if (typeof text === "string") {
+                                    eventListeners.interimMessage.forEach((listener) => {
+                                        listener(text);
+                                    });
+                                }
+                            }
+                            else if (json.type === "message") {
+                                messages.push({
+                                    text: json.text,
+                                    choices: json.choices ?? [],
+                                    messageId: json.messageId,
+                                    metadata: json.metadata,
+                                });
+                            }
+                            else if (json.type === "final_response") {
+                                finalResponse = json.data;
+                            }
+                            buffer = buffer.substring(i + 1);
+                            foundObject = true;
+                            break;
+                        }
+                        catch (e) {
+                            /* keep scanning */
+                        }
+                    }
+                }
+                if (!foundObject)
+                    break;
+            }
+        }
+        eventListeners.interimMessage.forEach((listener) => {
+            listener(undefined);
+        });
+        return {
+            ...finalResponse,
+            messages: [
+                ...messages,
+                ...(finalResponse.messages ?? []).map((json) => ({
+                    text: json.text,
+                    choices: json.choices ?? [],
+                    messageId: json.messageId,
+                    metadata: json.metadata,
+                })),
+            ],
+        };
+    };
+    if (stream) {
+        return await streamRequest(body);
+    }
+    else {
+        const response = await fetch(fullApplicationUrl, {
+            method: "POST",
+            headers: {
+                ...(headers ?? {}),
+                "nlx-api-key": apiKey,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                // Legacy header
+                "nlx-sdk-version": packageJson.version,
+                "nlx-core-version": packageJson.version,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok || response.body == null)
+            throw new Error(`HTTP Error: ${response.status}`);
+        const json = await response.json();
+        return json;
+    }
+};
 /**
  * Call this to create a conversation handler.
  * @param configuration - The necessary configuration to create the conversation.
@@ -188,12 +352,21 @@ function createConversation(configuration) {
     let voicePlusSocket;
     let voicePlusSocketMessageQueue = [];
     let voicePlusSocketMessageQueueCheckInterval = null;
-    const applicationUrl = configuration.applicationUrl ?? "";
+    const connection = parseConnection(configuration);
+    const websocketApplicationUrl = connection != null
+        ? toWebsocketUrl(connection)
+        : configuration.applicationUrl ?? "";
+    const httpApplicationUrl = connection != null
+        ? toHttpUrl(connection)
+        : configuration.applicationUrl ?? "";
     // Check if the application URL has a language code appended to it
-    if (/[-|_][a-z]{2,}[-|_][A-Z]{2,}$/.test(applicationUrl)) {
+    if (/[-|_][a-z]{2,}[-|_][A-Z]{2,}$/.test(httpApplicationUrl)) {
         Console.warn("Since v1.0.0, the language code is no longer added at the end of the application URL. Please remove the modifier (e.g. '-en-US') from the URL, and specify it in the `languageCode` parameter instead.");
     }
-    const eventListeners = { voicePlusCommand: [] };
+    const eventListeners = {
+        voicePlusCommand: [],
+        interimMessage: [],
+    };
     const initialConversationId = configuration.conversationId ?? uuid.v4();
     let state = {
         responses: configuration.responses ?? [],
@@ -201,7 +374,7 @@ function createConversation(configuration) {
         userId: configuration.userId,
         conversationId: initialConversationId,
     };
-    const fullApplicationHttpUrl = () => `${normalizeToHttp(applicationUrl)}${configuration.experimental?.completeApplicationUrl === true
+    const fullApplicationHttpUrl = () => `${httpApplicationUrl}${configuration.experimental?.completeApplicationUrl === true
         ? ""
         : `-${state.languageCode}`}`;
     const setState = (change, 
@@ -295,7 +468,7 @@ function createConversation(configuration) {
             channelType: configuration.experimental?.channelType,
             environment: configuration.environment,
         };
-        if (isWebsocketUrl(applicationUrl)) {
+        if (connection?.protocol === exports.Protocol.Websocket) {
             if (socket?.readyState === 1) {
                 socket.send(JSON.stringify(bodyWithContext));
             }
@@ -305,20 +478,14 @@ function createConversation(configuration) {
         }
         else {
             try {
-                const res = await fetch(fullApplicationHttpUrl(), {
-                    method: "POST",
-                    headers: {
-                        ...(configuration.headers ?? {}),
-                        Accept: "application/json",
-                        "Content-Type": "application/json",
-                        "nlx-sdk-version": packageJson.version,
-                    },
-                    body: JSON.stringify(bodyWithContext),
+                const json = await fetchUserMessage({
+                    fullApplicationUrl: fullApplicationHttpUrl(),
+                    apiKey: connection?.apiKey ?? "",
+                    headers: configuration.headers ?? {},
+                    stream: connection?.protocol === exports.Protocol.HttpsWithStreaming,
+                    eventListeners,
+                    body: bodyWithContext,
                 });
-                if (res.status >= 400) {
-                    throw new Error(`Responded with ${res.status}`);
-                }
-                const json = await res.json();
                 messageResponseHandler(json);
             }
             catch (err) {
@@ -344,7 +511,7 @@ function createConversation(configuration) {
     const setupWebsocket = () => {
         // If the socket is already set up, tear it down first
         teardownWebsocket();
-        const url = new URL(applicationUrl);
+        const url = new URL(websocketApplicationUrl);
         if (configuration.experimental?.completeApplicationUrl !== true) {
             url.searchParams.set("languageCode", state.languageCode);
             url.searchParams.set("channelKey", `${url.searchParams.get("channelKey") ?? ""}-${state.languageCode}`);
@@ -359,21 +526,6 @@ function createConversation(configuration) {
                 messageResponseHandler(safeJsonParse(e.data));
             }
         };
-        url.searchParams.set("voice-plus", "true");
-        voicePlusSocket = new ReconnectingWebSocket(url.href);
-        voicePlusSocketMessageQueueCheckInterval = setInterval(() => {
-            checkVoicePlusSocketQueue();
-        }, 500);
-        voicePlusSocket.onmessage = (e) => {
-            if (typeof e?.data === "string") {
-                const command = safeJsonParse(e.data);
-                if (command != null) {
-                    eventListeners.voicePlusCommand.forEach((listener) => {
-                        listener(command);
-                    });
-                }
-            }
-        };
     };
     const setupCommandWebsocket = () => {
         // If the socket is already set up, tear it down first
@@ -381,16 +533,15 @@ function createConversation(configuration) {
         if (configuration.bidirectional !== true) {
             return;
         }
-        const url = new URL(normalizeToWebsocket(applicationUrl));
+        const url = new URL(websocketApplicationUrl);
         if (configuration.experimental?.completeApplicationUrl !== true) {
             url.searchParams.set("languageCode", state.languageCode);
             url.searchParams.set("channelKey", `${url.searchParams.get("channelKey") ?? ""}-${state.languageCode}`);
         }
         url.searchParams.set("conversationId", state.conversationId);
         url.searchParams.set("type", "voice-plus");
-        const apiKey = configuration.headers["nlx-api-key"];
-        if (!isWebsocketUrl(applicationUrl) && apiKey != null) {
-            url.searchParams.set("apiKey", apiKey);
+        if (connection?.apiKey != null) {
+            url.searchParams.set("apiKey", connection.apiKey);
         }
         voicePlusSocket = new ReconnectingWebSocket(url.href);
         voicePlusSocketMessageQueueCheckInterval = setInterval(() => {
@@ -427,7 +578,7 @@ function createConversation(configuration) {
             voicePlusSocket = undefined;
         }
     };
-    if (isWebsocketUrl(applicationUrl)) {
+    if (connection?.protocol === exports.Protocol.Websocket) {
         setupWebsocket();
     }
     setupCommandWebsocket();
@@ -533,10 +684,13 @@ function createConversation(configuration) {
                 method: "POST",
                 headers: {
                     ...(configuration.headers ?? {}),
+                    "nlx-api-key": connection?.apiKey ?? "",
                     Accept: "application/json",
                     "Content-Type": "application/json",
                     "nlx-conversation-id": state.conversationId,
+                    // Legacy header
                     "nlx-sdk-version": packageJson.version,
+                    "nlx-core-version": packageJson.version,
                 },
                 body: JSON.stringify({
                     languageCode: state.languageCode,
@@ -591,6 +745,23 @@ function createConversation(configuration) {
             sendFlow(welcomeIntent, context);
         },
         sendChoice,
+        submitFeedback: async (feedbackUrl, feedback) => {
+            const res = await fetch(feedbackUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    languageCode: state.languageCode,
+                    conversationId: state.conversationId,
+                    userId: state.userId,
+                    ...feedback,
+                }),
+            });
+            if (res.status >= 400) {
+                throw new Error(`Responded with ${res.status}`);
+            }
+        },
         currentConversationId: () => {
             return state.conversationId;
         },
@@ -599,7 +770,7 @@ function createConversation(configuration) {
                 Console.warn("Attempted to set language code to the one already active.");
                 return;
             }
-            if (isWebsocketUrl(applicationUrl)) {
+            if (connection?.protocol === exports.Protocol.Websocket) {
                 setupWebsocket();
             }
             setupCommandWebsocket();
@@ -609,15 +780,17 @@ function createConversation(configuration) {
             return state.languageCode;
         },
         getVoiceCredentials: async (context, options) => {
-            const url = normalizeToHttp(applicationUrl);
-            const res = await fetch(`${url}-${state.languageCode}/requestToken`, {
+            const res = await fetch(`${httpApplicationUrl}-${state.languageCode}/requestToken`, {
                 method: "POST",
                 headers: {
                     ...(configuration.headers ?? {}),
+                    "nlx-api-key": connection?.apiKey ?? "",
                     Accept: "application/json",
                     "Content-Type": "application/json",
                     "nlx-conversation-id": state.conversationId,
+                    // Legacy header
                     "nlx-sdk-version": packageJson.version,
+                    "nlx-core-version": packageJson.version,
                 },
                 body: JSON.stringify({
                     languageCode: state.languageCode,
@@ -647,14 +820,14 @@ function createConversation(configuration) {
                 conversationId: uuid.v4(),
                 responses: options?.clearResponses === true ? [] : state.responses,
             });
-            if (isWebsocketUrl(applicationUrl)) {
+            if (connection?.protocol === exports.Protocol.Websocket) {
                 setupWebsocket();
             }
             setupCommandWebsocket();
         },
         destroy: () => {
             subscribers = [];
-            if (isWebsocketUrl(applicationUrl)) {
+            if (connection?.protocol === exports.Protocol.Websocket) {
                 teardownWebsocket();
             }
             teardownCommandWebsocket();
@@ -679,8 +852,7 @@ function createConversation(configuration) {
  * @returns Whether the configuration is valid?
  */
 const isConfigValid = (configuration) => {
-    const applicationUrl = configuration.applicationUrl ?? "";
-    return applicationUrl.length > 0;
+    return parseConnection(configuration) != null;
 };
 /**
  * Helper method to decide when a new {@link Config} requires creating a new {@link ConversationHandler} or whether the old `Config`'s
@@ -773,10 +945,77 @@ function promisify(fn, convo, timeout = 10000) {
         });
     };
 }
+/**
+ * Use this function when using **Voice+ scripts** to advance the conversation to the step specified.
+ *
+ * This functionality is orthogonal from other usage of the core SDK, as it may be used either using standard SDK communication channels or it can be used to provide a Voice+ script experience with for instance a telephony based channel.
+ * @example
+ * ```typescript
+ *  import { sendVoicePlusStep } from "@nlxai/core";
+ *
+ *  await sendVoicePlusStep({
+ *    // hard-coded params
+ *    apiKey: "REPLACE_WITH_API_KEY",
+ *    workspaceId: "REPLACE_WITH_WORKSPACE_ID",
+ *    scriptId: "REPLACE_WITH_SCRIPT_ID",
+ *    step: "REPLACE_WITH_STEP_ID",
+ *    // dynamic params
+ *    conversationId: "REPLACE_WITH_CONVERSATION_ID",
+ *    languageCode: "en-US",
+ * });
+ * ```
+ * @param configuration - Configuration for sending the step. Many of the values can be found on the deployment modal of the Voice+ script.
+ */
+const sendVoicePlusStep = async ({ apiKey, workspaceId, conversationId, scriptId, languageCode, step, context, debug = false, dev = false, }) => {
+    if (scriptId == null) {
+        throw new Error("Voice+ scriptId is not defined.");
+    }
+    if (typeof conversationId !== "string" || conversationId.length === 0) {
+        throw new Error("Voice+ conversationId is not defined.");
+    }
+    const [stepId, stepTriggerDescription] = typeof step === "string"
+        ? [step, undefined]
+        : [step.stepId, step.stepTriggerDescription];
+    if (!stepIdRegex.test(stepId)) {
+        throw new Error("Invalid stepId. It should be formatted as a UUID.");
+    }
+    const payload = {
+        stepId,
+        context,
+        conversationId,
+        journeyId: scriptId,
+        languageCode,
+        stepTriggerDescription,
+    };
+    try {
+        await fetch(`https://${dev ? "dev." : ""}mm.nlx.ai/v1/track`, {
+            method: "POST",
+            headers: {
+                "x-api-key": apiKey,
+                "x-nlx-id": workspaceId,
+                "Content-Type": "application/json",
+                "nlx-sdk-version": packageJson.version,
+                "nlx-core-version": packageJson.version,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (debug) {
+            Console.info(`✓ step: ${stepId}`, payload);
+        }
+    }
+    catch (err) {
+        if (debug) {
+            Console.error(`× step: ${stepId}`, err, payload);
+        }
+        throw err;
+    }
+};
+const stepIdRegex = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 
 exports.createConversation = createConversation;
 exports.getCurrentExpirationTimestamp = getCurrentExpirationTimestamp;
 exports.isConfigValid = isConfigValid;
 exports.promisify = promisify;
+exports.sendVoicePlusStep = sendVoicePlusStep;
 exports.shouldReinitialize = shouldReinitialize;
 exports.version = version;