votcore/lib/types.d.ts

Vot Kit for Valensas Bots

import { SorunClient } from './channels/sorun';
import { TriggersClient } from './channels/triggers';
import { Action, ChannelClient, ChannelClientInterface, Context, Conversation, Flow, Message, User, VotClient } from './models';
/**
 * Environment setting
 */
export declare type Environment = 'test' | 'production' | 'development';
/**
 * The status of the conversation.
 * Started: Still on progress,
 * Yielded: The bot redirected to an agent,
 * Ended: The bot ended the conversation successfully,
 * Halted: The conversation was ended prematurely
 */
export declare type ConversationStatus = 'Started' | 'Yielded' | 'Ended' | 'Halted';
/**
 * All supported payload types for messages
 */
export declare type MessagePayloadType = 'text' | 'card' | 'url' | 'location' | 'null' | 'context';
/**
 * All possible message types
 * user: Message is coming from a user
 * agent: Message is coming from an agent
 * log: Message is a log message sent by the chat channel
 * bot: Message is coming from another bot
 * self: Message was created by the bot
 * trigger: Message is coming from task service
 */
export declare type MessageType = 'user' | 'agent' | 'log' | 'bot' | 'self' | 'trigger';
/**
 * Chat channel specific settings that are carried with the message
 */
export interface MessageChannelData {
    /**
     * An ID given to the message by the channel
     */
    id?: any;
    /**
     * An ID given to the user by the channel
     */
    userID?: any;
    /**
     * Secondary ID given to the message by the channel (Used for Sor'un)
     */
    uniqueID?: any;
}
/**
 * Chat channel specific settings that are carried with the conversation
 */
export interface ConversationChannelData {
    /**
     * An ID given to the conversation by the channel
     */
    id?: any;
    /**
     * Secondary ID given to the conversation by the channel (Used for Sor'un)
     */
    uniqueID?: any;
}
/**
 * Combination of all settings from all chat channels
 */
export interface ChannelSettings {
    /**
     * The token that comes with every message received from Sor'un
     */
    incomingHookToken?: string;
}
/**
 * Type of steps of a flow.
 * A flow can have actions or another flows as steps
 */
export interface FlowStepsType {
    [t: string]: Action<any, any, any> | Flow<any, any>;
}
/**
 * Parameters that are fed to every action body
 */
export interface ActionBodyParameters extends ExitParameters {
    /**
     * Received message
     */
    message: Message;
    /**
     * lient for the chat channel that is being used by the user
     */
    client: ChannelClient & ChannelClientInterface;
    /**
     * VoT Client to connect to VoT Services
     */
    votClient: VotClient;
    /**
     * An object that helps forming output of actions bodies.
     * Must be returned
     * Example: return result.next(...)
     */
    result: ActionBodyCallback;
    /**
     * The chat channel that is being used by the user
     */
    channel: keyof VotChannels;
}
/**
 * Parameters that are fed to every exit generators
 */
export interface ExitParameters {
    /**
     * Received message
     */
    message: Message;
    /**
     * Client for the chat channel that is being used by the user
     */
    client: ChannelClient & ChannelClientInterface;
    /**
     * VoT Client to connect to VoT Services
     */
    votClient: VotClient;
    /**
     * The chat channel that is being used by the user
     */
    channel: keyof VotChannels;
}
/**
 * Format of the data that is saved in context for every conversation
 */
export interface Data {
    [t: string]: any;
}
/**
 * Prototype interface for generating Context instances
 */
export interface ContextPrototype {
    /**
     * State Prototype.
     * Saves where the bot is at in the current flow.
     * Takes the root as the current flow
     */
    state?: Exit;
    /**
     * The flow that the bot is currently running.
     * Takes the root as the main flow so gives the full path except the steps provided by the state.
     */
    flow?: Exit;
    /**
     * The data that is being carried
     */
    data?: Data;
}
/**
 * Payload to generate UrlMessage instances
 */
