Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

JSDoc, Formatting, and Spelling Fixes #183

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

JSDoc, Formatting, and Spelling Fixes #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 73 additions & 85 deletions src/jira.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ export default class JiraApi {
this.base = options.base || '';
this.intermediatePath = options.intermediatePath;
this.strictSSL = options.hasOwnProperty('strictSSL') ? options.strictSSL : true;
// This is so we can fake during unit tests
// This is so we can fake during unit tests
this.request = options.request || request;
this.webhookVersion = options.webHookVersion || '1.0';
this.greenhopperVersion = options.greenhopperVersion || '1.0';
Expand Down Expand Up @@ -55,8 +55,7 @@ export default class JiraApi {
}

/**
* @typedef JiraApiOptions
* @type {object}
* @typedef {object} JiraApiOptions
* @property {string} [protocol=http] - What protocol to use to connect to
* jira? Ex: http|https
* @property {string} host - What host is this tool connecting to for the jira
Expand All @@ -82,31 +81,51 @@ export default class JiraApi {
* that if the underlying TCP connection cannot be established, the OS-wide TCP connection timeout
* will overrule the timeout option ([the default in Linux can be anywhere from 20-120 *
* seconds](http://www.sekuda.com/overriding_the_default_linux_kernel_20_second_tcp_socket_connect_timeout)).
* @property {string} [webhookVersion=1.0] - What webhook version does this api wrapper need to
* @property {string} [webHookVersion=1.0] - What webhook version does this api wrapper need to
* hit?
* @property {string} [greenhopperVersion=1.0] - What webhook version does this api wrapper need
* to hit?
* @property {OAuth} - Specify an oauth object for this tool to authenticate all requests using
* OAuth.
* @property {OAuth} oauth - Specify an oauth object for this tool to authenticate all requests
* using OAuth.
* @property {string} bearer - Specify an Authorization Bearer to be used instead of user/pass
*/

/**
* @typedef OAuth
* @type {object}
* @typedef {object} OAuth
* @property {string} consumer_key - The consumer entered in Jira Preferences.
* @property {string} consumer_secret - The private RSA file.
* @property {string} access_token - The generated access token.
* @property {string} access_token_secret - The generated access toke secret.
* @property {string} signature_method [signature_method=RSA-SHA1] - OAuth signurate methode
* @property {string} signature_method [signature_method=RSA-SHA1] - OAuth signature method
* Possible values RSA-SHA1, HMAC-SHA1, PLAINTEXT. Jira Cloud supports only RSA-SHA1.
*/

/**
* @typedef {object} UriOptions
* @property {string} pathname - The url after the specific functions path
* @property {object} [query] - An object of all query parameters
* @property {string} [intermediatePath] - Overwrites with specified path
*/

/**
* @typedef {object} WebhookUriOptions
* @property {string} pathname - The url after the specific functions path
* @property {string} [intermediatePath] - Overwrites with specified path
*/

/**
* @typedef {object} makeRequestHeaderOptions
* @property {string} [method] - HTTP Request Method. ie GET, POST, PUT, DELETE
* @property {boolean} [followAllRedirects]
*/

