@nlxai/core 1.2.3-alpha.2 → 1.2.4-alpha.1

package/lib/index.d.ts

@@ -2,6 +2,217 @@
  * Package version
  */
 export declare const version: string;
+/**
+ * The configuration necessary to create a conversation.
+ */
+export interface Config {
+    /**
+     * The URL at which your conversational application is running.
+     * Fetch this from the application's API channel tab.
+     */
+    applicationUrl?: string;
+    /**
+     * Headers to forward to the NLX API.
+     */
+    headers: Record<string, string> & {
+        /**
+         * The `nlx-api-key` is required. Fetch this from the application's API channel tab.
+         */
+        "nlx-api-key": string;
+    };
+    /**
+     * Set `conversationId` to continue an existing conversation. If not set, a new conversation will be started (and a new conversationId will be generated internally).
+     */
+    conversationId?: string;
+    /**
+     * Setting the `userID` allows it to be searchable in application history, as well as usable via `{System.userId}` in the flow.
+     */
+    userId?: string;
+    /**
+     * When `responses` is set, initialize the chatHandler with historical messages. This is useful when restoring a previous conversation, that perhaps started on a different page.
+     */
+    responses?: Response[];
+    /**
+     * When set, this overrides the default failure message ("We encountered an issue. Please try again soon.").
+     */
+    failureMessage?: string;
+    /**
+     * The language code to use for the application. In the browser this can be fetched with `navigator.language`.
+     * If you don't have translations, hard-code this to the language code you support.
+     */
+    languageCode: LanguageCode;
+    /**
+     * @hidden @internal
+     * this should only be used for NLX internal testing.
+     */
+    environment?: Environment;
+    /**
+     * Specifies whether the conversation is using bidirectional Voice+ (if so, an additional command socket will be opened).
+     */
+    bidirectional?: boolean;
+    /**
+     * Experimental settings
+     * @internal
+     */
+    experimental?: {
+        /**
+         * Simulate alternative channel types
+         */
+        channelType?: string;
+        /**
+         * Prevent the `languageCode` parameter to be appended to the application URL - used in special deployment environments such as the sandbox chat inside Dialog Studio
+         */
+        completeApplicationUrl?: boolean;
+    };
+}
+/**
+ * A bundle of functions to interact with a conversation, created by {@link createConversation}.
+ */
+export interface ConversationHandler {
+    /**
+     * Send user's message
+     * @param text - the user's message
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
+     */
+    sendText: (text: string, context?: Context) => void;
+    /**
+     * Send [slots](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/slots-custom#slot-settings) to the application.
+     * @param slots - The slots to populate
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
+     */
+    sendSlots: (slots: SlotsRecordOrArray, context?: Context) => void;
+    /**
+     * Respond to [a choice](https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/nodes#user-choice) from the application.
+     * @param choiceId - The `choiceId` is in the {@link ApplicationResponse}'s `.payload.messages[].choices[].choiceId` fields
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
+     * @param metadata - links the choice to the specific message and node in the conversation.
+     */
+    sendChoice: (choiceId: string, context?: Context, metadata?: ChoiceRequestMetadata) => void;
+    /**
+     * Trigger the welcome flow. This should be done when the user starts interacting with the conversation.
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
+     */
+    sendWelcomeFlow: (context?: Context) => void;
+    /**
+     * Trigger the welcome [intent](https://docs.studio.nlx.ai/intents/introduction-to-intents). This should be done when the user starts interacting with the conversation.
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+     * @deprecated use `sendWelcomeFlow` instead
+     * @hidden
+     */
+    sendWelcomeIntent: (context?: Context) => void;
+    /**
+     * Trigger a specific flow.
+     * @param flowId - the flow to trigger. The id is the name under the application's _Intents_.
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+     */
+    sendFlow: (flowId: string, context?: Context) => void;
+    /**
+     * Trigger a specific [intent](https://docs.studio.nlx.ai/intents/introduction-to-intents).
+     * @param intentId - the intent to trigger. The id is the name under the application's _Intents_.
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+     * @deprecated use `sendFlow` instead
+     * @hidden
+     */
+    sendIntent: (intentId: string, context?: Context) => void;
+    /**
+     * Send context without sending a message
+     * @param context - [Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+     */
+    sendContext: (context: Context) => Promise<void>;
+    /**
+     * Obtain Voice credentials to run the experience in voice.
+     * @internal
+     * @returns Voice credentials in promise form
+     */
+    getVoiceCredentials: (context?: Context, options?: {
+        autoTriggerWelcomeFlow?: boolean;
+    }) => Promise<VoiceCredentials>;
+    /**
+     * Append messages manually to the transcript. This is an advanced feature that allows routing and aggregation of different chat message
+     * sources.
+     * @param response - the response with optional timestamps.
+     */
+    appendMessageToTranscript: (response: (Omit<ApplicationResponse, "receivedAt"> & {
+        receivedAt?: Time;
+    }) | (Omit<UserResponse, "receivedAt"> & {
+        receivedAt?: Time;
+    }) | (Omit<FailureMessage, "receivedAt"> & {
+        receivedAt?: Time;
+    })) => void;
+    /**
+     * Send a combination of choice, slots, and intent in one request.
+     * @param request -
+     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
+     */
+    sendStructured: (request: StructuredRequest, context?: Context) => void;
+    /**
+     * Submit feedback about a response.
+     * @param url - The URL comming from the Application response `metadata.feedbackURL` field.
+     * @param feedback - Either a numerical rating or a textual comment.
+     */
+    submitFeedback: (url: string, feedback: {
+        rating?: number;
+        comment?: string;
+    }) => Promise<void>;
+    /**
+     * Subscribe a callback to the conversation. On subscribe, the subscriber will receive all of the Responses that the conversation has already received.
+     * @param subscriber - The callback to subscribe
+     * @returns A function to unsubscribe the callback.
+     */
+    subscribe: (subscriber: Subscriber) => () => void;
+    /**
+     * Unsubscribe a callback from the conversation.
+     * @param subscriber - The callback to unsubscribe
+     */
+    unsubscribe: (subscriber: Subscriber) => void;
+    /**
+     * Unsubscribe all callback from the conversation.
+     */
+    unsubscribeAll: () => void;
+    /**
+     * Get the current conversation ID if it's set, or undefined if there is no conversation.
+     */
+    currentConversationId: () => string | undefined;
+    /**
+     * Get the current language code
+     */
+    currentLanguageCode: () => LanguageCode;
+    /**
+     * Set the language code
+     */
+    setLanguageCode: (languageCode: LanguageCode) => void;
+    /**
+     * Forces a new conversation. If `clearResponses` is set to true, will also clear historical responses passed to subscribers.
+     * Retains all existing subscribers.
+     */
+    reset: (options?: {
+        /**
+         * If set to true, will clear historical responses passed to subscribers.
+         */
+        clearResponses?: boolean;
+    }) => void;
+    /**
+     * Removes all subscribers and, if using websockets, closes the connection.
+     */
+    destroy: () => void;
+    /**
+     * Optional {@link RequestOverride} function used to bypass the application request and handle them in a custom fashion
+     */
+    setRequestOverride: (override: RequestOverride | undefined) => void;
+    /**
+     * Add a listener to one of the handler's custom events
+     */
+    addEventListener: (event: ConversationHandlerEvent, handler: EventHandlers[ConversationHandlerEvent]) => void;
+    /**
+     * Remove a listener to one of the handler's custom events
+     */
+    removeEventListener: (event: ConversationHandlerEvent, handler: EventHandlers[ConversationHandlerEvent]) => void;
+    /**
+     * Send voicePlus message
+     * @internal
+     */
+    sendVoicePlusContext: (context: VoicePlusContext) => void;
+}
 /**
  * [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
  */
