Source: managers/comments.ts

/**
 * @fileoverview Manager for the Box Comments Resource
 */

// ------------------------------------------------------------------------------
// Requirements
// ------------------------------------------------------------------------------

import BoxClient from '../box-client';
import urlPath from '../util/url-path';

// -----------------------------------------------------------------------------
// Typedefs
// -----------------------------------------------------------------------------

// ------------------------------------------------------------------------------
// Private
// ------------------------------------------------------------------------------

const BASE_PATH = '/comments';

// ------------------------------------------------------------------------------
// Public
// ------------------------------------------------------------------------------

/**
 * Simple manager for interacting with all 'Comment' endpoints and actions.
 *
 * @constructor
 * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API
 * @returns {void}
 */
class Comments {
  client: BoxClient;

  constructor(client: BoxClient) {
    this.client = client;
  }

  /**
   * Requests a comment object with the given ID.
   *
   * API Endpoint: '/comments/:commentID'
   * Method: GET
   *
   * @param {string} commentID - Box ID of the comment being requested
   * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
   * @param {Function} [callback] - Passed the comment information if it was acquired successfully
   * @returns {Promise<Object>} A promise resolving to the comment object
   */
  get(commentID: string, options?: Record<string, any>, callback?: Function) {
    var params = {
      qs: options,
    };
    var apiPath = urlPath(BASE_PATH, commentID);
    return this.client.wrapWithDefaultHandler(this.client.get)(
      apiPath,
      params,
      callback
    );
  }

  /**
   * Posts a new comment on a file.
   *
   * API Endpoint: '/comments
   * Method: POST
   *
   * @param {string} fileID - Box file id of the file to comment on
   * @param {string} commentBody - text of the comment
   * @param {Function} [callback] - passed the new comment data if it was posted successfully
   * @returns {Promise<Object>} A promise resolving to the new comment object
   */
  create(fileID: string, commentBody: string, callback?: Function) {
    // @TODO(bemerick) 2013-10-29: Don't hardcode this 'item'. Abstract to all commentable types...
    var params = {
      body: {
        item: {
          type: 'file',
          id: fileID,
        },
        message: commentBody,
      },
    };
    return this.client.wrapWithDefaultHandler(this.client.post)(
      BASE_PATH,
      params,
      callback
    );
  }

  /**
   * Posts a new tagged comment on a file.
   *
   * API Endpoint: '/comments
   * Method: POST
   *
   * @param {string} fileID - Box file id of the file to comment on
   * @param {string} commentBody - text of the tagged comment
   * @param {Function} [callback] - passed the new tagged comment data if it was posted successfully
   * @returns {Promise<Object>} A promise resolving to the new comment object
   */
  createTaggedComment(
    fileID: string,
    commentBody: string,
    callback?: Function
  ) {
    var params = {
      body: {
        item: {
          type: 'file',
          id: fileID,
        },
        tagged_message: commentBody,
      },
    };
    return this.client.wrapWithDefaultHandler(this.client.post)(
      BASE_PATH,
      params,
      callback
    );
  }

  /**
   * Posts a new comment as a reply to another comment.
   *
   * API Endpoint: '/comments
   * Method: POST
   *
   * @param {string} commentID - Comment ID of the comment to reply to
   * @param {string} commentBody - text of the comment
   * @param {Function} [callback] - passed the new comment data if it was posted successfully
   * @returns {Promise<Object>} A promise resolving to the new comment object
   */
  reply(commentID: string, commentBody: string, callback?: Function) {
    var params = {
      body: {
        item: {
          type: 'comment',
          id: commentID,
        },
        message: commentBody,
      },
    };
    return this.client.wrapWithDefaultHandler(this.client.post)(
      BASE_PATH,
      params,
      callback
    );
  }

  /**
   * Posts a new tagged comment as a reply to another comment.
   *
   * API Endpoint: '/comments
   * Method: POST
   *
   * @param {string} commentID - Comment ID of the comment to reply to
   * @param {string} commentBody - text of the tagged comment
   * @param {Function} [callback] - passed the new tagged comment data if it was posted successfully
   * @returns {Promise<Object>} A promise resolving to the new comment object
   */
  createTaggedReply(
    commentID: string,
    commentBody: string,
    callback?: Function
  ) {
    var params = {
      body: {
        item: {
          type: 'comment',
          id: commentID,
        },
        tagged_message: commentBody,
      },
    };
    return this.client.wrapWithDefaultHandler(this.client.post)(
      BASE_PATH,
      params,
      callback
    );
  }

  /**
   * Update some information about a given comment.
   *
   * API Endpoint: '/comments/:commentID'
   * Method: PUT
   *
   * @param {string} commentID - Box ID of the comment being requested
   * @param {Object} updates - Fields to update on the comment
   * @param {Function} [callback] - Passed the updated comment information if it was acquired successfully
   * @returns {Promise<Object>} A promise resolving to the updated comment object
   */
  update(commentID: string, updates: Record<string, any>, callback?: Function) {
    var params = {
      body: updates,
    };

    var apiPath = urlPath(BASE_PATH, commentID);
    return this.client.wrapWithDefaultHandler(this.client.put)(
      apiPath,
      params,
      callback
    );
  }

  /**
   * Delete a given comment.
   *
   * API Endpoint: '/comments/:commentID'
   * Method: DELETE
   *
   * @param {string} commentID - Box ID of the comment being requested
   * @param {Function} [callback] - Empty response body passed if successful.
   * @returns {Promise<void>} A promise resolving to nothing
   */
  delete(commentID: string, callback?: Function) {
    var apiPath = urlPath(BASE_PATH, commentID);
    return this.client.wrapWithDefaultHandler(this.client.del)(
      apiPath,
      null,
      callback
    );
  }
}

/**
 * @module box-node-sdk/lib/managers/comments
 * @see {@Link Comments}
 */
export = Comments;