export interface UrlPayload {
    /**
     * Title of the target website.
     * Can be obtained from <title>...</title> tags.
     */
    title?: string;
    /**
     * Description of the target website.
     * Can be obtained from <meta name="description" content="..." /> tags
     */
    description?: string;
    /**
     * Href of the link
     */
    url: string;
}
/**
 * Options to be used when sending URLs to users.
 */
export interface UrlReplyOptions {
    /**
     * Enables automatically scraping title and description for UrlPayload
     */
    discoverUrl?: boolean;
}
/**
 * Format for action body returns
 */
export declare type ActionBodyReturn = [ContextPrototype, boolean];
/**
 * Function provided to help format action body return values
 */
export interface ActionBodyCallback {
    /**
     * Method to be used to wait for user input after action body
     *
     * @param context Prototype Context to generate new Context after action body returns
     * @returns [ContextPrototype, goToNextAction] Returns the context prototype and false meaning the bot will wait for a new user input.
     */
    next(context: ContextPrototype): [ContextPrototype, boolean];
    /**
     * Method to be used to run the next action after returning from action body
     *
     * @param context Prototype Context to generate new Context after action body returns
     * @returns [ContextPrototype, goToNextAction] Returns the context prototype and false meaning the bot will run the next action.
     */
    passthrough(context: ContextPrototype): [ContextPrototype, boolean];
}
/**
 * Base interfae for channel messages
 */
export interface ChannelMessageInput {
}
/**
 * Base class that forces static methods to channel clients
 */
export declare class ChannelMessageStatic {
    /**
     * Produces an object in the form of channel message data from Message
     */
    static fromMessage: (message: Message) => {};
}
/**
 * A generic message type for different chat channels
 */
export interface ChannelMessage {
    /**
     * Converts the channel message into VoT Message instance
     *
     * @param conversation Current conversation
     * @returns Promise<Message> Returns a promise that resolves to a new message
     */
    toMessage(conversation: Conversation, user: User): Promise<Message>;
    /**
     * Used to find out which type of payload a message has from its properties
     *
     * @returns Promise<MessagePayloadType> Returns a promise that resolves the payload type of the message
     */
    getMessagePayloadType(): Promise<MessagePayloadType>;
    /**
     * Used to find out the type of the message from its properties
     *
     * @returns MessageType Returns the type of the message
     */
    getMessageType(): MessageType;
    /**
     * Used to parse the date that comes from the chat channel
     *
     * @returns Date Returns a javascript Date object
     */
    getDate(): Date;
}
/**
 * Simple exits can be passed to Flows or Actions.
 * These exits can only be strings or array of strings.
 * For more complicated exits with middleware or async functionality use Exit
 */
export declare type SimpleExit = string | string[];
/**
 * Exits are passed to Actions or Flows to specify possible outcomes of these components.
 * An exit may be
 *  - a string that contains the name of the next state
 *  - an array of strings that holds the path to an actions including its containing flow's name
 *  - a function that returns a string after some computation (conditional exits etc.)
 *  - a function that returns an array of strings
 *  - a function that returns a Promise that resolves to a string (async exit selection etc.)
 *  - a function that returns a Promise that resolves to an array of strings (async exit selection etc.)
 *
 * In function cases, the functions are fed with ExitParameters
 */
export declare type Exit = string | string[] | Promise<string> | Promise<string[]> | ((parameters: ExitParameters) => string) | ((parameters: ExitParameters) => string[]) | ((parameters: ExitParameters) => Promise<string>) | ((parameters: ExitParameters) => Promise<string[]>);
/**
 * Exits are possible out paths of Actions and Flows
 */
export interface Exits {
    [t: string]: Exit | undefined;
}
/**
 * Options define possible parameters that can be given to Actions and Flows
 */
export interface Options {
}
/**
 * Requirements specify context data keys that an Action needs to access in order to operate.
 * The global data is validated against action requirements and only the keys that are specified in Requirements is fed to the action through this.state
 */