@@ -149,6 +360,16 @@ export interface ApplicationResponseMetadata {
      * Knowledge base sources
      */
     sources?: KnowledgeBaseResponseSource[];
+    /**
+     * 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`.
+     */
+    feedbackUrl?: string;
+    /**
+     * If present, the application would like to collect feedback from the user.
+     */
+    feedbackConfig?: FeedbackConfiguration;
 }
 /**
  * Response for knowlege base sources
@@ -340,70 +561,53 @@ export type Response = ApplicationResponse | UserResponse | FailureMessage;
  */
 export type Time = number;
 /**
- * @hidden
+ * Configuration for feedback collection. You can use this to render an appropriate feedback widget in your application.
+ */
+export interface FeedbackConfiguration {
+    /** Unique identifier for the feedback collection. */
+    feedbackId: string;
+    /** Human readable name of this feedback collection. */
+    feedbackName: string;
+    /**
+     * 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.
+     */
+    feedbackType: FeedbackType;
+    /** Whether comments are enabled for this feedback collection. */
+    commentsEnabled: boolean;
+    /** Optional question to show to the user when collecting feedback. */
+    question?: string;
+    /** Labels for individual feedback UI elements as customised by the builder. */
+    labels: {
+        /** Label for positive feedback */
+        positive?: string;
+        /** Label for negative feedback */
+        negative?: string;
+    };
+}
+/**
+ * @inline @hidden
  */
-export type Environment = "production" | "development";
+export type FeedbackType = {
+    /** A binary feedback type is a thumbs up/down sort of choice. */
+    type: "binary";
+    /** Configuration specific to binary feedback. */
+    config: BinaryFeedbackConfig;
+};
 /**
- * The configuration to create a conversation.
+ * @inline @hidden
  */
