@nlxai/core 1.2.3-alpha.1 → 1.2.3

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-alpha.1";
+var version$1 = "1.2.3";
 var description = "Low-level SDK for building NLX experiences";
 var type = "module";
 var main = "lib/index.cjs";
@@ -22,40 +22,40 @@ var exports$1 = {
 };
 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"
+	tsc: "tsc",
+	"update-readme:docs": "rm -rf docs/ && typedoc",
+	"update-readme:merge": "../../scripts/transclude-markdown.js",
+	"update-readme": "npm run update-readme:docs && npm run update-readme:merge"
 };
 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/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-config-nlx": "*",
-	typedoc: "^0.25.13",
-	"typedoc-plugin-markdown": "^3.17.1",
+	typedoc: "^0.28.14",
+	"typedoc-plugin-markdown": "^4.9.0",
 	typescript: "^5.5.4"
 };
 var dependencies = {
 	"isomorphic-fetch": "^3.0.0",
-	ramda: "^0.29.1",
+	ramda: "^0.32.0",
 	"reconnecting-websocket": "^4.4.0",
 	uuid: "^9.0.1"
 };
 var publishConfig = {
 	access: "public"
 };
-var gitHead = "13e26a6c67af7aa6c8dc100ad83d9c33e1112a08";
+var gitHead = "3902161e95745dd4a9cfb68bb469755a62b421f5";
 var packageJson = {
 	name: name,
 	version: version$1,
@@ -127,18 +127,6 @@ const safeJsonParse = (val) => {
         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 !ramda.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.
@@ -175,41 +163,45 @@ const normalizeToHttp = (applicationUrl) => {
 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 -
+ * @param configuration - The necessary configuration to create the conversation.
  * @returns The {@link ConversationHandler} is a bundle of functions to interact with the conversation.
+ * @example
+ * ```typescript
+ * import { createConversation } from "@nlx/core";
+ *
+ * const conversation = createConversation({
+ *   applicationUrl: "https://apps.nlx.ai/c/cfab3-243ad-232dc",
+ *   headers: {
+ *     "nlx-api-key": "4393029032-dwsd",
+ *   },
+ *  userId: "abcd-1234",
+ *  languageCode: "en-US",
+ * });
+ * ```
  */
-function createConversation(config) {
+function createConversation(configuration) {
     let socket;
     let socketMessageQueue = [];
     let socketMessageQueueCheckInterval = null;
     let voicePlusSocket;
     let voicePlusSocketMessageQueue = [];
     let voicePlusSocketMessageQueueCheckInterval = null;
-    const applicationUrl = config.applicationUrl ?? "";
+    const applicationUrl = configuration.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 ?? uuid.v4();
+    const initialConversationId = configuration.conversationId ?? uuid.v4();
     let state = {
-        responses: config.responses ?? [],
-        languageCode: config.languageCode,
-        userId: config.userId,
+        responses: configuration.responses ?? [],
+        languageCode: configuration.languageCode,
+        userId: configuration.userId,
         conversationId: initialConversationId,
     };
-    const fullApplicationHttpUrl = () => `${normalizeToHttp(applicationUrl)}${config.experimental?.completeApplicationUrl === true
+    const fullApplicationHttpUrl = () => `${normalizeToHttp(applicationUrl)}${configuration.experimental?.completeApplicationUrl === true
         ? ""
         : `-${state.languageCode}`}`;
     const setState = (change, 
@@ -228,7 +220,7 @@ function createConversation(config) {
             type: exports.ResponseType.Failure,
             receivedAt: new Date().getTime(),
             payload: {
-                text: config.failureMessage ?? defaultFailureMessage,
+                text: configuration.failureMessage ?? defaultFailureMessage,
             },
         };
         setState({
@@ -283,6 +275,7 @@ function createConversation(config) {
     const sendToApplication = async (body) => {
         if (requestOverride != null) {
             requestOverride(body, (payload) => {
+                Console.warn("Using the second argument in `setRequestOverride` is deprecated. Use `conversationHandler.appendMessageToTranscript` instead.");
                 const newResponse = {
                     type: exports.ResponseType.Application,
                     receivedAt: new Date().getTime(),
@@ -299,8 +292,8 @@ function createConversation(config) {
             conversationId: state.conversationId,
             ...body,
             languageCode: state.languageCode,
-            channelType: config.experimental?.channelType,
-            environment: config.environment,
+            channelType: configuration.experimental?.channelType,
+            environment: configuration.environment,
         };
         if (isWebsocketUrl(applicationUrl)) {
             if (socket?.readyState === 1) {
@@ -315,7 +308,7 @@ function createConversation(config) {
                 const res = await fetch(fullApplicationHttpUrl(), {
                     method: "POST",
                     headers: {
-                        ...(config.headers ?? {}),
+                        ...(configuration.headers ?? {}),
                         Accept: "application/json",
                         "Content-Type": "application/json",
                         "nlx-sdk-version": packageJson.version,
@@ -352,7 +345,7 @@ function createConversation(config) {
         // If the socket is already set up, tear it down first
         teardownWebsocket();
         const url = new URL(applicationUrl);
-        if (config.experimental?.completeApplicationUrl !== true) {
+        if (configuration.experimental?.completeApplicationUrl !== true) {
             url.searchParams.set("languageCode", state.languageCode);
             url.searchParams.set("channelKey", `${url.searchParams.get("channelKey") ?? ""}-${state.languageCode}`);
         }
@@ -385,17 +378,17 @@ function createConversation(config) {
     const setupCommandWebsocket = () => {
         // If the socket is already set up, tear it down first
         teardownCommandWebsocket();
-        if (config.bidirectional !== true) {
+        if (configuration.bidirectional !== true) {
             return;
         }
         const url = new URL(normalizeToWebsocket(applicationUrl));
-        if (config.experimental?.completeApplicationUrl !== true) {
+        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 = config.headers["nlx-api-key"];
+        const apiKey = configuration.headers["nlx-api-key"];
         if (!isWebsocketUrl(applicationUrl) && apiKey != null) {
             url.searchParams.set("apiKey", apiKey);
         }
@@ -539,7 +532,7 @@ function createConversation(config) {
             const res = await fetch(`${fullApplicationHttpUrl()}/context`, {
                 method: "POST",
                 headers: {
-                    ...(config.headers ?? {}),
+                    ...(configuration.headers ?? {}),
                     Accept: "application/json",
                     "Content-Type": "application/json",
                     "nlx-conversation-id": state.conversationId,
@@ -556,6 +549,15 @@ function createConversation(config) {
                 throw new Error(`Responded with ${res.status}`);
             }
         },
+        appendMessageToTranscript: (newResponse) => {
+            const newResponseWithTimestamp = {
+                ...newResponse,
+                receivedAt: newResponse.receivedAt ?? new Date().getTime(),
+            };
+            setState({
+                responses: [...state.responses, newResponseWithTimestamp],
+            }, newResponseWithTimestamp);
+        },
         sendStructured: (structured, context) => {
             appendStructuredUserResponse(structured, context);
             void sendToApplication({
@@ -611,7 +613,7 @@ function createConversation(config) {
             const res = await fetch(`${url}-${state.languageCode}/requestToken`, {
                 method: "POST",
                 headers: {
-                    ...(config.headers ?? {}),
+                    ...(configuration.headers ?? {}),
                     Accept: "application/json",
                     "Content-Type": "application/json",
                     "nlx-conversation-id": state.conversationId,
@@ -672,9 +674,52 @@ function createConversation(config) {
     };
 }
 /**
- * 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)
+ * Check whether a configuration is valid.
+ * @param configuration - Conversation configuration
+ * @returns Whether the configuration is valid?
+ */
+const isConfigValid = (configuration) => {
+    const applicationUrl = configuration.applicationUrl ?? "";
+    return applicationUrl.length > 0;
+};
+/**
+ * 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 !ramda.equals(config1, config2);
+};
+/**
+ * Get current expiration timestamp from a list of responses. Can be used to determine if a conversation has timed out.
+ * @example
+ * ```typescript
+ * import { useState } from "react";
+ * import { getCurrentExpirationTimestamp } from "@nlxai/core";
+ *
+ * const [isTimedOut, setIsTimedOut] = useState(false);
+ *
+ * conversation.subscribe((responses) => {
+ *   const expirationTimestamp = getCurrentExpirationTimestamp(responses);
+ *   if (expirationTimestamp != null && expirationTimestamp < new Date().getTime()) {
+ *     setIsTimedOut(true);
+ *   }
+ * });
+ *
+ * return (<div>
+ *   {isTimedOut ? (
+ *     <p>Your session has timed out. Please start a new conversation.</p>
+ *   ) : (
+ *     <p>Your session is active.</p>
+ *   )}
+ * </div>
+ * ```
+ * @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;
@@ -702,7 +747,7 @@ const getCurrentExpirationTimestamp = (responses) => {
  *   console.log(response);
  * });
  * ```
- * @typeParam T - the type of the function's params, e.g. for `sendText` it's `text: string, context?: Context`
+ * @typeParam Params - 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