@twyr/announce

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>git_host_utilities/github.js - Announce CLI - API Reference</title> <meta name="description" content="Announce CLI - API Reference" /> <meta name="keywords" content="automation announce changelog cli console git github gitlab npm package publish release release-automation release-helper release-workflow semantic-release semantic-version semver semver-release terminal twyr version" /> <meta name="keyword" content="automation announce changelog cli console git github gitlab npm package publish release release-automation release-helper release-workflow semantic-release semantic-version semver semver-release terminal twyr version" /> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav class="wrap"> <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2> <h2><a href="https://github.com/twyr/announce" target="_blank" class="menu-item" id="github_link">GitHub</a></h2> <h3>Classes</h3> <ul> <li><a href="GitHubWrapper.html">GitHubWrapper</a> <ul class='methods'> <li data-type='method'><a href="GitHubWrapper.html#_fetchData">_fetchData</a></li> <li data-type='method'><a href="GitHubWrapper.html#createRelease">createRelease</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchCommitAuthorInformation">fetchCommitAuthorInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchCommitInformation">fetchCommitInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#fetchReleaseInformation">fetchReleaseInformation</a></li> <li data-type='method'><a href="GitHubWrapper.html#getCommitLink">getCommitLink</a></li> </ul> </li> <li><a href="GitLabWrapper.html">GitLabWrapper</a> <ul class='methods'> <li data-type='method'><a href="GitLabWrapper.html#createRelease">createRelease</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchCommitAuthorInformation">fetchCommitAuthorInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchCommitInformation">fetchCommitInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#fetchReleaseInformation">fetchReleaseInformation</a></li> <li data-type='method'><a href="GitLabWrapper.html#getCommitLink">getCommitLink</a></li> </ul> </li> <li><a href="PrepareCommandClass.html">PrepareCommandClass</a> <ul class='methods'> <li data-type='method'><a href="PrepareCommandClass.html#_bumpVersion">_bumpVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_computeNextVersion">_computeNextVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_getCurrentVersion">_getCurrentVersion</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_getTargetFileList">_getTargetFileList</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="PrepareCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="PrepareCommandClass.html#execute">execute</a></li> </ul> </li> <li><a href="PublishCommandClass.html">PublishCommandClass</a> <ul class='methods'> <li data-type='method'><a href="PublishCommandClass.html#_getUpstreamRepositoryInfo">_getUpstreamRepositoryInfo</a></li> <li data-type='method'><a href="PublishCommandClass.html#_initializeGit">_initializeGit</a></li> <li data-type='method'><a href="PublishCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="PublishCommandClass.html#_publishToNpm">_publishToNpm</a></li> <li data-type='method'><a href="PublishCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="PublishCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="PublishCommandClass.html#execute">execute</a></li> </ul> </li> <li><a href="ReleaseCommandClass.html">ReleaseCommandClass</a> <ul class='methods'> <li data-type='method'><a href="ReleaseCommandClass.html#_generateChangelog">_generateChangelog</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_generateRelease">_generateRelease</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_initializeGit">_initializeGit</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_mergeOptions">_mergeOptions</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_pushUpstream">_pushUpstream</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_restoreCode">_restoreCode</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_setupLogger">_setupLogger</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_setupTasks">_setupTasks</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_stashOrCommit">_stashOrCommit</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_summarize">_summarize</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#_tagCode">_tagCode</a></li> <li data-type='method'><a href="ReleaseCommandClass.html#execute">execute</a></li> </ul> </li> </ul> </nav> <div id="main"> <h1 class="page-title">git_host_utilities/github.js</h1> <section> <article> <pre class="prettyprint source linenums"><code>'use strict'; /** * Module dependencies, required for ALL Twy'r modules * @ignore */ /** * Module dependencies, required for this module * @ignore */ /** * @class GitHubWrapper * @classdesc The command class that wraps GitHub related functionality for Release and Publish. * * @param {string} token - The GitHub Personal Access Token to be used to access the repositories * * @description * The wrapper class that provides an API interface for all GitHub related operations. * */ class GitHubWrapper { // #region Constructor constructor(token) { this.#client = require('octonode')?.client?.(token); } // #endregion // #region Public API /** * @async * @function * @instance * @memberof GitHubWrapper * @name fetchCommitInformation * * @param {object} repository - the GitHub repository to query for the release * @param {string} commitLog - the git commit object for which commit information needs to be fetched * * @return {object} The required information about the commit from GitHub. * * @summary Given a GitHub repository, returns information about the commit pointed to by the commitLog object. * */ async fetchCommitInformation(repository, commitLog) { const ghRepo = this.#client?.repo?.(`${repository?.user}/${repository?.project}`); const commit = await ghRepo?.commitAsync?.(commitLog?.hash); return commit?.[0]; } /** * @async * @function * @instance * @memberof GitHubWrapper * @name fetchCommitAuthorInformation * * @param {object} repository - the GitHub repository to query for the release * @param {string} commitLog - the git commit object for which the author information needs to be fetched * * @return {object} The required information about the commit author from GitHub. * * @summary Given a GitHub repository, returns information about the commit author pointed to by the commitLog object. * */ async fetchCommitAuthorInformation(repository, commitLog) { const ghRepo = this.#client?.repo?.(`${repository?.user}/${repository?.project}`); let commit = await ghRepo?.commitAsync?.(commitLog?.hash); commit = commit?.[0]; return { 'name': commit?.commit?.author?.name, 'email': commit?.commit?.author?.email, 'profile': commit?.author?.html_url, 'avatar': commit?.author?.avatar_url }; } /** * @async * @function * @instance * @memberof GitHubWrapper * @name fetchReleaseInformation * * @param {object} repository - the GitHub repository to query for the release * @param {string} releaseName - the name of the release * * @return {object} The required information about the release from GitHub. * * @summary Given a GitHub repository, returns information about the release - either the latest, or the one matching the specified release name. * */ async fetchReleaseInformation(repository, releaseName) { const ghRepo = this.#client?.repo?.(`${repository?.user}/${repository?.project}`); let allReleases = await ghRepo?.releasesAsync?.(); allReleases = allReleases?.[0]; if(releaseName?.trim?.()?.length) { const releaseInfo = allReleases?.filter?.((release) => { return (release?.name === releaseName); })?.shift?.(); return { 'name': releaseInfo?.name, 'prerelease': releaseInfo?.prerelease, 'published': releaseInfo?.published_at, 'tarball_url': releaseInfo?.tarball_url, 'tag': releaseInfo?.tag_name }; } const releaseInfo = allReleases?.map?.((release) => { return { 'name': release?.name, 'prerelease': release?.prerelease, 'published': release?.published_at, 'tarball_url': release?.tarball_url, 'tag': release?.tag_name }; }) ?.sort?.((left, right) => { return (new Date(right?.published))?.valueOf() - (new Date(left?.published))?.valueOf(); }) ?.shift?.(); return releaseInfo; } /** * @async * @function * @instance * @memberof GitHubWrapper * @name createRelease * * @param {object} releaseData - The data required for creating a release on GitHub * * @return {null} Nothing. * * @summary Given the required data, creates a release on Github. * */ async createRelease(releaseData) { return new Promise((resolve, reject) => { const repository = releaseData?.['REPO']; this.#client?.post?.(`https://api.${repository.domain}/repos/${repository.user}/${repository.project}/releases`, { 'accept': 'application/vnd.github.v3+json', 'tag_name': releaseData?.['RELEASE_TAG'], 'name': releaseData?.['RELEASE_NAME'], 'body': releaseData?.['RELEASE_NOTES'], 'prerelease': !!(releaseData?.['RELEASE_TYPE'] === 'pre-release') }, (err, status) => { if(err) { reject?.(err); return; } if(status >= 300) { reject?.(status); return; } resolve?.(status); }); }); } /** * @function * @instance * @memberof GitHubWrapper * @name getCommitLink * * @param {object} repository - the GitHub repository to query for the release * @param {object} commitLog - the commit information * * @return {object} The URL to access the commit on GitHub. * * @summary Given a GitHub repository, and a commit, returns the URL to access the commit directly. * */ getCommitLink(repository, commitLog) { return `https://${repository?.domain}/${repository?.user}/${repository?.project}/commit/${commitLog?.hash})`; } // #endregion // #region Private Methods /** * @async * @function * @instance * @memberof GitHubWrapper * @name _fetchData * * @param {string} url - the url giving the information we seek * * @return {object} Hopefully, the required information from GitHub. * * @summary Given a GitHub REST API endpoint, call it and give back the information returned. * */ async _fetchData(url) { return new Promise((resolve, reject) => { this.#client?.get?.(url, {}, (err, status, body) => { if(err) { reject?.(err); return; } if(status >= 300) { reject?.(status); return; } resolve?.(body); }); }); } // #endregion // #region Private Fields #client = null; // #endregion } exports.GitHostWrapper = GitHubWrapper; </code></pre> </article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script> prettyPrint(); </script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>