-export interface Config {
-    /**
-     * Fetch this from the application's Deployment page.
-     */
-    applicationUrl?: string;
-    /**
-     * Headers to forward to the NLX API.
-     */
-    headers: Record<string, string> & {
-        /**
-         * The `nlx-api-key` is required. Fetch this from the application's Deployment page.
-         */
-        "nlx-api-key": string;
-    };
-    /**
-     * Set `conversationId` to continue an existing conversation. If not set, a new conversation will be started.
-     */
-    conversationId?: string;
-    /**
-     * Setting the `userID` allows it to be searchable in application history, as well as usable via `{System.userId}` in the intent.
-     */
-    userId?: string;
-    /**
-     * When `responses` is set, initialize the chatHandler with historical messages.
-     */
-    responses?: Response[];
-    /**
-     * When set, this overrides the default failure message ("We encountered an issue. Please try again soon.").
-     */
-    failureMessage?: string;
-    /**
-     * The language code to use for the application. In the browser this can be fetched with `navigator.language`.
-     * If you don't have translations, hard-code this to the language code you support.
-     */
-    languageCode: LanguageCode;
-    /**
-     * @hidden
-     * this should only be used for NLX internal testing.
-     */
-    environment?: Environment;
-    /**
-     * Specifies whether the conversation is bidirectional
-     */
-    bidirectional?: boolean;
-    /**
-     * Experimental settings
-     */
-    experimental?: {
-        /**
-         * Simulate alternative channel types
-         */
-        channelType?: string;
-        /**
-         * Prevent the `languageCode` parameter to be appended to the application URL - used in special deployment environments such as the sandbox chat inside Dialog Studio
-         */
-        completeApplicationUrl?: boolean;
-    };
+export interface BinaryFeedbackConfig {
+    /** Value to send for positive feedback. Default `1`. */
+    positiveValue: number;
+    /** Value to send for negative feedback. Default `-1`. */
+    negativeValue: number;
 }
+/**
+ * @hidden
+ */
+export type Environment = "production" | "development";
 /**
  * The body of `sendStructured`
  * Includes a combination of choice, slots, and intent in one request.
@@ -566,6 +770,7 @@ export interface VoicePlusMessage {
 }
 /**
  * Handler events
+ * @event voicePlusCommand
  */
 export type ConversationHandlerEvent = "voicePlusCommand";
 /**
@@ -577,145 +782,35 @@ export interface EventHandlers {
      */
     voicePlusCommand: (payload: any) => void;
 }
