@nlxai/core 1.2.3 → 1.2.4-alpha.10

package/README.md

@@ -13,7 +13,10 @@ import { createConversation } from "@nlxai/core";
 
 // Create some configuration
 const config = {
-  applicationUrl: "", // obtain from NLX deployments page
+  protocol: "httpsWithStreaming", // "httpsWithStreaming", "https" or "websocket"
+  host: "", // obtain from NLX deployments page
+  deploymentKey: "", // obtain from NLX deployments page
+  channelKey: "", // obtain from NLX deployments page
   headers: {
     "nlx-api-key": "", // obtain from NLX deployments page
   },
@@ -224,7 +227,6 @@ export default async function (req: Request): Promise<Response> {
 # API reference
 
 <!-- include docs/README.md -->
-
 ## Functions
 
 ### createConversation()
@@ -441,6 +443,101 @@ sendTextWrapped("Hello").then((response) => {
 });
 ```
 
+---
+
+### sendVoicePlusStep()
+
+```ts
+function sendVoicePlusStep(configuration): Promise<void>;
+```
+
+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.
+
+#### Parameters
+
+##### configuration
+
+Configuration for sending the step. Many of the values can be found on the deployment modal of the Voice+ script.
+
+###### apiKey
+
+`string`
+
+- the API key generated for the Voice+ script. Note that this value is different from the API key you would pass to [createConversation](#createconversation). You can control the API key on the Voice+ script settings page.
+
+###### scriptId?
+
+`string`
+
+The ID of the Voice+ script.
+
+###### workspaceId
+
+`string`
+
+Your workspace ID.
+
+###### conversationId
+
+`string`
+
+The active conversation ID, passed from the active NLX voice application. This is what ties the script exectution to the specific Voice application.
+
+_Note: This must be dynamically set by the voice application._ Normally, when the voice application directs the user to the webpage running this code, it will include the conversation ID as a URL parameter which you can extract and pass here.
+
+**Example**
+
+```typescript
+const conversationId = new URLSearchParams(window.location.search).get("cid");
+```
+
+###### languageCode
+
+`string`
+
+The user's language code, consistent with the language codes defined on the Voice+ script.
+
+###### step
+
+[`StepInfo`](#stepinfo)
+
+Which step to send.
+
+###### context
+
+[`Context`](#context)
+
+Any context.
+
+###### debug?
+
+`boolean` = `false`
+
+Set to `true` to help debug issues or errors. Defaults to `false`.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### 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",
+});
+```
+
 ## Variables
 
 ### version
@@ -738,6 +835,38 @@ Send a combination of choice, slots, and intent in one request.
 
 `void`
 
+##### submitFeedback()
+
+```ts
+submitFeedback: (url, feedback) => Promise<void>;
+```
+
+Submit feedback about a response.
+
+###### Parameters
+
+###### url
+
+`string`
+
+The URL comming from the Application response `metadata.feedbackURL` field.
+
+###### feedback
+
+Either a numerical rating or a textual comment.
+
+###### rating?
+
+`number`
+
+###### comment?
+
+`string`
+
+###### Returns
+
+`Promise`\<`void`\>
+
 ##### subscribe()
 
 ```ts
@@ -905,11 +1034,11 @@ Add a listener to one of the handler's custom events
 
 ###### event
 
-`"voicePlusCommand"`
+[`ConversationHandlerEvent`](#conversationhandlerevent)
 
 ###### handler
 
-(`payload`) => `void`
+[`VoicePlusCommandListener`](#voicepluscommandlistener) | [`InterimMessageListener`](#interimmessagelistener)
 
 ###### Returns
 
@@ -927,11 +1056,11 @@ Remove a listener to one of the handler's custom events
 
 ###### event
 
-`"voicePlusCommand"`
+[`ConversationHandlerEvent`](#conversationhandlerevent)
 
 ###### handler
 
-(`payload`) => `void`
+[`VoicePlusCommandListener`](#voicepluscommandlistener) | [`InterimMessageListener`](#interimmessagelistener)
 
 ###### Returns
 
@@ -1132,6 +1261,24 @@ optional sources: KnowledgeBaseResponseSource[];
 
 Knowledge base sources
 
+##### feedbackUrl?
+
+```ts
+optional feedbackUrl: string;
+```
+
+URL to use for submitting feedback about this response. See `feedbackConfig` for what the expected feedback type is.
+
+You can pass this as the first argument to `submitFeedback`.
+
+##### feedbackConfig?
+
+```ts
+optional feedbackConfig: FeedbackConfiguration;
+```
+
+If present, the application would like to collect feedback from the user.
+
 ---
 
 ### KnowledgeBaseResponseSource
@@ -1391,6 +1538,120 @@ When the failure occurred.
 
 ---
 
+### FeedbackConfiguration
+
+Configuration for feedback collection. You can use this to render an appropriate feedback widget in your application.
+
+#### Properties
+
+##### feedbackId
+
+```ts
+feedbackId: string;
+```
+
+Unique identifier for the feedback collection.
+
+##### feedbackName
+
+```ts
+feedbackName: string;
+```
+
+Human readable name of this feedback collection.
+
+##### feedbackType
+
+```ts
+feedbackType: object;
+```
+
+Type of feedback being collected.
+At the moment only binary feedback is supported, but we plan to introduce more types in the future.
+Hence your code should make sure to check the `type` attribute to make sure the expected feedback type is handled.
+
+###### type
+
+```ts
+type: "binary";
+```
+
+A binary feedback type is a thumbs up/down sort of choice.
+
+###### config
+
+```ts
+config: object;
+```
+
+Configuration specific to binary feedback.
+
+###### config.positiveValue
+
+```ts
+positiveValue: number;
+```
+
+Value to send for positive feedback. Default `1`.
+
+###### config.negativeValue
+
+```ts
+negativeValue: number;
+```
+
+Value to send for negative feedback. Default `-1`.
+
+##### commentsEnabled
+
+```ts
+commentsEnabled: boolean;
+```
+
+Whether comments are enabled for this feedback collection.
+
+##### question?
+
+```ts
+optional question: string;
+```
+
+Optional question to show to the user when collecting feedback.
+
+##### labels
+
+```ts
+labels: object;
+```
+
+Labels for individual feedback UI elements as customised by the builder.
+
+###### positive?
+
+```ts
+optional positive: string;
+```
+
+Label for positive feedback
+
+###### negative?
+
+```ts
+optional negative: string;
+```
+
+Label for negative feedback
+
+###### comment?
+
+```ts
+optional comment: string;
+```
+
+Label for comment
+
+---
+
 ### StructuredRequest
 
 The body of `sendStructured`
@@ -1642,23 +1903,21 @@ Dictionary of handler methods per event
 
 #### Properties
 
-##### voicePlusCommand()
+##### voicePlusCommand
 
 ```ts
-voicePlusCommand: (payload) => void;
+voicePlusCommand: VoicePlusCommandListener;
 ```
 
 Voice+ command event handler
 
-###### Parameters
-
-###### payload
+##### interimMessage
 
-`any`
+```ts
+interimMessage: InterimMessageListener;
+```
 
-###### Returns
-
-`void`
+Interim message event handler
 
 ## Enumerations
 
@@ -1697,7 +1956,7 @@ Generic failure (cannot be attributed to the application)
 ### ConversationHandlerEvent
 
 ```ts
-type ConversationHandlerEvent = "voicePlusCommand";
+type ConversationHandlerEvent = "voicePlusCommand" | "interimMessage";
 ```
 
 Handler events
@@ -1932,6 +2191,46 @@ Voice+ context, type to be defined
 
 ---
 
+### VoicePlusCommandListener()
+
+```ts
+type VoicePlusCommandListener = (payload) => void;
+```
+
+Voice+ command listener
+
+#### Parameters
+
+##### payload
+
+`any`
+
+#### Returns
+
+`void`
+
+---
+
+### InterimMessageListener()
+
+```ts
+type InterimMessageListener = (message?) => void;
+```
+
+Interim message listener
+
+#### Parameters
+
+##### message?
+
+`string`
+
+#### Returns
+
+`void`
+
+---
+
 ### Subscriber()
 
 ```ts
@@ -1953,3 +2252,46 @@ The callback function for listening to all responses.
 #### Returns
 
 `void`
+
+---
+
+### StepInfo
+
+```ts
+type StepInfo =
+  | string
+  | {
+      stepId: string;
+      stepTriggerDescription?: string;
+    };
+```
+
+Step information, either a step ID as a single string or an object
+
+#### Type Declaration
+
+`string`
+
+```ts
+{
+  stepId: string;
+  stepTriggerDescription?: string;
+}
+```
+
+##### stepId
+
+```ts
+stepId: string;
+```
+
+Step ID
+
+##### stepTriggerDescription?
+
+```ts
+optional stepTriggerDescription: string;
+```
+
+Step trigger description
+