From 5a59ce08bf113537ecddd8ca7241af94c03c4ff1 Mon Sep 17 00:00:00 2001 From: Peter Szerzo Date: Sat, 21 May 2022 06:59:47 +0200 Subject: [PATCH 1/3] Add language code setting --- README.md | 92 +++----------------------------------- packages/core/README.md | 21 +++------ packages/core/src/index.ts | 2 + packages/widget/README.md | 22 ++++++--- 4 files changed, 33 insertions(+), 104 deletions(-) diff --git a/README.md b/README.md index 70b2fa4..d90638c 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,18 @@ # Chat SDK for NLX bots -This is our official JavaScript SDK to communicate with NLX conversational bots. - -## Getting started - -```js -import createConversation from "nlx-chat-sdk"; - -// Create some configuration -const testConfig = { - botUrl: "" // obtain from NLX deployments page -}; - -// Start the conversation -const convo = createConversation(testConfig); - -// Subscribe to changes in the list of messages -convo.subscribe(messages => { - console.log(messages); -}); - -// Send a message from the user's end -convo.sendText("hello"); -``` - -## API reference - -The package exports a single function called `createConversation`, which is called with the bot configuration and returns a conversation handler object. This object has the following methods: - -#### `sendText: (text: string) => void` - -Send a simple text to your bot. - -#### `sendChoice: (choiceId: string) => void` - -Your bot may send a list of choices to choose from, each with a `choiceText` and a `choiceId` field. You can use `choiceText` as button labels, and include the `choiceId` in this method when sending responses. - -#### `sendSlots: (slots: Array<{ slotId: string; value: unknown }>) => void` - -Send slot values directly through custom widgets such as interactive maps. - -#### `subscribe: (subscriber: (messages: Message[], additional: { payload?: string }) => void) => void` - -Subscribe to the current state of messages whenever there is a change. - -#### `unsubscribe: (subscriber: (messages: Message[], additional: { payload?: string }) => void) => void` - -Remove a subscription. - -#### `unsubscribeAll: () => void` - -Remove all subscriptions. - -#### `reset: () => void` - -Reset the conversation. This makes sure that information previously collected by your bot will not affect the logic of the conversation any longer. - -## Usage with React - -We provide a [React](https://reactjs.org/) example in TypeScript to illustrate how the project works in a modern web application framework. This implementation uses our `useChat` [hook](https://reactjs.org/docs/hooks-intro.html) which you can use to build your own chat widget: - -```jsx -import { useChat } from "nlx-chat-sdk/react-utils"; - -const ChatWidget = () => { - const chat = useChat({ - botUrl: "" - }); - - return ( -
- {chat.messages.map(/* render messages in the current conversation */)} -
- ); -}; -``` - -See [full example](examples/with-react.tsx). - -The API of the hook is similar to the vanilla API. It leaves out subscribe and unsubscribe methods as they are used internally in effect hooks, making sure things are properly cleaned up. Instead, messages are readily available in the `chat.messages` field, and we added state hooks for taking care of the value of the chat input field. You are free to not use these and manage things on your own. +This is our official JavaScript SDK to communicate with NLX conversational bots. It contains the following packages: +* [@nlxchat/core](https://www.npmjs.com/package/@nlxchat/core): vanilla JavaScript SDK. +* [@nlxchat/react](https://www.npmjs.com/package/@nlxchat/react): React hook for building chat widgets. +* [@nlxchat/preact](https://www.npmjs.com/package/@nlxchat/preact): Preact hook for building chat widgets. +* [@nlxchat/widget](https://www.npmjs.com/package/@nlxchat/widget): the official themeable NLX widget. ## Usage with \* -Do you work with Vue? React without hooks? Custom elements? Elm? Let us know what framework you are looking to build web-based chat applications with so we can look into making utilities for those. +Do you work with Vue? React without hooks? Custom elements? Let us know what framework you are looking to build web-based chat applications with so we can look into making utilities for those. ## TypeScript -This SDK is written in TypeScript so you can use our type definitions in your project. - -## Widget - -This package also exports a themeable widget build in React. [Docs here](src/widget/README.md). +All SDK packages are written in TypeScript so you can use our type definitions in your project. ## Contributing diff --git a/packages/core/README.md b/packages/core/README.md index 63d92fb..2ad1a63 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -12,7 +12,10 @@ const config = { botUrl: "", // obtain from NLX deployments page headers: { "nlx-api-key": "" // obtain from NLX deployments page - } + }, + userId: "abcd-1234", // optional property to identify the user + context: {}, // context that is shared with the bot + languageCode: "es-US" // optional language code for standard bots that do not run on US English }; // Start the conversation @@ -29,7 +32,9 @@ convo.sendText("hello"); ## API reference -The package exports a single function called `createConversation`, which is called with the bot configuration and returns a conversation handler object. This object has the following methods: +The package exports a single function called `createConversation`, which is called with the bot configuration and returns a conversation handler object. + +This return object has the following methods: #### `sendText: (text: string) => void` @@ -67,18 +72,6 @@ Remove all subscriptions. Reset the conversation. This makes sure that information previously collected by your bot will not affect the logic of the conversation any longer. -## Usage with React - -See the custom [React hook](https://www.npmjs.com/package/@nlxchat/react) for setting up your own React widget in a few dozen lines of code. - -## Usage with Preact - -Likewise, see the custom [Preact hook](https://www.npmjs.com/package/@nlxchat/preact) for setting up your own Preact widget in a few dozen lines of code. - -## Usage with \* - -Do you work with Vue? React without hooks? Custom elements? Elm? Let us know what framework you are looking to build web-based chat applications with so we can look into making utilities for those. - ## TypeScript This SDK is written in TypeScript so you can use our type definitions in your project. diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index ee7864c..08cd276 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -66,6 +66,7 @@ export interface Config { headers: { [key: string]: string; }; + languageCode?: string; } const defaultFailureMessages = [ @@ -190,6 +191,7 @@ const createConversation = (config: Config): ConversationHandler => { ? { context: config.context } : {}), ...body, + languageCode: config.languageCode }; if (!state.contextSent) { state = { ...state, contextSent: true }; diff --git a/packages/widget/README.md b/packages/widget/README.md index a59f54d..0446feb 100644 --- a/packages/widget/README.md +++ b/packages/widget/README.md @@ -19,7 +19,14 @@ standalone({ botUrl: "", headers: { "nlx-api-key": "" - } + }, + }, + initiallyExpanded: true, + theme: { + primaryColor: "teal", + darkMessageColor: "#000", + lightMessageColor: "#fff", + fontFamily: "Helvetica" } }); ``` @@ -44,6 +51,13 @@ There is also a packaged version of the SDK that exposes the `chat.standalone` a headers: { "nlx-api-key": "" } + }, + initiallyExpanded: true, + theme: { + primaryColor: "teal", + darkMessageColor: "#000", + lightMessageColor: "#fff", + fontFamily: "Helvetica" } }); @@ -52,7 +66,7 @@ There is also a packaged version of the SDK that exposes the `chat.standalone` a ## Configuration -Initiating the chat takes the following parameters (see [type definition](types.ts) for details): +Initiating the chat takes the following parameters (see [type definition](https://github.com/nlxai/chat-sdk/blob/master/packages/widget/src/props.ts) for details): ### `config` @@ -60,7 +74,7 @@ The configuration of the chat itself, containing `botUrl` and request headers. ### `theme` -Overrides for the visual theme constants. See [Theme type definition](types.ts) for details. +Overrides for the visual theme constants. See [Theme type definition](https://github.com/nlxai/chat-sdk/blob/master/packages/widget/src/theme.ts) for details. ### `chatIcon` @@ -77,8 +91,6 @@ Renders an optional title bar at the top. If the object is provided, it has the When set to a non-empty string, a small bubble will appear above the chat pin when the chat is not expanded, helping the user understand what the chat is for. This bubble appears 3s after the chat is loaded, and disappears after 20s. -A complete example of the configuration options can be found [here](../../examples/standalone.html). - ### `initiallyExpanded` Sets whether the widget is initially expanded. From 7467862ed19e0ca8a129ae7de2a1238c68b7ead9 Mon Sep 17 00:00:00 2001 From: Peter Szerzo Date: Sun, 22 May 2022 10:45:41 +0200 Subject: [PATCH 2/3] Tweak docs --- README.md | 10 +++++----- packages/widget/README.md | 4 ++++ packages/widget/src/theme.ts | 9 +++++++-- 3 files changed, 16 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d90638c..3400fb3 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Chat SDK for NLX bots -This is our official JavaScript SDK to communicate with NLX conversational bots. It contains the following packages: -* [@nlxchat/core](https://www.npmjs.com/package/@nlxchat/core): vanilla JavaScript SDK. -* [@nlxchat/react](https://www.npmjs.com/package/@nlxchat/react): React hook for building chat widgets. -* [@nlxchat/preact](https://www.npmjs.com/package/@nlxchat/preact): Preact hook for building chat widgets. -* [@nlxchat/widget](https://www.npmjs.com/package/@nlxchat/widget): the official themeable NLX widget. +The official JavaScript SDK to communicate with conversational bots created using NLX Dialog Studio. It contains the following packages: +* [@nlxchat/widget](https://www.npmjs.com/package/@nlxchat/widget): the official out-of-the-box, lightly themeable NLX widget. +* [@nlxchat/core](https://www.npmjs.com/package/@nlxchat/core): vanilla JavaScript SDK for creating fully custom chat widgets. +* [@nlxchat/react](https://www.npmjs.com/package/@nlxchat/react): React custom hook for building chat widgets. +* [@nlxchat/preact](https://www.npmjs.com/package/@nlxchat/preact): Preact custom hook for building chat widgets. ## Usage with \* diff --git a/packages/widget/README.md b/packages/widget/README.md index 0446feb..e58ed93 100644 --- a/packages/widget/README.md +++ b/packages/widget/README.md @@ -110,3 +110,7 @@ If you need low-level control of the widget, this configuration value gives acce ``` The callback pattern works similarly to the way [callback refs](https://reactjs.org/docs/refs-and-the-dom.html#callback-refs) work in React. We are avoiding that naming since the configuration option works identical in standalone mode. + +## License + +MIT. diff --git a/packages/widget/src/theme.ts b/packages/widget/src/theme.ts index 8142620..cc48261 100644 --- a/packages/widget/src/theme.ts +++ b/packages/widget/src/theme.ts @@ -1,8 +1,13 @@ // Colors may be in any CSS-compatible format like rgb(50, 50, 50) or #aaa export interface Theme { - primaryColor: string; - darkMessageColor: string; + /** Primary color for interactive UI elements like buttons */ + primaryColor: string; + /** Background color for the dark chat bubbles (sent by the user) */ + darkMessageColor: string; + /** Background color for the light chat bubbles (sent by the bot) */ lightMessageColor: string; + /** Customized shade of white */ white: string; + /** Widget font family */ fontFamily: string; } From 4e428e5ffac217ed261517adb1c2924f12c4b162 Mon Sep 17 00:00:00 2001 From: Peter Szerzo Date: Tue, 24 May 2022 09:58:43 +0200 Subject: [PATCH 3/3] Upgrade React --- packages/react/package.json | 8 ++++---- packages/widget/package.json | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/react/package.json b/packages/react/package.json index a93bae8..111db76 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -13,8 +13,8 @@ "devDependencies": { "@types/node": "^11.15.11", "@types/ramda": "^0.26.44", - "@types/react": "^16.9.34", - "@types/react-dom": "^16.9.6", + "@types/react": "^17.0.39", + "@types/react-dom": "^17.0.11", "prettier": "^1.19.1", "typescript": "^4.0.5" }, @@ -23,8 +23,8 @@ "ramda": "^0.27.1" }, "peerDependencies": { - "react": "^16.13.1", - "react-dom": "^16.13.1" + "react": "^17.0.2", + "react-dom": "^17.0.2" }, "publishConfig": { "access": "public" diff --git a/packages/widget/package.json b/packages/widget/package.json index 576b6dc..447b239 100644 --- a/packages/widget/package.json +++ b/packages/widget/package.json @@ -15,14 +15,14 @@ "devDependencies": { "@types/node": "^11.15.11", "@types/ramda": "^0.26.44", - "@types/react": "^16.9.34", - "@types/react-dom": "^16.9.6", + "@types/react": "^17.0.39", + "@types/react-dom": "^17.0.11", "@types/tinycolor2": "^1.4.2", "browserify": "^17.0.0", "parcel": "^2.0.0", "prettier": "^1.19.1", - "react": "^16.13.1", - "react-dom": "^16.13.1", + "react": "^17.0.2", + "react-dom": "^17.0.2", "tsify": "^5.0.2", "typescript": "^4.0.5", "uglifyify": "^5.0.2" @@ -41,8 +41,8 @@ "whatwg-fetch": "^3.0.0" }, "peerDependencies": { - "react": "^16.13.1", - "react-dom": "^16.13.1" + "react": "^17.0.2", + "react-dom": "^17.0.2" }, "publishConfig": { "access": "public"