lib/component/sdk.js

  1. /* eslint-disable no-prototype-builtins */
  2. 'use strict';
  4. const { BaseContext } = require("./baseContext");
  5. const ComponentRequestSchemaFactory = require("./schema/componentRequestSchema");
  6. const { MessageModel } = require("../message/messageModel");
  8. // fix for MIECS-23476, we need to return "2.0" until all customers have migrated to 20.05 which
  9. // no longer checks whether version returned is a valid platform version
  10. // const sdkVersion = '2.0';
  11. const sdkVersion = require('../../package.json').version;
  13. // Response template
  14. const RESPONSE = {
  15.   platformVersion: undefined,
  16.   context: undefined,
  17.   action: undefined,
  18.   keepTurn: true,
  19.   transition: false,
  20.   error: false,
  21.   modifyContext: false
  22. };
  24. // Variable types supported by the dialog engine
  25. const CONST = {
  26.   SYSTEM_INVALID_USER_INPUT: 'system.invalidUserInput',
  27. };
  29. /**
  30.  * The Bots Node SDK uses this class to receive bot requests, which is provided
  31.  * to the custom component invocation.
  32.  * <p>
  33.  * It offers a comprehensive interface to reading context for the invocation
  34.  * as well as changing variables and sending results back to the dialog engine.
  35.  * </p>
  36.  * @memberof module:Lib
  37.  * @extends BaseContext
  38.  * @alias CustomComponentContext
  39.  * @example <caption>Context object used to invoke Custom Component</caption>
  40.  * 
  41.  * const MyCustomComponent = {
  42.  *   metadata: () => ({name: 'hello'}),
  43.  *   invoke: async (context) => {
  44.  *     // use conversation instance methods to respond, set variables, etc.
  45.  *     context.reply('Hello!');
  46.  *     context.transition();
  47.  *   }
  48.  * }
  49.  */
  50. class CustomComponentContext extends BaseContext {
  51.   /**
  52.    * @param {object} request - The request body
  53.    */
  54.   constructor(request) {
  55.     // Initilize the response, filling in platformVersion, context/vars
  56.     // from the incoming request as needed.
  57.     const response = Object.assign({}, RESPONSE, { platformVersion: request.platformVersion });
  58.     super(request, response, ComponentRequestSchemaFactory);
  60.     // Reset system.invalidUserInput variable if set to true.  Requested by runtime to do this in sdk
  61.     this._resetInvalidUserInput();
  62.   }
  64.   /**
  65.    * Retrieves the request body.
  66.    * @return {object} The request body.
  67.    */
  68.   request() {
  69.     return super.getRequest();
  70.   }
  72.   /**
  73.    * Retrieves the bot id.
  74.    * @return {string} The bot id.
  75.    */
  76.   botId() {
  77.     return this.request().botId;
  78.   }
  80.   /**
  81.    * Retrieves the sdk version.
  82.    * @return {string} The sdk version.
  83.    */
  84.   static sdkVersion() {
  85.     return sdkVersion;
  86.   }
  88.   /**
  89.    * Retrieves the platform version of the request.
  90.    * @return {string} The platform version.
  91.    */
  92.   platformVersion() {
  93.     return this.request().platformVersion;
  94.   }
  96.   /**
  97.    * Retrieves the raw payload of the current input message.
  98.    * @return {object} The raw payload.
  99.    */
  100.   rawPayload() {
  101.     return this.request().message.payload;
  102.   }
  104.   /**
  105.    * Retrieves the payload of the current input message in the common message format.
  106.    * @return {object} The common message payload.
  107.    */
  108.   messagePayload() {
  109.     return this.request().message.messagePayload;
  110.   }
  112.   /**  
  113.    * Retrieves the payload of the current input message. For backward compatibility purposes.  
  114.    * However, the payload returned may be in the new message format.
  115.    * @return {object} The message payload.
  116.    * @deprecated to be removed in favor of rawPayload() and messagePayload()
  117.    * @private
  118.    */
  119.   payload() {
  120.     this.logger().warn("conversation SDK payload() is deprecated in favor of messagePayload()"); 
  121.     return this.rawPayload();
  122.   }
  124.   /**
  125.    * Retrieves the channel type of the current input message.
  126.    * @return {string} The channel type - facebook, webhook, test, etc.
  127.    */
  128.   channelType() {
  129.     return this.request().message.channelConversation.type;
  130.   }
  132.   /**
  133.    * Retrieves the channel Id of the current input message.
  134.    * @return {string} The channel id.
  135.    */
  136.   channelId() {
  137.     return this.request().message.channelConversation.channelId;
  138.   }
  141.   /**
  142.    * Retrieves the userId for the current input message.
  143.    * @return {string} The userId.
  144.    */
  145.   userId() {
  146.     return this.request().message.channelConversation.userId;
  147.   }
  149.   /**
  150.    * Retrieves the sessionId for the current input message.
  151.    * @return {string} The sessionId.
  152.    */
  153.   sessionId() {
  154.     return this.request().message.channelConversation.sessionId;
  155.   }
  157.   // retrieve v1.0 facebook postback
  158.   _postback10() {
  159.     const rawPayload = this.rawPayload();
  160.     if (rawPayload && this.channelType() === 'facebook') {
  161.       if (rawPayload.hasOwnProperty('postback') && rawPayload.postback.hasOwnProperty('payload')) {
  162.         return rawPayload.postback.payload;
  163.       }
  164.     }
  165.     return null;
  166.   }
  168.   /**
  169.    * Retrieves the postback of the current input message.
  170.    * If the input message is not a postback, this will return null.
  171.    * @return {object} The postback payload.
  172.    */
  173.   postback() {
  174.     let postback = null;
  176.     const messagePayload = this.messagePayload();
  177.     if (messagePayload && messagePayload.postback) {
  178.       postback = messagePayload.postback;
  179.     }
  180.     if (!postback) {
  181.       postback = this._postback10();
  182.     }
  183.     return postback;
  184.   }
  186.   // return v1.0 facebook text and quick_reply text
  187.   _text10() {
  188.     const rawPayload = this.rawPayload();
  189.     if (rawPayload && this.channelType() === 'facebook') {
  190.       if (rawPayload.hasOwnProperty('message')) {
  191.         if (rawPayload.message.hasOwnProperty('quick_reply') && rawPayload.message.quick_reply.hasOwnProperty('payload')) {
  192.           return rawPayload.message.quick_reply.payload;
  193.         } else if (rawPayload.message.hasOwnProperty('text')) {
  194.           return rawPayload.message.text;
  195.         }
  196.       }
  197.     }
  198.     return null;
  199.   }
  201.   /**
  202.    * Retrieves the text of the current input message.
  203.    * Eventually not all messages will have a text value, in which case
  204.    * this will return null.
  205.    * @return {string} The text of the input message.
  206.    */
  207.   text() {
  208.     let text = null;
  210.     const messagePayload = this.messagePayload();
  211.     if (messagePayload) {
  212.       if (messagePayload.text) {
  213.         text = messagePayload.text;
  214.       } else {
  215.         const postback = this.postback();
  216.         if (postback && typeof postback === 'string') {
  217.           text = postback;
  218.         }
  219.       }
  220.     }
  221.     if (!text) {
  222.       text = this._text10();
  223.     }
  224.     return text;
  225.   }
  227.   /**
  228.    * Retrieves the attachment of the current input message.
  229.    * If the input message is not an attachment, this will return null.
  230.    * @return {object} The attachment.
  231.    */
  232.   attachment() {
  233.     let attachment = null;
  235.     const messagePayload = this.messagePayload();
  236.     if (messagePayload && messagePayload.attachment) {
  237.       attachment = messagePayload.attachment;
  238.     }
  239.     return attachment;
  240.   }
  242.   /**
  243.    * Retrieves the location of the current input message.
  244.    * If the input message does not contain a location, this will return null.
  245.    * @return {object} The location.
  246.    */
  247.   location() {
  248.     let location = null;
  250.     const messagePayload = this.messagePayload();
  251.     if (messagePayload && messagePayload.location) {
  252.       location = messagePayload.location;
  253.     }
  254.     return location;
  255.   }
  257.   /**
  258.    * Retrieves the properties defined for the current state.
  259.    * @return {object} The properties
  260.    */
  261.   properties() {
  262.     return this.request().properties || {};
  263.   }
  265.   /**
  266.    * Returns the MessageModel class for creating or validating messages to or from bots.
  267.    * @return {MessageModel} The MessageModel class
  268.    * @deprecated Use getMessageFactory() instead
  269.    */
  270.   MessageModel() {
  271.     return super.getMessageModel();
  272.   }
  274.   /**  
  275.    * Sets the action to return from this component, which will determine the
  276.    * next state in the dialog.
  277.    *
  278.    * @param {string} a - action name
  279.    * @deprecated to be removed in favor of transition(action)
  280.    * @private
  281.    */
  282.   action(a) {
  283.     this.logger().warn("conversation SDK action() is deprecated in favor of transition(action)"); 
  284.     if (a === undefined) {
  285.       return this.response().action;
  286.     }
  288.     this.response().action = a;
  289.     return this;
  290.   }
  292.   /**
  293.      * Call this method if the input is not understood, and this would allow the bots runtime to 
  294.      * handle the issue.  The bots runtime may just display the message to the user and execute the same component again, or
  295.      * it may try to interpret the input and process differently.
  296.      * @param {object|string|MessageModel} [r] - optional payload to be sent to user.  payload could also be a string for text response
  297.      */
  298.   invalidUserInput(r) {
  299.     this.variable(CONST.SYSTEM_INVALID_USER_INPUT, true);
  300.     this.reply(r||'Input not understood.  Please try again');
  301.     return this;
  302.   }
  304.   _resetInvalidUserInput() {
  305.     if (this.variable(CONST.SYSTEM_INVALID_USER_INPUT) === true) {
  306.       this.variable(CONST.SYSTEM_INVALID_USER_INPUT, false);
  307.     }
  308.   }
  309.   
  310.   /** 
  311.    * Set "exit" to true when your component has replies it wants to send to
  312.    * the client.
  313.    * <p>
  314.    * The SDK's "reply" function automatically sets "exit" to true, but
  315.    * if you manually modify the response to send replies then you will need
  316.    * to set this explicitly.
  317.    * </p>
  318.    * @private
  319.    * @deprecated to be removed in favor of keepTurn(boolean)
  320.    */
  321.   exit(e) {
  322.     this.logger().warn("conversation SDK exit() is deprecated in favor of keepTurn(boolean)"); 
  323.     this.response().keepTurn = !e;
  324.     return this;
  325.   }
  327.   /**
  328.    * "keepTurn" is used to indicate if the Bot/component should send the next replies, or
  329.    * or if the Bot/component should wait for user input (keepTurn = false).
  330.    * <p>
  331.    * The SDK's "reply" function automatically sets "keepTurn" to false.
  332.    * </p>
  333.    * @param {boolean} [k] - whether to keep the turn for sending more replies
  334.    */
  335.   keepTurn(k) {
  336.     this.response().keepTurn = (typeof k === "undefined" ? true : !!k);
  337.     return this;
  338.   }
  340.   /**
  341.    * "releaseTurn" is the shorthand for keepTurn(false)
  342.    * @param {boolean} [k] - whether to keep the turn for sending more replies
  343.    */
  344.   releaseTurn(k) {
  345.     this.response().keepTurn = (typeof k === "undefined" ? false : !k);
  346.     return this;
  347.   }
  349.   /**  
  350.    * Set "done" to true when your component has completed its logic and
  351.    * the dialog should transition to the next state.
  352.    * <p>
  353.    * This is only meaningful when you are sending replies (ie you have also
  354.    * set "exit" to true).  If you are not sending replies ("exit" is false,
  355.    * the default) then "done" is ignored; the dialog always moves to the next
  356.    * state.
  357.    * </p>
  358.    * If "exit" is true (replies are being sent), then leaving "done" as false
  359.    * (the default) means the dialog will stay in this state after sending
  360.    * the replies, and subsequent user input will come back to this component.
  361.    * This allows a component to handle a series of interactions within itself,
  362.    * however the component is responsible for keeping track of its own state
  363.    * in such situations.
  364.    * <p>
  365.    * Setting "done" to true will transition to the next state/component after
  366.    * sending the replies.
  367.    * </p>
  368.    * @private
  369.    * @deprecated to be removed in favor of transition()
  370.    */
  371.   done(d) {
  372.     this.logger().warn("conversation SDK done() is deprecated in favor of transition()"); 
  373.     this.response().transition = !!d;
  374.     return this;
  375.   }
  377.   /**
  378.    * Call <code>transition()</code> when your component has completed its logic and
  379.    * the dialog should transition to the next state, after replies (if any) are sent.
  380.    * <p>
  381.    * If <code>transition()</code> is not called, the dialog will stay in this state after sending
  382.    * the replies (if any), and subsequent user input will come back to this component.
  383.    * This allows a component to handle a series of interactions within itself,
  384.    * however the component is responsible for keeping track of its own state
  385.    * in such situations.
  386.    * </p>
  387.    * <code>transition()</code> will cause the dialog to transition to the next state.
  388.    * transition(outcome) will set te outcome of the component that would be used to
  389.    * determine the next state to transition to.
  390.    * @param {string} [t] - outcome of component
  391.    */
  392.   transition(t) {
  393.     this.response().transition = true;
  394.     if (typeof t !== 'undefined') {
  395.       this.response().action = t;
  396.     }
  397.     return this;
  398.   }
  400.   /**
  401.    * Sets the error flag on the response.
  402.    * @param {boolean} e - sets error if true
  403.    */
  404.   error(e) {
  405.     this.response().error = !!e;
  406.     return this;
  407.   }
  409.   /**
  410.    * Adds a reply to be sent back to the user. May be called multiple times to send multiple replies in a given response.  
  411.    * Automatically sets the <code>keepTurn</code> as false.
  412.    * </p>
  413.    * @param {object} payload - can take a string message, a message created by the MessageFactory, or a message created by 
  414.    * the deprecated MessageModel.
  415.    * @param {object} [channelConversation] - to override the default channelConversation from request
  416.    * @returns the message payload in JSON format
  417.    */
  418.   reply(payload, channelConversation) {
  419.     var response = {
  420.       tenantId: this.request().message.tenantId,
  421.       channelConversation: channelConversation || Object.assign({}, this.request().message.channelConversation)
  422.     };
  423.     var messagePayload =  super.constructMessagePayload(payload);
  424.     if (messagePayload) {
  425.       response.messagePayload = messagePayload;
  426.     } else {
  427.       // is invalid raw message payload, keep for backwards compatibility
  428.       var rawMessagePayload = MessageModel.rawConversationMessage(payload);
  429.       var messageModel = new MessageModel(rawMessagePayload);
  430.       response.payload = messageModel.rawPayload();  
  431.     }
  433.     this.response().messages = this.response().messages || [];
  434.     this.response().messages.push(response);
  436.     // "keepTurn" false which signals to the engine to send replies and wait for user input
  437.     this.keepTurn(false);
  439.     return this;
  440.   }
  443.   // The HTTP response body
  444.   response() {
  445.     return super.getResponse();
  446.   }
  448.   // BUGBUG: workaround for https://jira.oraclecorp.com/jira/browse/MIECS-2748
  449.   resolveVariable(variable) {
  450.     return variable.startsWith('${') ? null : variable;
  451.   }
  453.   /** 
  454.    * When expecting an out of band conversation continuation, such as a
  455.    * user following the OAuth flow, completing a form and hitting submit, or
  456.    * a human support agent or other third party sending a message, issue a
  457.    * limited use token to allow calling back into Bots via the generic callback
  458.    * endpoint.
  459.    * The provided token should be a UUID or other unique and random number.  By setting it
  460.    * here in the response the Bot will await a reply with that token and use it to
  461.    * thread the message back into the current conversation with that user.
  462.    * @param {string} callbackToken - token generated by you to allow reauthentication back 
  463.    * into this conversation.  Should be unique, like userId + random.  It is ok to reissue 
  464.    * the same token for the same conversation.
  465.    * @private
  466.    */
  467.   setCallbackToken(callbackToken) {
  468.     this.response().callbackToken = (typeof callbackToken === "undefined" ? null : callbackToken);
  469.     return this;
  470.   }
  471. }
  473. module.exports = {
  474.   CustomComponentContext,
  475. }