/**
* @name makeRequestHeader
* @function
* Creates a requestOptions object based on the default template for one
* @param {string} uri
* @param {object} [options] - an object containing fields and formatting how the
* @param {makeRequestHeaderOptions} [options] - an object containing fields to
* add to the header request object
*/
makeRequestHeader(uri, options = {}) {
return {
Expand All @@ -118,120 +137,92 @@ export default class JiraApi {
};
}

/**
* @typedef makeRequestHeaderOptions
* @type {object}
* @property {string} [method] - HTTP Request Method. ie GET, POST, PUT, DELETE
*/

/**
* @name makeUri
* @function
* Creates a URI object for a given pathname
* @param {object} [options] - an object containing path information
* @param {UriOptions} object - an object containing path information
*/
makeUri({ pathname, query, intermediatePath }) {
const intermediateToUse = this.intermediatePath || intermediatePath;
makeUri(object) {
const intermediateToUse = this.intermediatePath || object.intermediatePath;
const tempPath = intermediateToUse || `/rest/api/${this.apiVersion}`;
const uri = url.format({
protocol: this.protocol,
hostname: this.host,
port: this.port,
pathname: `${this.base}${tempPath}${pathname}`,
query,
pathname: `${this.base}${tempPath}${object.pathname}`,
query: object.query,
});
return decodeURIComponent(uri);
}

/**
* @typedef makeUriOptions
* @type {object}
* @property {string} pathname - The url after the /rest/api/version
* @property {object} query - a query object
* @property {string} intermediatePath - If specified will overwrite the /rest/api/version section
*/

/**
* @name makeWebhookUri
* @function
* Creates a URI object for a given pathName
* @param {object} [options] - An options object specifying uri information
* @param {WebhookUriOptions} object - an object containing
*/
makeWebhookUri({ pathname, intermediatePath }) {
const intermediateToUse = this.intermediatePath || intermediatePath;
makeWebhookUri(object) {
const intermediateToUse = this.intermediatePath || object.intermediatePath;
const tempPath = intermediateToUse || `/rest/webhooks/${this.webhookVersion}`;
const uri = url.format({
protocol: this.protocol,
hostname: this.host,
port: this.port,
pathname: `${this.base}${tempPath}${pathname}`,
pathname: `${this.base}${tempPath}${object.pathname}`,
});
return decodeURIComponent(uri);
}

/**
* @typedef makeWebhookUriOptions
* @type {object}
* @property {string} pathname - The url after the /rest/webhooks
* @property {string} intermediatePath - If specified will overwrite the /rest/webhooks section
*/

/**
* @name makeSprintQueryUri
* @function
* Creates a URI object for a given pathName
* @param {object} [options] - The url after the /rest/
* @param {UriOptions} object - an object containing path information
*/
makeSprintQueryUri({ pathname, query, intermediatePath }) {
const intermediateToUse = this.intermediatePath || intermediatePath;
makeSprintQueryUri(object) {
const intermediateToUse = this.intermediatePath || object.intermediatePath;
const tempPath = intermediateToUse || `/rest/greenhopper/${this.greenhopperVersion}`;
const uri = url.format({
protocol: this.protocol,
hostname: this.host,
port: this.port,
pathname: `${this.base}${tempPath}${pathname}`,
query,
pathname: `${this.base}${tempPath}${object.pathname}`,
query: object.query,
});
return decodeURIComponent(uri);
}

/**
* @typedef makeSprintQueryUriOptions
* @type {object}
* @property {string} pathname - The url after the /rest/api/version
* @property {object} query - a query object
* @property {string} intermediatePath - will overwrite the /rest/greenhopper/version section
*/

/**
* @typedef makeDevStatusUri
* @name makeDevStatusUri
* @function
* Creates a URI object for a given pathname
* @arg {pathname, query, intermediatePath} obj1
* @param {string} pathname obj1.pathname - The url after the /rest/api/version
* @param {object} query obj1.query - a query object
* @param {string} intermediatePath obj1.intermediatePath - If specified will overwrite the
* /rest/dev-status/latest/issue/detail section
*/
makeDevStatusUri({ pathname, query, intermediatePath }) {
const intermediateToUse = this.intermediatePath || intermediatePath;
* @param {UriOptions} object
*/
makeDevStatusUri(object) {
const intermediateToUse = this.intermediatePath || object.intermediatePath;
const tempPath = intermediateToUse || '/rest/dev-status/latest/issue';
const uri = url.format({
protocol: this.protocol,
hostname: this.host,
port: this.port,
pathname: `${this.base}${tempPath}${pathname}`,
query,
pathname: `${this.base}${tempPath}${object.pathname}`,
query: object.query,
});
return decodeURIComponent(uri);
}

/** @typedef {object} doRequest
* @property {object} views
*/

/**
* @name doRequest
* @function
* Does a request based on the requestOptions object
* @param {object} requestOptions - fields on this object get posted as a request header for
* requests to jira
* @returns {doRequest}
*/
async doRequest(requestOptions) {
const options = {
Expand Down Expand Up @@ -304,7 +295,7 @@ export default class JiraApi {
})));
}

/**
/**
* @name createProject
* @function
* Create a new Project
Expand Down Expand Up @@ -332,10 +323,8 @@ export default class JiraApi {

if (typeof projectName === 'undefined' || projectName === null) return response.views;

const rapidViewResult = response.views
.find(x => x.name.toLowerCase() === projectName.toLowerCase());

return rapidViewResult;
return response.views
.find(x => x.name.toLowerCase() === projectName.toLowerCase());
}

/** Get the most recent sprint for a given rapidViewId
Expand Down Expand Up @@ -471,7 +460,7 @@ export default class JiraApi {
* [Jira Doc](https://docs.atlassian.com/jira/REST/latest/#d2e510)
* @name updateVersion
* @function
* @param {string} version - an new object of the version to update
* @param {object} version - an new object of the version to update
*/
updateVersion(version) {
return this.doRequest(this.makeRequestHeader(this.makeUri({
Expand Down Expand Up @@ -514,8 +503,8 @@ export default class JiraApi {
* @function
* @param {string} searchString - jira query string in JQL
* @param {object} optional - object containing any of the following properties
* @param {integer} [optional.startAt=0]: optional starting index number
* @param {integer} [optional.maxResults=50]: optional ending index number
* @param {number} [optional.startAt=0]: optional starting index number
* @param {number} [optional.maxResults=50]: optional ending index number
* @param {array} [optional.fields]: optional array of string names of desired fields
*/
searchJira(searchString, optional = {}) {
Expand Down Expand Up @@ -553,27 +542,26 @@ export default class JiraApi {
* @function
* @param {SearchUserOptions} options
*/
searchUsers({ username, startAt, maxResults, includeActive, includeInactive }) {
searchUsers(options) {
return this.doRequest(this.makeRequestHeader(this.makeUri({
pathname: '/user/search',
query: {
username,
startAt: startAt || 0,
maxResults: maxResults || 50,
includeActive: includeActive || true,
includeInactive: includeInactive || false,
username: options.username,
startAt: options.startAt || 0,
maxResults: options.maxResults || 50,
includeActive: options.includeActive || true,
includeInactive: options.includeInactive || false,
},
}), {
followAllRedirects: true,
}));
}

/**
* @typedef SearchUserOptions
* @type {object}
* @typedef {object} SearchUserOptions
* @property {string} username - A query string used to search username, name or e-mail address
* @property {integer} [startAt=0] - The index of the first user to return (0-based)
* @property {integer} [maxResults=50] - The maximum number of users to return
* @property {number} [startAt=0] - The index of the first user to return (0-based)
* @property {number} [maxResults=50] - The maximum number of users to return
* @property {boolean} [includeActive=true] - If true, then active users are included
* in the results
* @property {boolean} [includeInactive=false] - If true, then inactive users
Expand All @@ -584,8 +572,8 @@ export default class JiraApi {
* @name getUsersInGroup
* @function
* @param {string} groupname - A query string used to search users in group
* @param {integer} [startAt=0] - The index of the first user to return (0-based)
* @param {integer} [maxResults=50] - The maximum number of users to return (defaults to 50).
* @param {number} [startAt=0] - The index of the first user to return (0-based)
* @param {number} [maxResults=50] - The maximum number of users to return (defaults to 50).
*/
getUsersInGroup(groupname, startAt = 0, maxResults = 50) {
return this.doRequest(
Expand Down Expand Up @@ -748,7 +736,7 @@ export default class JiraApi {
})));
}

/** Add an option for a select list issue field.
/** Add an option for a select list issue field.
* [Jira Doc](http://docs.atlassian.com/jira/REST/latest/#api/2/field/{fieldKey}/option-createOption)
* @name createFieldOption
* @function
Expand Down
Loading