@nlxai/core 1.1.8-alpha.0

package/lib/index.esm.js

@@ -0,0 +1,729 @@
+import fetch from 'isomorphic-fetch';
+import { equals, adjust } from 'ramda';
+import ReconnectingWebSocket from 'reconnecting-websocket';
+import { v4 } from 'uuid';
+
+var name = "@nlxai/core";
+var version$1 = "1.1.8-alpha.0";
+var description = "Low-level SDK for building NLX experiences";
+var type = "module";
+var main = "lib/index.cjs";
+var module = "lib/index.esm.js";
+var browser = "lib/index.umd.js";
+var types = "lib/index.d.ts";
+var exports = {
+	".": {
+		types: "./lib/index.d.ts",
+		"import": "./lib/index.esm.js",
+		require: "./lib/index.cjs"
+	}
+};
+var scripts = {
+	build: "rm -rf lib && rollup -c --configPlugin typescript --configImportAttributesKey with",
+	docs: "rm -rf docs/ && typedoc && concat-md --decrease-title-levels --dir-name-as-title docs/ > docs/index.md",
+	"lint:check": "eslint src/ --ext .ts,.tsx,.js,.jsx --max-warnings 0",
+	lint: "eslint src/ --ext .ts,.tsx,.js,.jsx --fix",
+	prepublish: "npm run build",
+	"preview-docs": "npm run docs && comrak --unsafe --gfm -o docs/index.html docs/index.md && open docs/index.html",
+	"publish-docs": "npm run docs && mv docs/index.md ../website/src/content/headless-api-reference.md",
+	test: "typedoc --emit none",
+	tsc: "tsc"
+};
+var author = "Peter Szerzo <peter@nlx.ai>";
+var license = "MIT";
+var devDependencies = {
+	"@types/isomorphic-fetch": "^0.0.36",
+	"@types/node": "^22.10.1",
+	"@types/ramda": "0.29.1",
+	"@types/uuid": "^9.0.7",
+	"concat-md": "^0.5.1",
+	"eslint-config-nlx": "*",
+	prettier: "^3.1.0",
+	"rollup-config-nlx": "*",
+	typedoc: "^0.25.13",
+	"typedoc-plugin-markdown": "^3.17.1",
+	typescript: "^5.5.4"
+};
+var dependencies = {
+	"isomorphic-fetch": "^3.0.0",
+	ramda: "^0.29.1",
+	"reconnecting-websocket": "^4.4.0",
+	uuid: "^9.0.1"
+};
+var publishConfig = {
+	access: "public"
+};
+var gitHead = "8f4341c889c73a3b681dcdf25420ecec285c1ef6";
+var packageJson = {
+	name: name,
+	version: version$1,
+	description: description,
+	type: type,
+	main: main,
+	module: module,
+	browser: browser,
+	types: types,
+	exports: exports,
+	scripts: scripts,
+	author: author,
+	license: license,
+	devDependencies: devDependencies,
+	dependencies: dependencies,
+	publishConfig: publishConfig,
+	gitHead: gitHead
+};
+
+/**
+ * Package version
+ */
+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;
+/**
+ * Response type
+ */
+var ResponseType;
+(function (ResponseType) {
+    /**
+     * Response from the application
+     */
+    ResponseType["Application"] = "bot";
+    /**
+     * Response from the user
+     */
+    ResponseType["User"] = "user";
+    /**
+     * Generic failure (cannot be attributed to the application)
+     */
+    ResponseType["Failure"] = "failure";
+})(ResponseType || (ResponseType = {}));
+const welcomeIntent = "NLX.Welcome";
+const defaultFailureMessage = "We encountered an issue. Please try again soon.";
+const normalizeSlots = (slotsRecordOrArray) => {
+    if (Array.isArray(slotsRecordOrArray)) {
+        return slotsRecordOrArray;
+    }
+    return Object.entries(slotsRecordOrArray).map(([key, value]) => ({
+        slotId: key,
+        value,
+    }));
+};
+const normalizeStructuredRequest = (structured) => ({
+    ...structured,
+    intentId: structured.flowId ?? structured.intentId,
+    slots: structured.slots != null
+        ? normalizeSlots(structured.slots)
+        : structured.slots,
+});
+const fromInternal = (internalState) => internalState.responses;
+const safeJsonParse = (val) => {
+    try {
+        const json = JSON.parse(val);
+        return json;
+    }
+    catch (_err) {
+        return null;
+    }
+};
+/**
+ * Helper method to decide when a new {@link Config} requires creating a new {@link ConversationHandler} or whether the old `Config`'s
+ * `ConversationHandler` can be used.
+ *
+ * The order of configs doesn't matter.
+ * @param config1 -
+ * @param config2 -
+ * @returns true if `createConversation` should be called again
+ */
+const shouldReinitialize = (config1, config2) => {
+    return !equals(config1, config2);
+};
+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";
+/**
+ * When a HTTP URL is provided, deduce the websocket URL. Otherwise, return the argument.
+ * @param applicationUrl - the websocket URL
+ * @returns httpUrl - the HTTP URL
+ */
+const normalizeToWebsocket = (applicationUrl) => {
+    if (isWebsocketUrl(applicationUrl)) {
+        return applicationUrl;
+    }
+    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;
+    }
+    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}`;
+};
+const isWebsocketUrl = (url) => {
+    return url.indexOf("wss://") === 0;
+};
+/**
+ * Check whether a configuration is value.
+ * @param config - Chat configuration
+ * @returns isValid - Whether the configuration is valid
+ */
+const isConfigValid = (config) => {
+    const applicationUrl = config.applicationUrl ?? "";
+    return applicationUrl.length > 0;
+};
+/**
+ * Call this to create a conversation handler.
+ * @param config -
+ * @returns The {@link ConversationHandler} is a bundle of functions to interact with the conversation.
+ */
+function createConversation(config) {
+    let socket;
+    let socketMessageQueue = [];
+    let socketMessageQueueCheckInterval = null;
+    let voicePlusSocket;
+    let voicePlusSocketMessageQueue = [];
+    let voicePlusSocketMessageQueueCheckInterval = null;
+    const applicationUrl = config.applicationUrl ?? "";
+    // Check if the application URL has a language code appended to it
+    if (/[-|_][a-z]{2,}[-|_][A-Z]{2,}$/.test(applicationUrl)) {
+        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 initialConversationId = config.conversationId ?? v4();
+    let state = {
+        responses: config.responses ?? [],
+        languageCode: config.languageCode,
+        userId: config.userId,
+        conversationId: initialConversationId,
+    };
+    const fullApplicationHttpUrl = () => `${normalizeToHttp(applicationUrl)}${config.experimental?.completeApplicationUrl === true
+        ? ""
+        : `-${state.languageCode}`}`;
+    const setState = (change, 
+    // Optionally send the response that causes the current state change, to be sent to subscribers
+    newResponse) => {
+        state = {
+            ...state,
+            ...change,
+        };
+        subscribers.forEach((subscriber) => {
+            subscriber(fromInternal(state), newResponse);
+        });
+    };
+    const failureHandler = () => {
+        const newResponse = {
+            type: ResponseType.Failure,
+            receivedAt: new Date().getTime(),
+            payload: {
+                text: config.failureMessage ?? defaultFailureMessage,
+            },
+        };
+        setState({
+            responses: [...state.responses, newResponse],
+        }, newResponse);
+    };
+    const messageResponseHandler = (response) => {
+        if (response?.messages.length > 0) {
+            const newResponse = {
+                type: ResponseType.Application,
+                receivedAt: new Date().getTime(),
+                payload: {
+                    ...response,
+                    messages: response.messages.map((message) => ({
+                        nodeId: message.nodeId,
+                        messageId: message.messageId,
+                        text: message.text,
+                        choices: message.choices ?? [],
+                    })),
+                },
+            };
+            setState({
+                responses: [...state.responses, newResponse],
+            }, newResponse);
+            if (response.metadata.hasPendingDataRequest) {
+                appendStructuredUserResponse({ poll: true });
+                setTimeout(() => {
+                    void sendToApplication({
+                        request: {
+                            structured: {
+                                poll: true,
+                            },
+                        },
+                    });
+                }, 1500);
+            }
+        }
+        else {
+            Console.warn("Invalid message structure, expected object with field 'messages'.");
+            failureHandler();
+        }
+    };
+    let requestOverride;
+    const sendVoicePlusMessage = (message) => {
+        if (voicePlusSocket?.readyState === 1) {
+            voicePlusSocket.send(JSON.stringify(message));
+        }
+        else {
+            voicePlusSocketMessageQueue = [...voicePlusSocketMessageQueue, message];
+        }
+    };
+    const sendToApplication = async (body) => {
+        if (requestOverride != null) {
+            requestOverride(body, (payload) => {
+                const newResponse = {
+                    type: ResponseType.Application,
+                    receivedAt: new Date().getTime(),
+                    payload,
+                };
+                setState({
+                    responses: [...state.responses, newResponse],
+                }, newResponse);
+            });
+            return;
+        }
+        const bodyWithContext = {
+            userId: state.userId,
+            conversationId: state.conversationId,
+            ...body,
+            languageCode: state.languageCode,
+            channelType: config.experimental?.channelType,
+            environment: config.environment,
+        };
+        if (isWebsocketUrl(applicationUrl)) {
+            if (socket?.readyState === 1) {
+                socket.send(JSON.stringify(bodyWithContext));
+            }
+            else {
+                socketMessageQueue = [...socketMessageQueue, bodyWithContext];
+            }
+        }
+        else {
+            try {
+                const res = await fetch(fullApplicationHttpUrl(), {
+                    method: "POST",
+                    headers: {
+                        ...(config.headers ?? {}),
+                        Accept: "application/json",
+                        "Content-Type": "application/json",
+                        "nlx-sdk-version": packageJson.version,
+                    },
+                    body: JSON.stringify(bodyWithContext),
+                });
+                if (res.status >= 400) {
+                    throw new Error(`Responded with ${res.status}`);
+                }
+                const json = await res.json();
+                messageResponseHandler(json);
+            }
+            catch (err) {
+                Console.warn(err);
+                failureHandler();
+            }
+        }
+    };
+    let subscribers = [];
+    const checkSocketQueue = async () => {
+        if (socket?.readyState === 1 && socketMessageQueue[0] != null) {
+            await sendToApplication(socketMessageQueue[0]);
+            socketMessageQueue = socketMessageQueue.slice(1);
+        }
+    };
+    const checkVoicePlusSocketQueue = () => {
+        if (voicePlusSocket?.readyState === 1 &&
+            voicePlusSocketMessageQueue[0] != null) {
+            sendVoicePlusMessage(voicePlusSocketMessageQueue[0]);
+            voicePlusSocketMessageQueue = voicePlusSocketMessageQueue.slice(1);
+        }
+    };
+    const setupWebsocket = () => {
+        // If the socket is already set up, tear it down first
+        teardownWebsocket();
+        const url = new URL(applicationUrl);
+        if (config.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);
+        socket = new ReconnectingWebSocket(url.href);
+        socketMessageQueueCheckInterval = setInterval(() => {
+            void checkSocketQueue();
+        }, 500);
+        socket.onmessage = function (e) {
+            if (typeof e?.data === "string") {
+                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
+        teardownCommandWebsocket();
+        if (config.bidirectional !== true) {
+            return;
+        }
+        const url = new URL(normalizeToWebsocket(applicationUrl));
+        if (config.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 = config.headers["nlx-api-key"];
+        if (!isWebsocketUrl(applicationUrl) && apiKey != null) {
+            url.searchParams.set("apiKey", apiKey);
+        }
+        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 teardownWebsocket = () => {
+        if (socketMessageQueueCheckInterval != null) {
+            clearInterval(socketMessageQueueCheckInterval);
+        }
+        if (socket != null) {
+            socket.onmessage = null;
+            socket.close();
+            socket = undefined;
+        }
+    };
+    const teardownCommandWebsocket = () => {
+        if (voicePlusSocketMessageQueueCheckInterval != null) {
+            clearInterval(voicePlusSocketMessageQueueCheckInterval);
+        }
+        if (voicePlusSocket != null) {
+            voicePlusSocket.onmessage = null;
+            voicePlusSocket.close();
+            voicePlusSocket = undefined;
+        }
+    };
+    if (isWebsocketUrl(applicationUrl)) {
+        setupWebsocket();
+    }
+    setupCommandWebsocket();
+    const appendStructuredUserResponse = (structured, context) => {
+        const newResponse = {
+            type: ResponseType.User,
+            receivedAt: new Date().getTime(),
+            payload: {
+                type: "structured",
+                ...normalizeStructuredRequest(structured),
+                context,
+            },
+        };
+        setState({
+            responses: [...state.responses, newResponse],
+        }, newResponse);
+    };
+    const sendFlow = (intentId, context) => {
+        appendStructuredUserResponse({ intentId }, context);
+        void sendToApplication({
+            context,
+            request: {
+                structured: {
+                    intentId,
+                },
+            },
+        });
+    };
+    const sendText = (text, context) => {
+        const newResponse = {
+            type: ResponseType.User,
+            receivedAt: new Date().getTime(),
+            payload: {
+                type: "text",
+                text,
+                context,
+            },
+        };
+        setState({
+            responses: [...state.responses, newResponse],
+        }, newResponse);
+        void sendToApplication({
+            context,
+            request: {
+                unstructured: {
+                    text,
+                },
+            },
+        });
+    };
+    const sendChoice = (choiceId, context, metadata) => {
+        let newResponses = [...state.responses];
+        const choiceResponse = {
+            type: ResponseType.User,
+            receivedAt: new Date().getTime(),
+            payload: {
+                type: "choice",
+                choiceId,
+            },
+        };
+        const responseIndex = metadata?.responseIndex ?? -1;
+        const messageIndex = metadata?.messageIndex ?? -1;
+        if (responseIndex > -1 && messageIndex > -1) {
+            newResponses = adjust(responseIndex, (response) => response.type === ResponseType.Application
+                ? {
+                    ...response,
+                    payload: {
+                        ...response.payload,
+                        messages: adjust(messageIndex, (message) => ({ ...message, selectedChoiceId: choiceId }), response.payload.messages),
+                    },
+                }
+                : response, newResponses);
+        }
+        newResponses = [...newResponses, choiceResponse];
+        setState({
+            responses: newResponses,
+        }, choiceResponse);
+        void sendToApplication({
+            context,
+            request: {
+                structured: {
+                    nodeId: metadata?.nodeId,
+                    intentId: metadata?.intentId,
+                    choiceId,
+                },
+            },
+        });
+    };
+    const unsubscribe = (subscriber) => {
+        subscribers = subscribers.filter((fn) => fn !== subscriber);
+    };
+    const subscribe = (subscriber) => {
+        subscribers = [...subscribers, subscriber];
+        subscriber(fromInternal(state));
+        return () => {
+            unsubscribe(subscriber);
+        };
+    };
+    return {
+        sendText,
+        sendContext: async (context) => {
+            const res = await fetch(`${fullApplicationHttpUrl()}/context`, {
+                method: "POST",
+                headers: {
+                    ...(config.headers ?? {}),
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "nlx-conversation-id": state.conversationId,
+                    "nlx-sdk-version": packageJson.version,
+                },
+                body: JSON.stringify({
+                    languageCode: state.languageCode,
+                    conversationId: state.conversationId,
+                    userId: state.userId,
+                    context,
+                }),
+            });
+            if (res.status >= 400) {
+                throw new Error(`Responded with ${res.status}`);
+            }
+        },
+        sendStructured: (structured, context) => {
+            appendStructuredUserResponse(structured, context);
+            void sendToApplication({
+                context,
+                request: {
+                    structured: normalizeStructuredRequest(structured),
+                },
+            });
+        },
+        sendSlots: (slots, context) => {
+            appendStructuredUserResponse({ slots }, context);
+            void sendToApplication({
+                context,
+                request: {
+                    structured: {
+                        slots: normalizeSlots(slots),
+                    },
+                },
+            });
+        },
+        sendFlow,
+        sendIntent: (intentId, context) => {
+            Console.warn("Calling `sendIntent` is deprecated and will be removed in a future version of the SDK. Use `sendFlow` instead.");
+            sendFlow(intentId, context);
+        },
+        sendWelcomeFlow: (context) => {
+            sendFlow(welcomeIntent, context);
+        },
+        sendWelcomeIntent: (context) => {
+            Console.warn("Calling `sendWelcomeIntent` is deprecated and will be removed in a future version of the SDK. Use `sendWelcomeFlow` instead.");
+            sendFlow(welcomeIntent, context);
+        },
+        sendChoice,
+        currentConversationId: () => {
+            return state.conversationId;
+        },
+        setLanguageCode: (languageCode) => {
+            if (languageCode === state.languageCode) {
+                Console.warn("Attempted to set language code to the one already active.");
+                return;
+            }
+            if (isWebsocketUrl(applicationUrl)) {
+                setupWebsocket();
+            }
+            setupCommandWebsocket();
+            setState({ languageCode });
+        },
+        currentLanguageCode: () => {
+            return state.languageCode;
+        },
+        getVoiceCredentials: async (context) => {
+            const url = normalizeToHttp(applicationUrl);
+            const res = await fetch(`${url}-${state.languageCode}/requestToken`, {
+                method: "POST",
+                headers: {
+                    ...(config.headers ?? {}),
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "nlx-conversation-id": state.conversationId,
+                    "nlx-sdk-version": packageJson.version,
+                },
+                body: JSON.stringify({
+                    languageCode: state.languageCode,
+                    conversationId: state.conversationId,
+                    userId: state.userId,
+                    requestToken: true,
+                    context,
+                }),
+            });
+            if (res.status >= 400) {
+                throw new Error(`Responded with ${res.status}`);
+            }
+            const data = await res.json();
+            if (data?.url == null) {
+                throw new Error("Invalid response");
+            }
+            return data;
+        },
+        subscribe,
+        unsubscribe,
+        unsubscribeAll: () => {
+            subscribers = [];
+        },
+        reset: (options) => {
+            setState({
+                conversationId: v4(),
+                responses: options?.clearResponses === true ? [] : state.responses,
+            });
+            if (isWebsocketUrl(applicationUrl)) {
+                setupWebsocket();
+            }
+            setupCommandWebsocket();
+        },
+        destroy: () => {
+            subscribers = [];
+            if (isWebsocketUrl(applicationUrl)) {
+                teardownWebsocket();
+            }
+            teardownCommandWebsocket();
+        },
+        setRequestOverride: (val) => {
+            requestOverride = val;
+        },
+        addEventListener: (event, listener) => {
+            eventListeners[event] = [...eventListeners[event], listener];
+        },
+        removeEventListener: (event, listener) => {
+            eventListeners[event] = eventListeners[event].filter((l) => l !== listener);
+        },
+        sendVoicePlusContext: (context) => {
+            sendVoicePlusMessage({ context });
+        },
+    };
+}
+/**
+ * Get current expiration timestamp from the current list of reponses
+ * @param responses - the current list of user and application responses (first argument in the subscribe callback)
+ * @returns an expiration timestamp in Unix Epoch (`new Date().getTime()`), or `null` if this is not known (typically occurs if the application has not responded yet)
+ */
+const getCurrentExpirationTimestamp = (responses) => {
+    let expirationTimestamp = null;
+    responses.forEach((response) => {
+        if (response.type === ResponseType.Application &&
+            response.payload.expirationTimestamp != null) {
+            expirationTimestamp = response.payload.expirationTimestamp;
+        }
+    });
+    return expirationTimestamp;
+};
+/**
+ * This package is intentionally designed with a subscription-based API as opposed to a promise-based one where each message corresponds to a single application response, available asynchronously.
+ *
+ * If you need a promise-based wrapper, you can use the `promisify` helper available in the package:
+ * @example
+ * ```typescript
+ * import { createConversation, promisify } from "@nlxai/core";
+ *
+ * const convo = createConversation(config);
+ *
+ * const sendTextWrapped = promisify(convo.sendText, convo);
+ *
+ * sendTextWrapped("Hello").then((response) => {
+ *   console.log(response);
+ * });
+ * ```
+ * @typeParam T - the type of the function's params, e.g. for `sendText` it's `text: string, context?: Context`
+ * @param fn - the function to wrap (e.g. `convo.sendText`, `convo.sendChoice`, etc.)
+ * @param convo - the `ConversationHandler` (from {@link createConversation})
+ * @param timeout - the timeout in milliseconds
+ * @returns A promise-wrapped version of the function. The function, when called, returns a promise that resolves to the Conversation's next response.
+ */
+function promisify(fn, convo, timeout = 10000) {
+    return async (payload) => {
+        return await new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error("The request timed out."));
+                convo.unsubscribe(subscription);
+            }, timeout);
+            const subscription = (_responses, newResponse) => {
+                if (newResponse?.type === ResponseType.Application ||
+                    newResponse?.type === ResponseType.Failure) {
+                    clearTimeout(timeoutId);
+                    convo.unsubscribe(subscription);
+                    resolve(newResponse);
+                }
+            };
+            convo.subscribe(subscription);
+            fn(payload);
+        });
+    };
+}
+
+export { ResponseType, createConversation, getCurrentExpirationTimestamp, isConfigValid, promisify, shouldReinitialize, version };