Source: index.js

  1. "use strict";
  3. // Core packages
  4. const url = require('url');
  6. // Npm packages
  7. const request = require('request');
  8. const jwt = require('atlassian-jwt');
  9. const queryString = require('query-string');
  11. // Custom packages
  12. var applicationProperties = require('./api/application-properties');
  13. var attachment = require('./api/attachment');
  14. var auditing = require('./api/auditing');
  15. var auth = require('./api/auth');
  16. var avatar = require('./api/avatar');
  17. var backlog = require('./api/backlog');
  18. var board = require('./api/board');
  19. var comment = require('./api/comment');
  20. var component = require('./api/component');
  21. var customFieldOption = require('./api/customFieldOption');
  22. var dashboard = require('./api/dashboard');
  23. const developmentInformation = require('./api/developmentInformation');
  24. var epic = require('./api/epic');
  25. var errorStrings = require('./lib/error');
  26. var field = require('./api/field');
  27. var filter = require('./api/filter');
  28. var group = require('./api/group');
  29. var groupUserPicker = require('./api/groupUserPicker');
  30. var groups = require('./api/groups');
  31. var issue = require('./api/issue');
  32. var issueLink = require('./api/issueLink');
  33. var issueLinkType = require('./api/issueLinkType');
  34. var issueType = require('./api/issueType');
  35. var jql = require('./api/jql');
  36. var labels = require('./api/labels');
  37. var licenseRole = require('./api/licenseRole');
  38. var licenseValidator = require('./api/licenseValidator');
  39. var myPermissions = require('./api/myPermissions');
  40. var myPreferences = require('./api/myPreferences');
  41. var myself = require('./api/myself');
  42. var oauth_util = require('./lib/oauth_util');
  43. var password = require('./api/password');
  44. var permissions = require('./api/permissions');
  45. var permissionScheme = require('./api/permission-scheme');
  46. var priority = require('./api/priority');
  47. var project = require('./api/project');
  48. var projectCategory = require('./api/projectCategory');
  49. var projectValidate = require('./api/projectValidate');
  50. var reindex = require('./api/reindex');
  51. var resolution = require('./api/resolution');
  52. var roles = require('./api/roles');
  53. var screens = require('./api/screens');
  54. var search = require('./api/search');
  55. var securityLevel = require('./api/securityLevel');
  56. var serverInfo = require('./api/serverInfo');
  57. var settings = require('./api/settings');
  58. var sprint = require('./api/sprint');
  59. var status = require('./api/status');
  60. var statusCategory = require('./api/statusCategory');
  61. var user = require('./api/user');
  62. var version = require('./api/version');
  63. var webhook = require('./api/webhook');
  64. var workflow = require('./api/workflow');
  65. var workflowScheme = require('./api/workflowScheme');
  66. var worklog = require('./api/worklog');
  68. /**
  69.  * @callback callback
  70.  * @param {any} err
  71.  * @param {any} data
  72.  * @returns {void}
  73.  */
  75. /**
  76.  * Represents a client for the Jira REST API
  77.  *
  78.  * @constructor JiraClient
  79.  * @property {AgileBoardClient} board
  80.  * @property {AgileSprintClient} sprint
  81.  *
  82.  * @property {ApplicationPropertiesClient} applicationProperties
  83.  * @property {AttachmentClient} attachment
  84.  * @property {AuditingClient} auditing
  85.  * @property {AuthClient} auth
  86.  * @property {AvatarClient} avatar
  87.  * @property {CommentClient} comment
  88.  * @property {ComponentClient} component
  89.  * @property {CustomFieldOptionClient} customFieldOption
  90.  * @property {DashboardClient} dashboard
  91.  * @property {DevelopmentInformationClient} developmentInformation
  92.  * @property {FieldClient} field
  93.  * @property {FilterClient} filter
  94.  * @property {GroupClient} group
  95.  * @property {GroupUserPickerClient} groupUserPicker
  96.  * @property {GroupsClient} groups
  97.  * @property {IssueClient} issue
  98.  * @property {IssueLinkClient} issueLink
  99.  * @property {IssueLinkTypeClient} issueLinkType
  100.  * @property {IssueTypeClient} issueType
  101.  * @property {JqlClient} jql
  102.  * @property {LabelsClient} labels
  103.  * @property {LicenseRoleClient} licenseRole
  104.  * @property {LicenseValidatorClient} licenseValidator
  105.  * @property {MyPermissionsClient} myPermissions
  106.  * @property {MyPreferencesClient} myPreferences
  107.  * @property {MyselfClient} myself
  108.  * @property {PasswordClient} password
  109.  * @property {PermissionsClient} permissions
  110.  * @property {PermissionSchemeClient} permissionScheme
  111.  * @property {PriorityClient} priority
  112.  * @property {ProjectCategoryClient} projectCategory
  113.  * @property {ProjectClient} project
  114.  * @property {ProjectValidateClient} projectValidate
  115.  * @property {ReindexClient} reindex
  116.  * @property {ResolutionClient} resolution
  117.  * @property {RoleClient} roles
  118.  * @property {ScreensClient} screens
  119.  * @property {SearchClient} search
  120.  * @property {SecurityLevelClient} securityLevel
  121.  * @property {ServerInfoClient} serverInfo
  122.  * @property {SettingsClient} settings
  123.  * @property {StatusCategoryClient} statusCategory
  124.  * @property {StatusClient} status
  125.  * @property {UserClient} user
  126.  * @property {VersionClient} version
  127.  * @property {WebhookClient} webhook
  128.  * @property {WorkflowClient} workflow
  129.  * @property {WorkflowSchemeClient} workflowScheme
  130.  * @property {WorklogClient} worklog
  131.  *
  132.  * @param config The information needed to access the Jira API
  133.  * @param {string} config.host The hostname of the Jira API.
  134.  * @param {number} [config.timeout] request timeout (milliseconds)
  135.  * @param {string} [config.protocol=https] The protocol used to accses the Jira API.
  136.  * @param {number} [config.port=443] The port number used to connect to Jira.
  137.  * @param {string} [config.path_prefix="/"] The prefix to use in front of the path, if Jira isn't at "/"
  138.  * @param {boolean} [config.strictSSL=true] It is recommended not to turn it off for no reason (https://github.com/request/request/issues/251).
  139.  * @param {number | string} [config.version=2] The version of the Jira API to which you will be connecting.  Currently, only
  140.  *     version 2 is supported.
  141.  * @param {Object} [config.basic_auth] The authentication information used tp connect to Jira. Must contain EITHER username and password
  142.  *     OR oauth information.  Oauth information will be used over username/password authentication.
  143.  * @param {Object} [config.basic_auth.base64] base64 that contains email:api_token.
  144.  * @param {string} [config.basic_auth.username] (DEPRECATED) The username of the user that will be authenticated. MUST be included
  145.  *     if using username and password authentication.
  146.  * @param {string} [config.basic_auth.password] (DEPRECATED) The password of the user that will be authenticated. MUST be included
  147.  *     if using username and password authentication.
  148.  * @param {string} [config.basic_auth.email] The email of the user that will be authenticated. MUST be included
  149.  *     if using email and api_token authentication.
  150.  * @param {string} [config.basic_auth.api_token] The api token of the user that will be authenticated. MUST be included
  151.  *     if using email and api_token authentication.
  152.  * @param {string} [config.oauth.consumer_key] The consumer key used in the Jira Application Link for oauth
  153.  *     authentication.  MUST be included if using OAuth.
  154.  * @param {string} [config.oauth.private_key] The private key used for OAuth security. MUST be included if using OAuth.
  155.  * @param {string} [config.oauth.token] The VERIFIED token used to connect to the Jira API.  MUST be included if using
  156.  *     OAuth.
  157.  * @param {string} [config.oauth.token_secret] The secret for the above token.  MUST be included if using Oauth.
  158.  * @param {Object} [config.jwt] The JWT configuration object that contains iss:secret
  159.  * @param {string} config.jwt.iss The Jira app key (can be found in the app descriptor). MUST be included
  160.  * @param {string} config.jwt.secret The JWT secret token. MUST be included
  161.  * @param {string} [config.jwt.expiry_time_seconds] The JWT token expiry time in seconds. OPTIONAL (default 180 seconds)
  162.  * @param {CookieJar} [config.cookie_jar] The CookieJar to use for every requests.
  163.  * @param {Promise} [config.promise] Any function (constructor) compatible with Promise (bluebird, Q,...).
  164.  *      Default - native Promise.
  165.  * @param {Request} [config.request] Any function (constructor) compatible with Request (request, supertest,...).
  166.  *      Default - require('request').
  167.  */
  169. var JiraClient = module.exports = function (config) {
  170.     if (!config.host) {
  171.         throw new Error(errorStrings.NO_HOST_ERROR);
  172.     }
  174.     this.host = config.host;
  175.     this.timeout = config.timeout;
  176.     this.protocol = config.protocol ? config.protocol : 'https';
  177.     this.path_prefix = config.path_prefix ? config.path_prefix : '/';
  178.     this.port = config.port;
  179.     this.apiVersion = 2;
  180.     this.strictSSL = config.hasOwnProperty('strictSSL') ? config.strictSSL : true;
  181.     this.agileApiVersion = '1.0';
  182.     this.authApiVersion = '1';
  183.     this.webhookApiVersion = '1.0';
  184.     this.promise = config.promise || Promise;
  185.     this.requestLib = config.request || request;
  186.     this.rejectUnauthorized = config.rejectUnauthorized;
  188.     if (config.oauth) {
  189.         if (!config.oauth.consumer_key) {
  190.             throw new Error(errorStrings.NO_CONSUMER_KEY_ERROR);
  191.         } else if (!config.oauth.private_key) {
  192.             throw new Error(errorStrings.NO_PRIVATE_KEY_ERROR);
  193.         } else if (!config.oauth.token) {
  194.             throw new Error(errorStrings.NO_OAUTH_TOKEN_ERROR);
  195.         } else if (!config.oauth.token_secret) {
  196.             throw new Error(errorStrings.NO_OAUTH_TOKEN_SECRET_ERROR);
  197.         }
  199.         this.oauthConfig = config.oauth;
  200.         this.oauthConfig.signature_method = 'RSA-SHA1';
  202.     } else if (config.basic_auth) {
  203.         if (config.basic_auth.base64) {
  204.             this.basic_auth = {
  205.                 base64: config.basic_auth.base64
  206.             }
  207.         } else if (config.basic_auth.api_token || config.basic_auth.email) {
  208.             if (!config.basic_auth.email) {
  209.                 throw new Error(errorStrings.NO_EMAIL_ERROR);
  210.             } else if (!config.basic_auth.api_token) {
  211.                 throw new Error(errorStrings.NO_APITOKEN_ERROR);
  212.             }
  214.             this.basic_auth = {
  215.                 user: config.basic_auth.email,
  216.                 pass: config.basic_auth.api_token
  217.             };
  218.         } else {
  219.             if (!config.basic_auth.username) {
  220.                 throw new Error(errorStrings.NO_USERNAME_ERROR);
  221.             } else if (!config.basic_auth.password) {
  222.                 throw new Error(errorStrings.NO_PASSWORD_ERROR);
  223.             }
  225.             this.basic_auth = {
  226.                 user: config.basic_auth.username,
  227.                 pass: config.basic_auth.password
  228.             };
  229.         }
  230.     } else if (config.jwt) {
  231.       if (config.jwt.secret && config.jwt.iss) {
  232.         this.jwt = {
  233.           iss: config.jwt.iss,
  234.           secret: config.jwt.secret,
  235.           expiry_time_seconds: config.jwt.expiry_time_seconds || 3 * 60
  236.         };
  237.       } else {
  238.         if (!config.jwt.secret) {
  239.           throw new Error(errorStrings.NO_JWT_SECRET_KEY_ERROR);
  240.         } else if (!config.jwt.iss) {
  241.           throw new Error(errorStrings.NO_JWT_ISS_KEY_ERROR);
  242.         }
  243.       }
  244.     }
  246.     if (config.cookie_jar) {
  247.         this.cookie_jar = config.cookie_jar;
  248.     }
  250.     this.applicationProperties = new applicationProperties(this);
  251.     this.attachment = new attachment(this);
  252.     this.auditing = new auditing(this);
  253.     this.auth = new auth(this);
  254.     this.avatar = new avatar(this);
  255.     this.backlog = new backlog(this);
  256.     this.board = new board(this);
  257.     this.comment = new comment(this);
  258.     this.component = new component(this);
  259.     this.customFieldOption = new customFieldOption(this);
  260.     this.dashboard = new dashboard(this);
  261.     this.developmentInformation = new developmentInformation(this);
  262.     this.epic = new epic(this);
  263.     this.field = new field(this);
  264.     this.filter = new filter(this);
  265.     this.group = new group(this);
  266.     this.groupUserPicker = new groupUserPicker(this);
  267.     this.groups = new groups(this);
  268.     this.issue = new issue(this);
  269.     this.issueLink = new issueLink(this);
  270.     this.issueLinkType = new issueLinkType(this);
  271.     this.issueType = new issueType(this);
  272.     this.jql = new jql(this);
  273.     this.labels = new labels(this);
  274.     this.licenseRole = new licenseRole(this);
  275.     this.licenseValidator = new licenseValidator(this);
  276.     this.myPermissions = new myPermissions(this);
  277.     this.myPreferences = new myPreferences(this);
  278.     this.myself = new myself(this);
  279.     this.password = new password(this);
  280.     this.permissions = new permissions(this);
  281.     this.permissionScheme = new permissionScheme(this);
  282.     this.priority = new priority(this);
  283.     this.project = new project(this);
  284.     this.projectCategory = new projectCategory(this);
  285.     this.projectValidate = new projectValidate(this);
  286.     this.reindex = new reindex(this);
  287.     this.resolution = new resolution(this);
  288.     this.roles = new roles(this);
  289.     this.screens = new screens(this);
  290.     this.search = new search(this);
  291.     this.securityLevel = new securityLevel(this);
  292.     this.serverInfo = new serverInfo(this);
  293.     this.settings = new settings(this);
  294.     this.sprint = new sprint(this);
  295.     this.status = new status(this);
  296.     this.statusCategory = new statusCategory(this);
  297.     this.user = new user(this);
  298.     this.version = new version(this);
  299.     this.webhook = new webhook(this);
  300.     this.workflow = new workflow(this);
  301.     this.workflowScheme = new workflowScheme(this);
  302.     this.worklog = new worklog(this);
  303. };
  305. (function () {
  307.     /**
  308.      * Simple utility to build a REST endpoint URL for the Jira API.
  309.      *
  310.      * @method buildURL
  311.      * @memberOf JiraClient#
  312.      * @param path The path of the URL without concern for the root of the REST API.
  313.      * @param {string | number} [forcedVersion] Use this param to force a particular version
  314.      * @returns {string} The constructed URL.
  315.      */
  316.     this.buildURL = function (path, forcedVersion) {
  317.         var apiBasePath = this.path_prefix + 'rest/api/';
  318.         var version = forcedVersion || this.apiVersion;
  319.         var requestUrl = url.format({
  320.             protocol: this.protocol,
  321.             hostname: this.host,
  322.             port: this.port,
  323.             pathname: apiBasePath + version + path
  324.         });
  326.         return decodeURIComponent(requestUrl);
  327.     };
  329.      /**
  330.      * Simple utility to build a REST endpoint URL for the Jira API without prefixes.
  331.      *
  332.      * @method buildAbstractURL
  333.      * @memberOf JiraClient#
  334.      * @param path The path of the URL without concern for the root of the REST API.
  335.      * @returns {string} The constructed URL.
  336.      */
  337.     this.buildAbstractURL = function(path) {
  338.       const apiBasePath = this.path_prefix + 'rest/';
  339.       const requestUrl = url.format({
  340.           protocol: this.protocol,
  341.           hostname: this.host,
  342.           port: this.port,
  343.           pathname: apiBasePath + path
  344.       });
  346.       return decodeURIComponent(requestUrl);
  347.     }
  349.     /**
  350.      * Simple utility to build a REST endpoint URL for the Jira Agile API.
  351.      *
  352.      * @method buildAgileURL
  353.      * @memberOf JiraClient#
  354.      * @param path The path of the URL without concern for the root of the REST API.
  355.      * @param {string | number} [forcedVersion] Use this param to force a particular version
  356.      * @returns {string} The constructed URL.
  357.      */
  358.     this.buildAgileURL = function (path, forcedVersion) {
  359.         var apiBasePath = this.path_prefix + 'rest/agile/';
  360.         var version = forcedVersion || this.agileApiVersion;
  361.         var requestUrl = url.format({
  362.             protocol: this.protocol,
  363.             hostname: this.host,
  364.             port: this.port,
  365.             pathname: apiBasePath + version + path
  366.         });
  368.         return decodeURIComponent(requestUrl);
  369.     };
  371.     /**
  372.      * Simple utility to build a REST endpoint URL for the Jira Auth API.
  373.      *
  374.      * @method buildAuthURL
  375.      * @memberOf JiraClient#
  376.      * @param path The path of the URL without concern for the root of the REST API.
  377.      * @param {string | number} [forcedVersion] Use this param to force a particular version
  378.      * @returns {string} The constructed URL.
  379.      */
  380.     this.buildAuthURL = function (path, forcedVersion) {
  381.         var apiBasePath = this.path_prefix + 'rest/auth/';
  382.         var version = forcedVersion || this.authApiVersion;
  383.         var requestUrl = url.format({
  384.             protocol: this.protocol,
  385.             hostname: this.host,
  386.             port: this.port,
  387.             pathname: apiBasePath + version + path
  388.         });
  390.         return decodeURIComponent(requestUrl);
  391.     };
  393.     /**
  394.      * Simple utility to build a REST endpoint URL for the Jira webhook API.
  395.      *
  396.      * @method buildWebhookURL
  397.      * @memberOf JiraClient#
  398.      * @param path The path of the URL without concern for the root of the REST API.
  399.      * @param {string | number} [forcedVersion] Use this param to force a particular version
  400.      * @returns {string} The constructed URL.
  401.      */
  402.     this.buildWebhookURL = function (path, forcedVersion) {
  403.         var apiBasePath = this.path_prefix + 'rest/webhooks/';
  404.         var version = forcedVersion || this.webhookApiVersion;
  405.         var requestUrl = url.format({
  406.             protocol: this.protocol,
  407.             hostname: this.host,
  408.             port: this.port,
  409.             pathname: apiBasePath + version + path
  410.         });
  412.         return decodeURIComponent(requestUrl);
  413.     };
  415.     /**
  416.      * Make a request to the Jira API and call back with it's response.
  417.      *
  418.      * @method makeRequest
  419.      * @memberOf JiraClient#
  420.      * @param options The request options.
  421.      * @param {callback} [callback] Called with the APIs response.
  422.      * @param {string} [successString] If supplied, this is reported instead of the response body.
  423.      * @return {Promise} Resolved with APIs response or rejected with error
  424.      */
  425.     this.makeRequest = function (options, callback, successString) {
  426.         let requestLib = this.requestLib;
  427.         options.rejectUnauthorized = this.rejectUnauthorized;
  428.         options.strictSSL = this.strictSSL;
  429.         options.timeout = this.timeout;
  431.         if (this.oauthConfig) {
  432.             options.oauth = this.oauthConfig;
  433.         } else if (this.basic_auth) {
  434.             if (this.basic_auth.base64) {
  435.                 if (!options.headers) {
  436.                     options.headers = {}
  437.                 }
  438.                 options.headers['Authorization'] = 'Basic ' + this.basic_auth.base64
  439.             } else {
  440.                 options.auth = this.basic_auth;
  441.             }
  442.         } else if (this.jwt) {
  443.             const pathname = new URL(options.uri).pathname;
  444.             const nowInSeconds = Math.floor(Date.now() / 1000);
  445.             const queryParam = queryString.parse(queryString.stringify(options.qs));
  446.             const jwtToken = jwt.encode({
  447.               iss: this.jwt.iss,
  448.               iat: nowInSeconds,
  449.               exp: nowInSeconds + this.jwt.expiry_time_seconds,
  450.               qsh: jwt.createQueryStringHash({
  451.                 method: options.method,
  452.                 pathname,
  453.                 query: queryParam || {}
  454.               })
  455.             }, this.jwt.secret);
  457.             if (!options.headers) {
  458.               options.headers = {};
  459.             }
  460.             options.headers['Authorization'] = `JWT ${jwtToken}`;
  461.         }
  463.         if (this.cookie_jar) {
  464.             options.jar = this.cookie_jar;
  465.         }
  467.         if (callback) {
  468.             requestLib(options, function (err, response, body) {
  469.                 if (
  470.                     err ||
  471.                     response.statusCode < 200 ||
  472.                     response.statusCode > 399
  473.                 ) {
  474.                     return callback(err ? err : body, null, response);
  475.                 }
  477.                 if (typeof body === 'string') {
  478.                     try {
  479.                         body = JSON.parse(body);
  480.                     } catch (jsonErr) {
  481.                         return callback(jsonErr, null, response);
  482.                     }
  483.                 }
  485.                 return callback(null, successString ? successString : body, response);
  486.             });
  487.         } else if (this.promise) {
  488.             return new this.promise(function (resolve, reject) {
  489.                 var req = requestLib(options);
  490.                 var requestObj = null;
  492.                 req.on('request', function (request) {
  493.                     requestObj = request;
  494.                 });
  496.                 req.on('response', function (response) {
  497.                     // Saving error
  498.                     var error = response.statusCode < 200 || response.statusCode > 399;
  500.                     // Collecting data
  501.                     var body = [];
  502.                     var push = body.push.bind(body);
  503.                     response.on('data', push);
  505.                     // Data collected
  506.                     response.on('end', function () {
  507.                         var result = body.join('');
  509.                         // Parsing JSON
  510.                         if (result[0] === '[' || result[0] === '{') {
  511.                             try {
  512.                                 result = JSON.parse(result);
  513.                             } catch (e) {
  514.                                 // nothing to do
  515.                             }
  516.                         }
  518.                         if (error) {
  519.                             response.body = result;
  520.                             if (options.debug) {
  521.                                 reject({
  522.                                     result: JSON.stringify(response),
  523.                                     debug: {
  524.                                         options: options,
  525.                                         request: {
  526.                                             headers: requestObj._headers,
  527.                                         },
  528.                                         response: {
  529.                                             headers: response.headers,
  530.                                         },
  531.                                     }
  532.                                 });
  533.                             } else {
  534.                                 reject(JSON.stringify(response));
  535.                             }
  536.                             return;
  537.                         }
  539.                         if (options.debug) {
  540.                             resolve({
  541.                                 result,
  542.                                 debug: {
  543.                                     options: options,
  544.                                     request: {
  545.                                         headers: requestObj._headers,
  546.                                     },
  547.                                     response: {
  548.                                         headers: response.headers,
  549.                                     },
  550.                                 }
  551.                             });
  552.                         } else {
  553.                             resolve(result);
  554.                         }
  555.                     });
  556.                 });
  558.                 req.on('error', reject);
  559.             });
  560.         }
  561.     };
  562. }).call(JiraClient.prototype);
  564. JiraClient.oauth_util = require('./lib/oauth_util');
  566. exports.oauth_util = oauth_util;