-/**
- * A bundle of functions to interact with a conversation, created by {@link createConversation}.
- */
-export interface ConversationHandler {
-    /**
-     * Send user's message
-     * @param text - the user's message
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendText: (text: string, context?: Context) => void;
-    /**
-     * Send [slots](https://docs.studio.nlx.ai/workspacesettings/introduction-to-settings) to the application.
-     * @param slots - The slots to populate
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendSlots: (slots: SlotsRecordOrArray, context?: Context) => void;
-    /**
-     * Respond to [a choice](https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/nodes#user-choice) from the application.
-     * @param choidId - The `choiceId` is in the {@link ApplicationResponse}'s `.payload.messages[].choices[].choiceId` fields
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     * @param metadata - links the choice to the specific message and node in the conversation.
-     */
-    sendChoice: (choiceId: string, context?: Context, metadata?: ChoiceRequestMetadata) => void;
-    /**
-     * Trigger the welcome flow. This should be done when the user starts interacting with the chat.
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendWelcomeFlow: (context?: Context) => void;
-    /**
-     * Trigger the welcome [intent](https://docs.studio.nlx.ai/intents/introduction-to-intents). This should be done when the user starts interacting with the chat.
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     * @deprecated use `sendWelcomeFlow` instead
-     */
-    sendWelcomeIntent: (context?: Context) => void;
-    /**
-     * Trigger a specific flow.
-     * @param flowId - the flow to trigger. The id is the name under the application's _Intents_.
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendFlow: (flowId: string, context?: Context) => void;
-    /**
-     * Trigger a specific [intent](https://docs.studio.nlx.ai/intents/introduction-to-intents).
-     * @param intentId - the intent to trigger. The id is the name under the application's _Intents_.
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     * @deprecated use `sendFlow` instead
-     */
-    sendIntent: (intentId: string, context?: Context) => void;
-    /**
-     * Send context without sending a message
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendContext: (context: Context) => Promise<void>;
-    /**
-     * Obtain Voice credentials to run the experience in voice.
-     * @internal
-     * @returns Voice credentials in promise form
-     */
-    getVoiceCredentials: (context?: Context, options?: {
-        autoTriggerWelcomeFlow?: boolean;
-    }) => Promise<VoiceCredentials>;
-    /**
-     * Append messages manually to the transcript. This is an advanced feature that allows routing and aggregation of different chat message
-     * sources.
-     * @param response - the response with optional timestamps.
-     */
-    appendMessageToTranscript: (response: (Omit<ApplicationResponse, "receivedAt"> & {
-        receivedAt?: Time;
-    }) | (Omit<UserResponse, "receivedAt"> & {
-        receivedAt?: Time;
-    }) | (Omit<FailureMessage, "receivedAt"> & {
-        receivedAt?: Time;
-    })) => void;
-    /**
-     * Send a combination of choice, slots, and intent in one request.
-     * @param request -
-     * @param context - [Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
-     */
-    sendStructured: (request: StructuredRequest, context?: Context) => void;
-    /**
-     * Subscribe a callback to the conversation. On subscribe, the subscriber will receive all of the Responses that the conversation has already received.
-     * @param subscriber - The callback to subscribe
-     */
-    subscribe: (subscriber: Subscriber) => () => void;
-    /**
-     * Unsubscribe a callback from the conversation.
-     * @param subscriber - The callback to unsubscribe
-     */
-    unsubscribe: (subscriber: Subscriber) => void;
-    /**
-     * Unsubscribe all callback from the conversation.
-     */
-    unsubscribeAll: () => void;
-    /**
-     * Get the current conversation ID if it's set, or undefined if there is no conversation.
-     */
-    currentConversationId: () => string | undefined;
-    /**
-     * Get the current language code
-     */
-    currentLanguageCode: () => LanguageCode;
-    /**
-     * Set the language code
-     */
-    setLanguageCode: (languageCode: LanguageCode) => void;
-    /**
-     * Forces a new conversation. If `clearResponses` is set to true, will also clear historical responses passed to subscribers.
-     * Retains all existing subscribers.
-     */
-    reset: (options?: {
-        /**
-         * If set to true, will clear historical responses passed to subscribers.
-         */
-        clearResponses?: boolean;
-    }) => void;
-    /**
-     * Removes all subscribers and, if using websockets, closes the connection.
-     */
-    destroy: () => void;
-    /**
-     * Optional {@link RequestOverride} function used to bypass the application request and handle them in a custom fashion
-     */
-    setRequestOverride: (override: RequestOverride | undefined) => void;
-    /**
-     * Add a listener to one of the handler's custom events
-     */
-    addEventListener: (event: ConversationHandlerEvent, handler: EventHandlers[ConversationHandlerEvent]) => void;
-    /**
-     * Remove a listener to one of the handler's custom events
-     */
-    removeEventListener: (event: ConversationHandlerEvent, handler: EventHandlers[ConversationHandlerEvent]) => void;
-    /**
-     * Send voicePlus message
-     */
-    sendVoicePlusContext: (context: VoicePlusContext) => void;
-}
 /**
  * The callback function for listening to all responses.
  */
 export type Subscriber = (response: Response[], newResponse?: Response) => void;
+/**
+ * Call this to create a conversation handler.
+ * @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",
+ * });
+ * ```
+ */
+export declare function createConversation(configuration: Config): ConversationHandler;
+/**
+ * Check whether a configuration is valid.
+ * @param configuration - Conversation configuration
+ * @returns Whether the configuration is valid?
+ */
+export declare const isConfigValid: (configuration: Config) => boolean;
 /**
  * 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.
@@ -727,21 +822,31 @@ export type Subscriber = (response: Response[], newResponse?: Response) => void;
  */
 export declare const shouldReinitialize: (config1: Config, config2: Config) => boolean;
 /**
- * Check whether a configuration is value.
- * @param config - Chat configuration
- * @returns isValid - Whether the configuration is valid
- */
-export declare const isConfigValid: (config: Config) => boolean;
-/**
- * Call this to create a conversation handler.
- * @param config -
- * @returns The {@link ConversationHandler} is a bundle of functions to interact with the conversation.
- */
-export declare function createConversation(config: Config): ConversationHandler;
-/**
- * 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)
+ * 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)
  */
 export declare const getCurrentExpirationTimestamp: (responses: Response[]) => number | null;
 /**
@@ -760,10 +865,10 @@ export declare const getCurrentExpirationTimestamp: (responses: Response[]) => n
  *   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
  * @returns A promise-wrapped version of the function. The function, when called, returns a promise that resolves to the Conversation's next response.
  */
-export declare function promisify<T>(fn: (payload: T) => void, convo: ConversationHandler, timeout?: number): (payload: T) => Promise<Response | null>;
+export declare function promisify<Params>(fn: (payload: Params) => void, convo: ConversationHandler, timeout?: number): (payload: Params) => Promise<Response | null>;