index.js

'use strict'

/**
 * Watson Work Services SDK
 * @module watsonworkspace-sdk
 */

const EventEmitter = require('events')
const fs = require('fs')
const graphql = require('./graphql')
const imageSize = require('image-size')
const mime = require('mime-types')
const request = require('request-promise')
const logger = require('winston')
const oauth = require('./oauth')
const path = require('path')
const Promise = require('bluebird')
const ui = require('./ui')

const baseUrl = 'https://api.watsonwork.ibm.com'

// controls the request-promise logging level; logs the raw req/res data
require('request-debug')(request, (type, data, r) => {
  if (logger.level === 'debug') {
    logger.debug(JSON.stringify(data, null, 2))
  }
})

/**
 * A Watson Work Services App (SDK instance).
 * @class
 */
module.exports = class SDK extends EventEmitter {
  constructor (appId, appSecret, token) {
    super()

    this.appId = appId
    this.appSecret = appSecret
    this.token = token
  }

  /**
   * Picks an object from server response, which is a Promise. If a response is { space : {displayName: "foo"} },
   * pick('space') returns {displayName: "foo"}.
   * @param {string} property Fields returned in user informatation e.g. id, displayName, email
   * @returns {Promise<Object>} Promise containing the picked object
   */
  pick (property, promise) {
    return new Promise((resolve, reject) => {
      promise.then(response => {
        // guard against the response being a raw string
        if (typeof response === 'string') {
          logger.warn(`Can not find '${property}'; converting to JSON`)
          response = JSON.parse(response) // convert to JSON for picking
        }

        // check if the property is present
        if(response[property] === undefined) {
          console.error(`No '${property}' field in ${JSON.stringify(response, null, 2)}`)
        }

        resolve(response[property])
      })
      .catch(err => reject(err))
    })
  }

  /**
   * Fulfills a Promise and calls map() of the items defined by the property.
   * @param {string} property The property containing a collection
   * @param {function} fn The function to apply in map()
   * @param {Promise<Object>} promise Promise returned from a server response
   * @returns {Promise<Object>} Promise containing the updated data
   */
  map (property, fn, promise) {
    return new Promise((resolve, reject) => {
      promise.then(response => {
        if (response[property]) {
          response[property] = response[property].map(fn)
        } else {
          logger.warn(`Map requested on missing property '${property}'`)
        }
        resolve(response)
      })
      .catch(err => reject(err))
    })
  }

  /**
   * Converts a JSON string to an object.
   * @param {string} obj String to convert
   * @returns {Object} Converted object
   */
  jsonify (obj) {
    return JSON.parse(obj)
  }

  /**
   * Authenticates the SDK with Watson Work Services. The resulting JWT token will be stored
   * for subsequent use. The token can be obtained from the Promise, but it is not necessary.
   * If a faiure occurs, the process will re-attempt every second for ten tries.
   * The JWT token will be refreshed automatically based on the expiration set in the response.
   * @returns {Promise<string>} Promise containing the app's JWT token
   */
  authenticate () {
    return new Promise((resolve, reject) => {
      const retry = 10000
      let errors = 0

      if (this.appId === undefined || this.appSecret === undefined ||
        this.appId.length !== 36 || this.appSecret.length !== 28) {
        reject(new Error(`appId ${this.appId} or appSecret has a problem`))
      } else {
        oauth.run(
          this.appId,
          this.appSecret,
          (err, token) => {
            if (err) {
              logger.error(`Failed to get JWT token; retrying in ${retry / 1000} seconds`)
              errors++
              if (errors > 10) {
                reject(new Error(`Too many JWT token attempts giving up`))
              }
              setTimeout(this.authenticate, retry)
              return
            }

            if (this.token) {
              logger.verbose('Refreshed access token')
            }

            this.token = token()
            resolve(token())
          })
      }
    })
  }

  /**
   * Sends GraphQL to Watson Work Services. The GraphQL can either be the raw string or JSON format.
   * @param {string|Object} graphql The GraphQL query or mutation
   * @returns {Promise<Object>} Promise containing the server response
   */
  sendGraphql (graphql) {
    const headers = {
      'Content-Type': typeof graphql === 'string' ? 'application/graphql' : 'application/json',
      'x-graphql-view': 'PUBLIC, BETA, EXPERIMENTAL'
    }

    return this.pick('data', this.sendRequest(`graphql`, 'POST', headers, graphql))
  }

  /**
   * Sends a request to Watson Work Services.
   * If a POST body is set, it will be checked whether it is a string or Object.
   * If the body is an Object, the response is assumed to also be JSON.
   * @param {string} route The route e.g. spaces
   * @param {string} method HTTP method e.g. GET or POST
   * @param {Object} headers HTTP headers
   * @param {string|Object} [body] Optional HTTP body if POSTing
   * @returns {Promise<Object>} Promise containing the server response
   */
  sendRequest (route, method, headers, body) {
    // add the auth header for convenience
    headers.Authorization = `Bearer ${this.token}`

    const options = {
      method: method,
      uri: `${baseUrl}/${route}`,
      headers: headers,
      body: body,
      json: (typeof body) === 'object',
      resolveWithFullResponse: false
    }

    logger.verbose(`${method} to '${route}'`)

    return request(options)
  }

  /**
   * Retrieves user configuration data.
   * @param {string} configurationToken The configuration token sent by Watson Work Services 
   * @returns {Promise<Object>} Promise containing the configuration data
   */
  getConfigurationData (configurationToken) {
    return this.sendRequest(
      `v1/apps/${this.appId}/configurationData/${configurationToken}`, 'GET', {})
  }

  /**
   * Get information about a person.
   * @param {string[]} fields Fields returned in user informatation e.g. id, displayName, email
   * @returns {Promise<Object>} Promise containing the person object
   */
  getMe (fields) {
    const json = {
      query: graphql.getMe(fields)
    }

    return this.pick('me', this.sendGraphql(json))
  }

  /**
   * Get information about a message.
   * @param {string} id Message ID e.g. 5a79f65de4b0d880b508ed57
   * @param {string[]} fields Fields returned in the message e.g. id, content, annotations
   * @returns {Promise<Object>} Promise containing the message object
   */
  getMessage (id, fields) {
    const json = {
      query: graphql.getMessage(fields),
      variables: {
        id: id
      }
    }

    return this.map('annotations', this.jsonify, this.pick('message', this.sendGraphql(json)))
  }

  /**
   * Get information about a space such as membership.
   * @param {string} id Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string[]} fields Fields returned in space informatation
   * @returns {Promise<Object>} Promise containing the space object
   */
  getSpace (id, fields) {
    const json = {
      query: graphql.getSpace(fields),
      variables: {
        id: id
      }
    }

    return this.pick('space', this.sendGraphql(json))
  }

  /**
   * Download a file 
   * @param {*} fileId 
   * @returns {Promise<Object>} Promise containing the file stream
   */
  getFile (fileId) {
    return new Promise((resolve, reject) => {
      let uri = `${baseUrl}/files/api/v1/files/file/${fileId}`;
      let options = {
        method: 'GET',
        uri: uri,
        headers: {
          Authorization: `Bearer ${this.token}`
        }
      };
      request(options)
      .then(result => {
        let json = JSON.parse(result)
        let resourceurl = json.entries[0].urls.redirect_download
        const dlResourceOptions = {
          url: resourceurl,
          headers: {
            Authorization: `Bearer ${this.token}`
          },
          encoding: null
        }
        request(dlResourceOptions)
        .then(body => {
          resolve(body)
        })
        .catch(err => {
          reject(err)
        });
      })
      .catch(err => {
        reject(err)
      });
    }); 
  }

  /**
   * Sends a file into a space. If the file is an image, the width and height can
   * be optionally specified. If omitted, the width and height will reflect the
   * full size. For all other files, the mime-type will inferred on a best effort.
   * @param {string} spaceId Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string} file Full path to the file
   * @param {number} [width] Optional width to set if file is an image
   * @param {number} [height] Optional height to set if file is an image
   * @returns {Promise<Object>} Promise containing the space object
   */
  sendFile (spaceId, file, width, height) {
    logger.verbose(`Sending file '${file}' to conversation '${spaceId}'`)

    let uri = `${baseUrl}/v1/spaces/${spaceId}/files`

    const mimeType = mime.contentType(path.extname(file))

    if (width && height) {
      uri += `?dim=${width}x${height}`
    } else {
      const isImage = mimeType.toLowerCase().includes('image/')

      if (isImage) {
        // figure out the dimensions and send full size
        const dim = imageSize(file)
        uri += `?dim=${dim.width}x${dim.height}`
      }
    }

    const options = {
      method: 'POST',
      uri: uri,
      headers: {
        Authorization: `Bearer ${this.token}`,
        'content-type': 'multipart/form-data'
      },
      resolveWithFullResponse: false,
      formData: {
        file: {
          value: fs.createReadStream(file),
          options: {
            filename: path.parse(file).base,
            contentType: mimeType
          }
        }
      }
    }

    return request(options)
  }


  /**
   * Similar to sendFile above, but uses a stream instead of a file from the file system.
   * If the file is an image, the width and height can
   * be optionally specified. If omitted, the width and height will reflect the
   * full size. For all other files, the mime-type will inferred on a best effort.
   * @param {string} spaceId Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string} fileStream a stream of the file contents
   * @param {string} fileName the name of the file
   * @param {string} mimeType the mime type of the file
   * @returns {Promise<Object>} Promise containing the space object
   */
  sendFileStream (spaceId, fileStream, fileName, mimeType) {
    logger.verbose(`Sending file stream to conversation '${spaceId}'`)

    let uri = `${baseUrl}/v1/spaces/${spaceId}/files`

    const isImage = mimeType.toLowerCase().includes('image/')
    if (isImage) {
      // figure out the dimensions and send full size
      const dim = imageSize(fileStream)
      uri += `?dim=${dim.width}x${dim.height}`
    }

    const options = {
      method: 'POST',
      uri: uri,
      headers: {
        Authorization: `Bearer ${this.token}`,
        'content-type': 'multipart/form-data'
      },
      resolveWithFullResponse: false,
      formData: {
        file: {
          value: fileStream,
          options: {
            filename: fileName,
            contentType: mimeType
          }
        }
      }
    }

    return request(options)
  }

  /**
   * Sends a text message into a space.
   * @param {string} spaceId Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string|Object|Array} content Content to be sent
   * @returns {Promise<Object>} Promise containing the message
   */
  sendMessage (spaceId, content) {
    logger.verbose(`Sending message to conversation '${spaceId}'`)

    const body = {
      type: 'appMessage',
      version: '1',
      annotations: []
    }

    // determine the type of content the user is tying to send
    const type = typeof content
    switch (type) {
      case 'string':
        body.annotations.push(ui.message(content))
        break
      case 'object':
        if (Array.isArray(content)) {
          body.annotations = content
        } else {
          body.annotations = [content]
        }
        break
      default:
        logger.error(`Error sending message of type '${type}'`)
    }

    return this.sendRequest(`v1/spaces/${spaceId}/messages`, 'POST', {}, body)
  }

  /**
   * An alternative way to send a text message to a space.
   * @param {string} spaceId Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string} content Content to be sent
   * @returns {Promise<Object>} Promise containing the message
   */
  sendSynchronousMessage (spaceId, content) {
    const json = {
      query: graphql.createSynchronousMessage,
      variables: {
        input: {
          conversationId: spaceId,
          content: content
        }
      }
    }

    return this.sendGraphql(json)
  }

  /**
   * Adds a member to a space.
   * @param {} spaceId Space ID e.g. 57cf270ee4b06c8b753629e6
   * @param {string[]} memberIds Array of member IDs e.g. 3c845f47-c56a-4ca9-a1cb-12dbebd72c3b
   * @returns {Promise<Object>} Promise containing the updated space
   */
  addMember (spaceId, memberIds) {
    const json = {
      query: graphql.addMember,
      variables: {
        input: {
          id: spaceId,
          members: memberIds,
          memberOperation: 'ADD'
        }
      }
    }

    return this.pick('updateSpace', this.sendGraphql(json))
  }

  /**
   * Adds a focus to a specific message. The message must contain content.
   * If the message is obtained from getMessage(), ensure the content field is set.
   * @param {Object} message The message returned from getMessage() or a webhook
   * @param {string} phrase The phrase to add the message (it must be present in content)
   * @param {string} lens The lens name to be added
   * @param {string} category The category for the lens
   * @param {string[]} actions The actions that can be taken e.g. ['commit-code']
   * @param {*} [payload] Data to be persisted in the focus and passed to receivers
   * @param {*} [hidden] True if hidden from Moments
   * @returns {Promise<Object>} Promise containing the updated message
   */
  addMessageFocus (message, phrase, lens, category, actions, payload, hidden) {
    let id
    let pos = -1

    if (message.id) {
      id = message.id
    } else {
      id = message.messageId
    }

    // the message's content differs based on how the message was created
    if (message.annotations && message.annotations[0].type === 'generic') {
      // app created
      pos = message.annotations[0].text.indexOf(phrase)
    } else {
      // user created
      pos = message.content.indexOf(phrase)
    }

    logger.verbose(`Adding message focus to message '${id}'`)

    const json = {
      query: graphql.addMessageFocus,
      variables: {
        input: {
          messageId: id,
          messageFocus: {
            phrase: phrase,
            lens: lens,
            category: category,
            actions: actions,
            confidence: 0.99,
            payload: payload ? JSON.stringify(payload) : '',
            start: pos,
            end: pos + phrase.length,
            version: 1,
            hidden: hidden || false
          }
        }
      }
    }

    return this.sendGraphql(json)
  }

  /**
   * Sends a targetted message (action fulfillment) to a user.
   * @param {string} userId The user's ID e.g. 3c845f47-c56a-4ca9-a1cb-12dbebd72c3b
   * @param {Object} annotation The annotation obtained from the 'actionSelected' event 
   * @param {Object[]} items UI items to be added to the resulting dialog
   * @returns {Promise<Object>} Promise containing the updated message
   */
  sendTargetedMessage (userId, annotation, items) {
    logger.verbose(`Sending targeted message to user ${userId}`)

    const input = {
      conversationId: annotation.conversationId,
      targetUserId: userId,
      targetDialogId: annotation.targetDialogId
    }

    if (!Array.isArray(items)) {
      items = [items]
    }

    if (items.length === 0) {
      logger.error(`Targetted message has no annotations or attachments for ${userId}`)
    }

    // check the type of user interface
    if (items.length && items[0].genericAnnotation) {
      input.annotations = items
    } else {
      input.attachments = items
    }

    const json = {
      query: graphql.createTargetedMessage,
      variables: {
        input: input
      }
    }

    return this.sendGraphql(json)
  }

  /**
   * Extracts the AlchemyAPI data (i.e. entities, keywords, concepts, ...) into a
   * single object.
   * @param {Object} message Message containing annotation data
   * @returns {Object} Object containing AlchemyAPI data
   */
  extractInformation (message) {
    const messageAnnotations = message.annotations  // already converted to JSON

    const nlp = {
      keywords: [],
      entities: [],
      concepts: [],
      taxonomy: [],
      dates: [],
      docSentiment: {},
      relations: []
    }

    if (messageAnnotations) {
      // pluck out cognitive data
      messageAnnotations.forEach(annotation => {
        const annotationType = annotation.type

        // 'message-nlp-keywords' -> 'keywords'
        const shortened = annotationType.substring(annotationType.lastIndexOf('-') + 1)

        // only handle Alchemy annotations (ie disregard a message-focus)
        if (nlp[shortened]) {
          if (shortened === 'docSentiment') {
            nlp[shortened] = annotation[shortened]
          } else {
            nlp[shortened] = (annotation[shortened])
          }
        }
      })
    } else {
      console.warn(`Information extraction on message with undefined annotations`)
    }

    return nlp
  }

  /**
   * Uploads a JPEG photo to a user's or app's profile.
   * @param {string} file The full path to the file.
   * @returns {Promise<Object>} Promise containing the server response
   */
  uploadPhoto (file) {
    let uri = `${baseUrl}/photos/`

    const options = {
      method: 'POST',
      uri: uri,
      headers: {
        Authorization: `Bearer ${this.token}`,
        'content-type': 'multipart/form-data'
      },
      resolveWithFullResponse: false,
      formData: {
        file: {
          value: fs.createReadStream(file),
          options: {
            filename: path.parse(file).base,
            contentType: 'image/jpeg'
          }
        }
      }
    }

    return request(options)
  }

  /**
   * Get the current human-readable status of a space created from a template
   * @param {string} spaceId 
   * @returns {string} the current status
   */
  getStatus(spaceId) {
    return new Promise((resolve, reject) => {
      const query = `query getSpace {
        space(id: "${spaceId}") {
          statusValueId
          templateInfo {
            spaceStatus {
              defaultValue
              acceptableValues {
                id
                displayName
              }
            }
          }
        }
      }
      `;
      this.sendGraphql(query)
      .then(result => {
        const acceptableValue = result.space.templateInfo.spaceStatus.acceptableValues.find(function(value) {
          return value.id === result.space.statusValueId;
        });
        resolve(acceptableValue.displayName);
      })
      .catch(err => {
        reject(err);
      });
    });
  }

  /**
   * Set the status of a space created from a template
   * @param {string} spaceId The space Id
   * @param {string} newStatus The human-readable status to set
   */
  setStatus(spaceId, newStatus) {
    return new Promise( (resolve, reject) => {
      // first get the acceptable status values
      const query = `query getSpace {
         space(id: "${spaceId}") {    
           templateInfo {
             spaceStatus {
               acceptableValues {
                 id
                 displayName
               }
             }
           }
         }
       }`;
      this.sendGraphql(query)
      .then(results => {
        // now find the one which matches our new status
        var statusValue = results.space.templateInfo.spaceStatus.acceptableValues.find(function(value) {
          return value.displayName === newStatus;
        });
        if (statusValue) {
          // set that status value Id into the mutation
          const updateStatusMutation = `mutation {
              updateSpace(input: {
                id: "${spaceId}",
                statusValue:  {
                    statusValueId: "${statusValue.id}"
                  }
              }
              ) {
                memberIdsChanged
              }
            }`;
          //  and execute
          resolve(this.sendGraphql(updateStatusMutation));
        } else {
          reject(`The value [${newStatus}] is not a valid status to set.`);
        }
      })
      .catch(err => {
         reject(err);
      });
   });
  }

  /**
   * Return an array of the property display names and human-readable values.
   * Each item in the array has a `propertyName` with the human-readable name of the property,
   * and a `propertyValue` with the human-readable value, converted from the value's Id.
   * This returns a promise for consistency with the other calls.
   * @param {string} spaceId 
   * @returns {Promise<Object>} Promise containing an array of the properties.
   */
  getProperties(spaceId) {
    return new Promise((resolve, reject) => {
      // this graphql will get the property definitions and their current values
      const query = `query getSpace {
        space(id: "${spaceId}") {
          propertyValueIds {
            propertyId
            propertyValueId
          }
          templateInfo {
            properties {
              items {
                id
                displayName
                type
                ... on SpaceListProperty {
                  acceptableValues {
                    id
                    displayName
                  }
                }
              }
            }
          }
        }
      }
      `;
      this.sendGraphql(query)
      .then(result => {
        const properties = []; // to hold the result
        // iterate through the property definitions in the template info
        for (let i = 0, itemsLength = result.space.templateInfo.properties.items.length; i < itemsLength; i++) {
          // for each property definition, get the current value from the propertyValueIds array
          const property = result.space.propertyValueIds.find(function(oneProperty) {
            return oneProperty.propertyId === result.space.templateInfo.properties.items[i].id;
          });
          let propertyValue; // to hold the value
          if (result.space.templateInfo.properties.items[i].type === 'LIST') {
            // if it's a list type, get the human-readable value
            const acceptableValue = result.space.templateInfo.properties.items[i].acceptableValues.find(function(value) {
              return value.id === property.propertyValueId;
            });
            propertyValue = acceptableValue.displayName;
          } else {
            // if it's not a list type, the value is whatever is in the propertyValueId
            propertyValue = property.propertyValueId;
          }
          properties.push({
            propertyName: result.space.templateInfo.properties.items[i].displayName,
            propertyValue: propertyValue
          });
        }
        resolve(properties);
      })
      .catch(err => {
        reject(err);
      })
    });
  }

  /**
   * Set a property of a space created from a template.
   * @param {*} spaceId the Id of the space.
   * @param {*} propertyName The name of the property to set.
   * @param {*} propertyValue The value of the property to set. For a property of 
   * type TEXT, this function will set the property value to whatever is passed in.
   * For a property of type BOOLEAN, this function will attempt to convert the primitive
   * boolean 'true' to the string TRUE and the primitive boolean 'false' to the string FALSE.
   * @returns {Promise<Object>} Promise containing the server response, or a reject message.
   */
  setProperty(spaceId, propertyName, propertyValue) {
    return new Promise((resolve, reject) => {
      // get all the property definitions
      let query = `query getSpace {
        space(id: "${spaceId}") { 
          templateInfo {
          properties {
              items {
                id
                displayName
                type       
                ... on SpaceListProperty {
                  acceptableValues {
                    id
                    displayName
                  }
                }
              }
            }
          }
        }
      }`;
      this.sendGraphql(query)
      .then(result => {
        // find the property we want
        const propertyDef = result.space.templateInfo.properties.items.find(function(item) {
          return item.displayName === propertyName
        });
        if (typeof propertyDef === 'undefined') {
          reject(`Property [${propertyName}] not defined in this space.`);
          return;
        }
        // if BOOLEAN, check for a valid property and replace it with its string equivalent
        if (propertyDef.type === 'BOOLEAN') {
          if (typeof propertyValue === 'boolean') {
            propertyValue = propertyValue === true ? 'TRUE' : 'FALSE';
          } else {
            reject(`Property value [${propertyValue}] invalid for property of type BOOLEAN`);
            return;
          }
        // if LIST, find the matching acceptableValue and use that
        } else if (propertyDef.type === 'LIST') {
          // find the acceptableValue which matches our propertyValue
          const acceptableValue = propertyDef.acceptableValues.find( function(value) {
            return value.displayName === propertyValue;
          });
          if (acceptableValue) {
            propertyValue = acceptableValue.id;
          } else {
            reject(`Acceptable Value [${propertyValue}] not found for property [${propertyName}]`);
            return;
          }
        }
        // if we got here, the inputs passed our checks and were converted if necessary.
        // Run the Graphql.
        const mutation = `mutation {
          updateSpace(input: {
            id: "${spaceId}", 
            propertyValues: [
              {
                propertyId: "${propertyDef.id}", 
                propertyValueId: "${propertyValue}"
              }
            ]
          }) {
            memberIdsChanged
          }
        }`;
        resolve(this.sendGraphql(mutation));
      })
      .catch(err => {
        reject(err);
      });
    });
  }

}

/**
 * Sets the debug level. If 'debug' is used, request/response debug will be set.
 * @param {string} level Level for debug e.g. error, info, warn, verbose, debug
 */
module.exports.level = level => {
  logger.level = level
}

/**
 * A user interface helper for sendTargetedMessage(). 
 */
module.exports.UI = ui