export interface Requirements {
    [t: string]: any | undefined;
}
/**
 * The standard format that VoT Engine responses with intents
 */
export interface IntentResponse {
    certainty: number;
    name: string;
}
/**
 * Types of triggers that can be used with VoTCore
 */
export declare type TriggerType = 'Trigger' | 'Timeout';
/**
 * A Trigger is used to modify the state of a bot using HTTP methods.
 * The format of triggers are given in this interface
 */
export interface TriggerInterface {
    kind: TriggerType;
    task: Task;
}
/**
 * A prototype object that is used to generate Task instances using available methods.
 */
export interface TaskPrototype {
    id: string;
    conversation: Conversation;
    platform: Platform;
    user: User;
    [t: string]: any;
}
/**
 * Task interface.
 * This interface is the basis for scheduled tasks.
 * Examples: Timeout, Reminder, Reoccuring
 */
export interface Task {
    /**
     * ID of the task. Overwrites if the ID already exists.
     */
    id: string;
    /**
     * Conversation instance for the task
     */
    conversation: Conversation;
    /**
     * The url that scheduler service will use to POST the task request.
     */
    callback: string;
    /**
     * The chat channel that the current message was received from.
     */
    channel: keyof VotChannels;
    /**
     * The chat platform that the current message was received from.
     */
    platform: Platform;
    /**
     * The user that the task will affect.
     */
    user: User;
}
/**
 * One time task interface.
 * This interface is used for creating tasks that are triggered only once at a specific time.
 * Example: Timeout
 */
export interface OneTimeTask extends Task {
    /**
     * Exact moment the task should be triggered at.
     */
    date: Date;
    /**
     * New context that will be set after the task runs.
     */
    context: Context;
}
/**
 * The standard format that VoTScheduler expects in order to start running tasks.
 */
export interface TaskRequest {
    /**
     * ID of the task. VoTScheduler overwrites existing IDs.
     */
    id: string;
    /**
     * The POST body VoTScheduler responds with at task runtimes.
     * VoTScheduler posts this data on the specified dates.
     */
    body: {};
    /**
     * The URL that VoTScheduler will send the POST request to
     */
    callback: string;
}
/**
 * A type of Task that only runs once on the given Date
 */
export interface OneTimeTaskRequest extends TaskRequest {
    /**
     * The date that the task will run at
     */
    date: Date;
    body: {
        /**
         * VoT ID of the current conversation
         */
        conversationID: string;
        /**
         * New context that the bot should have after the task runs
         */
        context: Context;
        /**
         * Unique identifier of the task
         */
        taskID: string;
        /**
         * The chat channel that the task will affect.
         */
        channel: keyof VotChannels;
        /**
         * The chat platform that the task will affect.
         */
        platform: Platform;
        /**
         * The user that the task will affect.
         */
        user: User;
    };
}
/**
 * Channels that VoT is able to connect.
 * This interface is used to connect client objects to VoT
 */
export interface VotChannels {
    /**
     * Sor'un client connection point
     */
    Sorun?: SorunClient;
    /**
     * Triggers client connection point
     */
    Triggers?: TriggersClient;
}
/**
 * Interface for constructing channel clients
 */
export interface ClientConstructor {
    [t: string]: any;
}
/**
 * Interface for constructing channel clients
 */
export interface IChannelClient {
    /**
     * Constructor for channel clients
     */
    new (parameters: ClientConstructor): ChannelClient;
    /**
     * Returns a unique identifier from VoT conversation data
     * Example: conversation.channelData.id
     *
     * @param conversation Current conversation
     * @returns id Unique ID
     */
    getConversationIdentifier(conversation: Conversation): string;
}
/**
 * Possible chat platforms.
 */
export declare type Platform = 'any' | 'web' | 'android' | 'ios';
/**
 * Interface for adding examples questions
 */
export interface Example {
    /**
     * Name of the intent
     */
    name: string;
    /**
     * If true one of the examples will always be of this intent
     */
    static: boolean;
    /**
     * Example questions
     */
    questions: string[];
}