@nlxai/core 1.2.3 → 1.2.4-alpha.10

package/lib/index.d.ts

@@ -7,19 +7,37 @@ export declare const version: string;
  */
 export interface Config {
     /**
-     * The URL at which your conversational application is running.
-     * Fetch this from the application's API channel tab.
+     * The URL at which your conversational application is running. Fetch this from the application's API channel tab.
+     * Currently, there are a few ways to specify the application URL:
+     * - (recommended) leave out `applicationUrl` and specify `protocol`, `host`, `deploymentKey` and `channelKey`.
+     * - specify the full `applicationUrl` as well as the `protocol`.
+     * - (legacy) specify the `applicationUrl` generated either as an HTTP or websocket URL. Use `experimental.streamHttp` to control streaming.
      */
     applicationUrl?: string;
+    /**
+     * Specify the protocol (http, websocket or httpWithStreaming)
+     */
+    protocol?: Protocol;
+    /**
+     * Hostname of the application deployment, without a leading `https://`.
+     */
+    host?: string;
+    /**
+     * Deployment key.
+     */
+    deploymentKey?: string;
+    /**
+     * Channel key.
+     */
+    channelKey?: string;
+    /**
+     * API key.
+     */
+    apiKey?: 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;
-    };
+    headers?: Record<string, 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).
      */
@@ -55,6 +73,11 @@ export interface Config {
      * @internal
      */
     experimental?: {
+        /**
+         * Check whether HTTP streaming should be enabled. Defaults to `true`.
+         * @deprecated use the protocol setting instead.
+         */
+        streamHttp?: boolean;
         /**
          * Simulate alternative channel types
          */
@@ -145,6 +168,15 @@ export interface ConversationHandler {
      * @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
@@ -224,6 +256,23 @@ export interface SlotValue {
      */
     value: any;
 }
+/**
+ * The protocol used to communicate with the application
+ */
+export declare enum Protocol {
+    /**
+     * Regular encrypted HTTPS, without support for post-escalation message handling, interim messages and other streaming features.
+     */
+    Https = "https",
+    /**
+     * Encrypted HTTPS with streaming enabled. This is the default setting and supports interim messages. Does not support post-escalation message handling.
+     */
+    HttpsWithStreaming = "httpsWithStreaming",
+    /**
+     * Websocket, with support for post-escalation message handling.
+     */
+    Websocket = "websocket"
+}
 /**
  * Response type
  */
@@ -351,6 +400,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
@@ -541,6 +600,52 @@ export type Response = ApplicationResponse | UserResponse | FailureMessage;
  * The time value in milliseconds since midnight, January 1, 1970 UTC.
  */
 export type Time = number;
+/**
+ * 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;
+        /** Label for comment */
+        comment?: string;
+    };
+}
+/**
+ * @inline @hidden
+ */
+export type FeedbackType = {
+    /** A binary feedback type is a thumbs up/down sort of choice. */
+    type: "binary";
+    /** Configuration specific to binary feedback. */
+    config: BinaryFeedbackConfig;
+};
+/**
+ * @inline @hidden
+ */
+export interface BinaryFeedbackConfig {
+    /** Value to send for positive feedback. Default `1`. */
+    positiveValue: number;
+    /** Value to send for negative feedback. Default `-1`. */
+    negativeValue: number;
+}
 /**
  * @hidden
  */
@@ -709,7 +814,15 @@ export interface VoicePlusMessage {
  * Handler events
  * @event voicePlusCommand
  */
-export type ConversationHandlerEvent = "voicePlusCommand";
+export type ConversationHandlerEvent = "voicePlusCommand" | "interimMessage";
+/**
+ * Voice+ command listener
+ */
+export type VoicePlusCommandListener = (payload: any) => void;
+/**
+ * Interim message listener
+ */
+export type InterimMessageListener = (message?: string) => void;
 /**
  * Dictionary of handler methods per event
  */
@@ -717,7 +830,11 @@ export interface EventHandlers {
     /**
      * Voice+ command event handler
      */
-    voicePlusCommand: (payload: any) => void;
+    voicePlusCommand: VoicePlusCommandListener;
+    /**
+     * Interim message event handler
+     */
+    interimMessage: InterimMessageListener;
 }
 /**
  * The callback function for listening to all responses.
@@ -809,3 +926,71 @@ export declare const getCurrentExpirationTimestamp: (responses: Response[]) => n
  * @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<Params>(fn: (payload: Params) => void, convo: ConversationHandler, timeout?: number): (payload: Params) => Promise<Response | null>;
+/**
+ *  @inline @hidden
+ */
+export interface VoicePlusStepConfig {
+    /** * the API key generated for the Voice+ script. Note that this value is different from the API key you would pass to {@link createConversation}. You can control the API key on the Voice+ script settings page.  */
+    apiKey: string;
+    /** The ID of the Voice+ script.  */
+    scriptId?: string;
+    /** Your workspace ID. */
+    workspaceId: 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");
+     * ```
+     */
+    conversationId: string;
+    /**
+     * The user's language code, consistent with the language codes defined on the Voice+ script.
+     */
+    languageCode: string;
+    /** Which step to send.  */
+    step: StepInfo;
+    /** Any context. */
+    context: Context;
+    /** Set to `true` to help debug issues or errors. Defaults to `false`. */
+    debug?: boolean;
+    /** Used for library testing @internal @hidden */
+    dev?: boolean;
+}
+/**
+ * Step information, either a step ID as a single string or an object
+ */
+export type StepInfo = string | {
+    /**
+     * Step ID
+     */
+    stepId: string;
+    /**
+     * Step trigger description
+     */
+    stepTriggerDescription?: string;
+};
+/**
+ * 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.
+ * @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",
+ * });
+ * ```
+ * @param configuration - Configuration for sending the step. Many of the values can be found on the deployment modal of the Voice+ script.
+ */
+export declare const sendVoicePlusStep: ({ apiKey, workspaceId, conversationId, scriptId, languageCode, step, context, debug, dev, }: VoicePlusStepConfig) => Promise<void>;