diff --git a/README.md b/README.md
index 17fc288..2975706 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,11 @@ If you detect a problem or want to suggest an improvement open an [issue](https:
 If you need support or would like to have Mediumroast run the Caffeine Machine Intelligence service on your repository please contact the Mediumroast team via [Discord](https://discord.gg/ebM4Cf8meK) or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io).
 
 ### Release notes
+#### Version 0.8.06.02
+- Resolved documentation errata for Demo.md
+- Updated text for basic reporting workflow and action to show both companies and study reports are running.
+- Removed debugging logging statements from basic reporting action.
+
 #### Version 0.8.06.01
 - The latest version of the SDK and CLI package now includes an initial implementation of Studies with the Foundation study. 
 - The SDK and CLI may run on for Windows OS, but it has not been tested. If you choose to install and run into problems please open an issue and we will work with you to resolve the matter.
diff --git a/cli/Demo.md b/cli/Demo.md
index 2b73d3d..167ae7b 100644
--- a/cli/Demo.md
+++ b/cli/Demo.md
@@ -11,18 +11,18 @@ With this configuration file by updating the `org` value to `MegaRoast` you can
 [DEFAULT]
 company_dns=https://company-dns.mediumroast.io
 company_logos=https://icon-server.mediumroast.io/allicons.json?url=
-echarts=https://echart-server.mediumroast.io:11000
+echarts=https://chart-server.mediumroast.io:11000
 nominatim=https://nominatim.openstreetmap.org/search?addressdetails=1&q=
 working_directory=working
 report_output_dir=Documents
-theme=coffee
+theme=latte
 
 [GitHub]
 clientId=Iv1.f5c0a4eb1f0606f8
 appId=650476
-authType=deviceFlow
-org=<ORGANIZATION>
 token=<TOKEN>
+authType=deviceFlow
+org=MegaRoast
 ```
 
 ### Limitations
diff --git a/cli/actions/actions/basic-reporting/action.yml b/cli/actions/actions/basic-reporting/action.yml
index 01ee5b5..0efc939 100644
--- a/cli/actions/actions/basic-reporting/action.yml
+++ b/cli/actions/actions/basic-reporting/action.yml
@@ -1,5 +1,5 @@
 name: 'Basic Reporting'
-description: 'Generates basic reports for companies plus wrapping README.md files in the repository'
+description: 'Generates basic reports for companies and studies plus wrapping README.md files in the repository'
 inputs:
   github-token:
     description: 'GitHub token'
diff --git a/cli/actions/actions/basic-reporting/study.js b/cli/actions/actions/basic-reporting/study.js
index 4f5d207..e5f1721 100644
--- a/cli/actions/actions/basic-reporting/study.js
+++ b/cli/actions/actions/basic-reporting/study.js
@@ -167,12 +167,10 @@ async function createStudyReport (studies, companies, reports) {
 
         // ---- Check if the study is caffinated ----
         const [caffinated, caffinatedMessage] = _checkCaffinated(study)
-        console.log('CAFFINATED STATUS>>>',caffinated)
         if (caffinated === true) {
             // ---- BEGIN Top Insights ----
             // Get the top insights
             const topInsights = await _getTopInsights(study)
-            console.log('TOP INSIGHTS>>>',topInsights)
             studyFile += topInsights
             // ---- END Top Insights ----
         } else {
diff --git a/cli/actions/workflows/basic-reporting.yml b/cli/actions/workflows/basic-reporting.yml
index b88d383..bf04266 100644
--- a/cli/actions/workflows/basic-reporting.yml
+++ b/cli/actions/workflows/basic-reporting.yml
@@ -18,7 +18,7 @@ jobs:
           - name: Install dependencies
             run: npm install
             working-directory: ./.github/actions/basic-reporting
-          - name: Generate basic reports for companies
+          - name: Generate basic reports for companies and studies
             uses: ./.github/actions/basic-reporting
             with:
               github-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/GitHubFunctions.GitHubFunctions.html b/docs/GitHubFunctions.GitHubFunctions.html
index ab552ac..33e2258 100644
--- a/docs/GitHubFunctions.GitHubFunctions.html
+++ b/docs/GitHubFunctions.GitHubFunctions.html
@@ -347,7 +347,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/authorize.js.html b/docs/authorize.js.html
index 183825a..0e96014 100644
--- a/docs/authorize.js.html
+++ b/docs/authorize.js.html
@@ -372,7 +372,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/classes.list.html b/docs/classes.list.html
index cf9a57c..899c8f4 100644
--- a/docs/classes.list.html
+++ b/docs/classes.list.html
@@ -207,7 +207,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/gitHubServer.js.html b/docs/gitHubServer.js.html
index e1f942f..03b8148 100644
--- a/docs/gitHubServer.js.html
+++ b/docs/gitHubServer.js.html
@@ -707,7 +707,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/github.js.html b/docs/github.js.html
index dfd9f68..7e074fe 100644
--- a/docs/github.js.html
+++ b/docs/github.js.html
@@ -1282,7 +1282,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/index.html b/docs/index.html
index 55707e2..c86bf65 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -162,6 +162,12 @@ <h2>Issues</h2>
 <h2>Support</h2>
 <p>If you need support or would like to have Mediumroast run the Caffeine Machine Intelligence service on your repository please contact the Mediumroast team via <a href="https://discord.gg/ebM4Cf8meK">Discord</a> or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io).</p>
 <h3>Release notes</h3>
+<h4>Version 0.8.06.02</h4>
+<ul>
+<li>Resolved documentation errata for Demo.md</li>
+<li>Updated text for basic reporting workflow and action to show both companies and study reports are running.</li>
+<li>Removed debugging logging statements from basic reporting action.</li>
+</ul>
 <h4>Version 0.8.06.01</h4>
 <ul>
 <li>The latest version of the SDK and CLI package now includes an initial implementation of Studies with the Foundation study.</li>
@@ -218,7 +224,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-GitHubAuth-GitHubAuth.html b/docs/module-GitHubAuth-GitHubAuth.html
index 4676bd3..6db58c4 100644
--- a/docs/module-GitHubAuth-GitHubAuth.html
+++ b/docs/module-GitHubAuth-GitHubAuth.html
@@ -347,7 +347,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-GitHubAuth.html b/docs/module-GitHubAuth.html
index 3dfa7fd..0b7f49e 100644
--- a/docs/module-GitHubAuth.html
+++ b/docs/module-GitHubAuth.html
@@ -529,7 +529,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-GitHubFunctions.html b/docs/module-GitHubFunctions.html
index c1f0ff2..81d2d70 100644
--- a/docs/module-GitHubFunctions.html
+++ b/docs/module-GitHubFunctions.html
@@ -1173,7 +1173,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Actions.html b/docs/module-baseObjects-Actions.html
index af10161..7fb8a20 100644
--- a/docs/module-baseObjects-Actions.html
+++ b/docs/module-baseObjects-Actions.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Companies.html b/docs/module-baseObjects-Companies.html
index ef0b5d5..1fed151 100644
--- a/docs/module-baseObjects-Companies.html
+++ b/docs/module-baseObjects-Companies.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Interactions.html b/docs/module-baseObjects-Interactions.html
index e930115..96a3c06 100644
--- a/docs/module-baseObjects-Interactions.html
+++ b/docs/module-baseObjects-Interactions.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Storage.html b/docs/module-baseObjects-Storage.html
index 8f97b80..c4afdcd 100644
--- a/docs/module-baseObjects-Storage.html
+++ b/docs/module-baseObjects-Storage.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Studies.html b/docs/module-baseObjects-Studies.html
index 9b78282..a026875 100644
--- a/docs/module-baseObjects-Studies.html
+++ b/docs/module-baseObjects-Studies.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects-Users.html b/docs/module-baseObjects-Users.html
index 4f1091a..3572e8e 100644
--- a/docs/module-baseObjects-Users.html
+++ b/docs/module-baseObjects-Users.html
@@ -349,7 +349,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/module-baseObjects.html b/docs/module-baseObjects.html
index f145ce2..227f09f 100644
--- a/docs/module-baseObjects.html
+++ b/docs/module-baseObjects.html
@@ -1659,7 +1659,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/modules.list.html b/docs/modules.list.html
index 655a89c..53c75f1 100644
--- a/docs/modules.list.html
+++ b/docs/modules.list.html
@@ -207,7 +207,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/quicksearch.html b/docs/quicksearch.html
index 10a336b..0d6e351 100644
--- a/docs/quicksearch.html
+++ b/docs/quicksearch.html
@@ -7,7 +7,7 @@
     <script src="scripts/fulltext-search.js"></script>
 
     <script type="text/x-docstrap-searchdb">
-    {"github.js.html":{"id":"github.js.html","title":"Source: github.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: github.js /** * @fileoverview A class that safely wraps RESTful calls to the GitHub API * @license Apache-2.0 * @version 1.0.0 * * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file github.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * * @class GitHubFunctions * @classdesc Core functions needed to interact with the GitHub API for mediumroast.io. * * @requires octokit * @requires axios * * @exports GitHubFunctions * * @example * const gitHubCtl = new GitHubFunctions(accessToken, myOrgName, 'mr-cli-setup') * const createRepoResp = await gitHubCtl.createRepository() */ import { Octokit } from \"octokit\" import axios from \"axios\" class GitHubFunctions { /** * @constructor * @classdesc Core functions needed to interact with the GitHub API for mediumroast.io. * @param {String} token - the GitHub token for the mediumroast.io application * @param {String} org - the GitHub organization for the mediumroast.io application * @param {String} processName - the name of the process that is using the GitHub API * @memberof GitHubFunctions */ constructor (token, org, processName) { this.token = token this.orgName = org this.repoName = `${org}_discovery` this.repoDesc = `A repository for all of the mediumroast.io application assets.` this.octCtl = new Octokit({auth: token}) // NOTE: The lockfile name needs to be more flexible in checking for the lockfile this.lockFileName = `${processName}.lock` this.mainBranchName = 'main' this.objectFiles = { Studies: 'Studies.json', Companies: 'Companies.json', Interactions: 'Interactions.json', Users: null, Billings: null } } /** * @async * @function getSha * @description Gets the SHA of a file in a container on a branch * @param {String} containerName - the name of the container to get the SHA from * @param {String} fileName - the short name of the file to get the SHA from * @param {String} branchName - the name of the branch to get the SHA from * @returns {Array} An array with position 0 being boolean to signify success/failure, position 1 being the response or error message, and position 2 being the SHA. * @memberof GitHubFunctions */ async getSha(containerName, fileName, branchName) { try { const response = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: branchName, path: `${containerName}/${fileName}` }) return [true, {status_code:200, status_msg: `captured sha for [${containerName}/${fileName}]`}, response.data.sha] } catch (err) { return [false, {status_code: 500, status_msg: `unable to capture sha for [${containerName}/${fileName}] due to [${err.message}]`}, err] } } /** * @async * @function getUser * @description Gets the authenticated user from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. * @todo Add a check to see if the user is a member of the organization * @todo Add a check to see if the user has admin rights to the organization */ async getUser() { // using try and catch to handle errors get user info try { const response = await this.octCtl.rest.users.getAuthenticated() return [true, `SUCCESS: able to capture current user info`, response.data] } catch (err) { return [false, `ERROR: unable to capture current user info due to [${err}]`, err.message] } } /** * @async * @function getAllUsers * @description Gets all of the users from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getAllUsers() { // using try and catch to handle errors get info for all users try { const response = await this.octCtl.rest.repos.listCollaborators({ owner: this.orgName, repo: this.repoName, affiliation: 'all' }) return [true, `SUCCESS: able to capture info for all users`, response.data] } catch (err) { return [false, `ERROR: unable to capture info for all users due to [${err}]`, err.message] } } /** * @async * @function getActionsBillings * @description Gets the complete billing status for actions from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getActionsBillings() { // using try and catch to handle errors get info for all billings data try { const response = await this.octCtl.rest.billing.getGithubActionsBillingOrg({ org: this.orgName, }) return [true, `SUCCESS: able to capture info for actions billing`, response.data] } catch (err) { return [false, {status_code: 404, status_msg: `unable to capture info for actions billing due to [${err}]`}, err.message] } } /** * @async * @function getStorageBillings * @description Gets the complete billing status for actions from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getStorageBillings() { // using try and catch to handle errors get info for all billings data try { const response = await this.octCtl.rest.billing.getSharedStorageBillingOrg({ org: this.orgName, }) return [true, `SUCCESS: able to capture info for storage billing`, response.data] } catch (err) { return [false, {status_code: 404, status_msg: `unable to capture info for storage billing due to [${err}]`}, err.message] } } /** * @function createRepository * @description Creates a repository, at the organization level, for keeping track of all mediumroast.io assets * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the created repo or error message. * @todo Make sure the repo is not public */ async createRepository () { try { const response = await this.octCtl.rest.repos.createInOrg({ org: this.orgName, name: this.repoName, description: this.repoDesc, private: true }) return [true, response.data] } catch (err) { return[false, err.message] } } /** * @function getGitHubOrg * @description If the GitHub organization exists retrieves the detail about it and returns to the caller * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the org or error message. */ async getGitHubOrg () { try { const response = await this.octCtl.rest.orgs.get({ org: this.orgName }) return[true, response.data] } catch (err) { return[false, err.message] } } /** * @async * @function getWorkflowRuns * @description Gets all of the workflow runs for the repository * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the response or error message. */ async getWorkflowRuns () { let workflows try { workflows = await this.octCtl.rest.actions.listWorkflowRunsForRepo({ owner: this.orgName, repo: this.repoName }) } catch (err) { return [false, {status_code: 500, status_msg: err.message}, err] } const workflowList = [] let totalRunTimeThisMonth = 0 for (const workflow of workflows.data.workflow_runs) { // Get the current month const currentMonth = new Date().getMonth() // Compute the runtime and if the time is less than 60s round it to 1m const runTime = Math.ceil((new Date(workflow.updated_at) - new Date(workflow.created_at)) / 1000 / 60) &lt; 1 ? 1 : Math.ceil((new Date(workflow.updated_at) - new Date(workflow.created_at)) / 1000 / 60) // If the month of the workflow is not the current month, then skip it if (new Date(workflow.updated_at).getMonth() !== currentMonth) { continue } totalRunTimeThisMonth += runTime // Add the workflow to the workflowList workflowList.push({ // Create name where the path is the name of the workflow, but remove the path and the .yml extension name: workflow.path.replace('.github/workflows/', '').replace('.yml', ''), title: workflow.display_title, id: workflow.id, workflowId: workflow.workflow_id, runTimeMinutes: runTime, status: workflow.status, conclusion: workflow.conclusion, event: workflow.event, path: workflow.path, }) } // Sort the worflowList to put the most recent workflows first workflowList.sort((a, b) =&gt; new Date(b.updated_at) - new Date(a.updated_at)) return [true, { status_code: 200, status_msg: `discovered [${workflowList.length}] workflow runs for [${this.repoName}]`,}, workflowList ] } // Create a method using the octokit to get the size of the repository and return the size in MB async getRepoSize() { let repoData = { size: 0, numFiles: 0, name: this.repoName, org: this.orgName, } // Count the number of files in the repository const countFiles = async (path = '') =&gt; { try { const response = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, path: path }) let fileCount = 0; for (const item of response.data) { if (item.type === 'file') { fileCount += 1; } else if (item.type === 'dir') { fileCount += await countFiles(item.path) } } return fileCount } catch (err) { return 0 } } try { repoData.numFiles = await countFiles() } catch (err) { repoData.numFiles = 'Unknown' } const getRepoSize = async () =&gt; { try { const response = await this.octCtl.rest.repos.get({ owner: this.orgName, repo: this.repoName }) const sizeInKB = response.data.size; const sizeInMB = sizeInKB / 1024; return sizeInMB.toFixed(2); // Convert to MB and format to 2 decimal places } catch (err) { return 0 } } try { repoData.size = await getRepoSize() } catch (err) { repoData.size = 'Unknown' } return [true, {status_code: 200, status_msg: `discovered size of [${this.repoName}]`}, repoData] } /** * @function createContainers * @description Creates the top level Study, Company and Interaction containers for all mediumroast.io assets * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the responses or error messages. */ async createContainers (containers = ['Studies', 'Companies', 'Interactions']) { let responses = [] let emptyJson = Buffer.from(JSON.stringify([])).toString('base64') for (const containerName in containers) { try { const response = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: `${containers[containerName]}/${containers[containerName]}.json`, message: `Create container [${containers[containerName]}]`, content: emptyJson, // Create a valid empty JSON file, but this must be Base64 encoded }) responses.push(response) } catch (err) { return[false, err] } } return [true, responses] } /** * @description Creates a new branch from the main branch. * @function createBranchFromMain * @async * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the main branch reference or creating the new branch. * @memberof GitHubFunctions */ async createBranchFromMain() { // Define the branch name const branchName = Date.now().toString() try { // Get the SHA of the latest commit on the main branch const mainBranchRef = await this.octCtl.rest.git.getRef({ owner: this.orgName, repo: this.repoName, ref: `heads/${this.mainBranchName}`, }) // Create a new branch based on the latest commit on the main branch const newBranchResp = await this.octCtl.rest.git.createRef({ owner: this.orgName, repo: this.repoName, ref: `refs/heads/${branchName}`, sha: mainBranchRef.data.object.sha, }) return [true, `SUCCESS: created branch [${branchName}]`, newBranchResp] } catch (error) { return [false, `FAILED: unable to create branch [${branchName}] due to [${error.message}]`, newBranchResp] } } /** * @description Merges a specified branch into the main branch by creating a pull request. * @function mergeBranchToMain * @async * @param {string} branchName - The name of the branch to merge into main. * @param {string} mySha - The SHA of the commit to use as the head of the pull request. * @param {string} [commitDescription='Performed CRUD operation on objects.'] - The description of the commit. * @returns {Promise&lt;Aray&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while creating the branch or the pull request. * @memberof GitHubFunctions */ async mergeBranchToMain(branchName, mySha, commitDescription='Performed CRUD operation on objects.') { try { // Create a new branch // const createBranchResponse = await this.octCtl.rest.git.createRef({ // owner: this.orgName, // repo: this.repoName, // ref: branchName, // sha: mySha, // }) // console.log(createBranchResponse.data) // Create a pull request const createPullRequestResponse = await this.octCtl.rest.pulls.create({ owner: this.orgName, repo: this.repoName, title: commitDescription, head: branchName, base: this.mainBranchName, body: commitDescription, }) // Merge the pull request const mergeResponse = await this.octCtl.rest.pulls.merge({ owner: this.orgName, repo: this.repoName, pull_number: createPullRequestResponse.data.number, commit_title: commitDescription, }) return [true, 'SUCCESS: Pull request created and merged successfully', mergeResponse] } catch (error) { return [false, `FAILED: Pull request not created or merged successfully due to [${error.message}]`, null] } } /** * @description Checks to see if a container is locked. * @function checkForLock * @async * @param {string} containerName - The name of the container to check for a lock. * @returns {Promise&lt;Array&lt;boolean, string&gt;&gt;} A promise that resolves to an array containing a boolean indicating success and a message. * @throws {Error} If an error occurs while getting the latest commit or the contents of the container. * @memberof GitHubFunctions * @todo Add a check to see if the lock file is older than 24 hours and if so delete it. */ async checkForLock(containerName) { // Get the latest commit const latestCommit = await this.octCtl.rest.repos.getCommit({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, }) // Check to see if the lock file exists const mainContents = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: latestCommit.data.sha, path: containerName }) // Can we search for a file with an extension of .lock? // This is due to the fact that there are other processes that may create lock files. const lockExists = mainContents.data.some( item =&gt; item.path === `${containerName}/${this.lockFileName}` ) if (lockExists) { return [true, {status_code: 200, status_msg: `container [${containerName}] is locked with lock file [${this.lockFileName}]`}, lockExists] } else { return [false, {status_code: 404, status_msg: `container [${containerName}] is not locked with lock file [${this.lockFileName}]`}, lockExists] } } /** * @description Locks a container by creating a lock file in the container. * @function lockContainer * @async * @param {string} containerName - The name of the container to lock. * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the latest commit or creating the lock file. * @memberof GitHubFunctions */ async lockContainer(containerName) { // Define the full path to the lockfile const lockFile = `${containerName}/${this.lockFileName}` // Get the latest commit const {data: latestCommit} = await this.octCtl.rest.repos.getCommit({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, }) let lockResponse try { lockResponse = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: lockFile, content: '', branch: this.mainBranchName, message: `Locking container [${containerName}]`, sha: latestCommit.sha }) return [true, `SUCCESS: Locked the container [${containerName}]`, lockResponse] } catch(err) { return [false, `FAILED: Unable to lock the container [${containerName}]`, err] } } /** * @description Unlocks a container by deleting the lock file in the container. * @function unlockContainer * @async * @param {string} containerName - The name of the container to unlock. * @param {string} commitSha - The SHA of the commit to use as the head of the pull request. * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the latest commit or deleting the lock file. * @memberof GitHubFunctions */ async unlockContainer(containerName, commitSha, branchName = this.mainBranchName) { // Define the full path to the lockfile const lockFile = `${containerName}/${this.lockFileName}` const lockExists = await this.checkForLock(containerName) // TODO: Change to try and catch if(lockExists[0]) { // NOTICE: DON'T USE DELETE AS THIS COMPLETELY REMOVES THE REPOSITORY WITHOUT MUCH WARNING const unlockResponse = await this.octCtl.rest.repos.deleteFile({ owner: this.orgName, repo: this.repoName, path: lockFile, branch: branchName, message: `Unlocking container [${containerName}]`, sha: commitSha }) return [true, `SUCCESS: Unlocked the container [${containerName}]`, unlockResponse] } else { return [false, `FAILED: Unable to unlock the container [${containerName}]`, null] } } /** * Read a blob (file) from a container (directory) in a specific branch. * * @param {string} fileName - The name of the blob to read with a complete path to the file (e.g. dirname/filename.ext). * @returns {Array} A list containing a boolean indicating success or failure, a status message, and the blob's raw data (or the error message in case of failure). */ async readBlob(fileName) { // Encode the file name including files with special characters like question marks // Custom encoding function to handle special characters const customEncodeURIComponent = (str) =&gt; { return str.split('').map(char =&gt; { return encodeURIComponent(char).replace(/[!'()*]/g, (c) =&gt; { return '%' + c.charCodeAt(0).toString(16).toUpperCase(); }); }).join(''); } const originalFileNameEncoded = customEncodeURIComponent(fileName) // Try to download the file from the repository using the download URL const downloadFile = async (url) =&gt; { try { const downloadResult = await axios.get(url, { responseType: 'arraybuffer' }) return [true, downloadResult.data] } catch (e) { if (e instanceof TypeError &amp;&amp; (e.message.includes('Request path contains unescaped characters') || e.message.includes('ERR_UNESCAPED_CHARACTERS'))) { // Handle the specific error here // For example, you can re-encode the URL or log the error return [false, 'ERR_UNESCAPED_CHARACTERS'] } return [false, e] } } // Re-encode the download URL const reEncodeDownloadUrl = (url, originalFileName) =&gt; { // Extract the base URL and the file name part let urlParts = url.split('/'); const lastPart = urlParts.pop(); // Get the last part of the URL which contains the file name and possibly query parameters // Remove the last item from the URL parts urlParts.pop() // Find the position of the first question mark that indicates the start of query parameters const altLastPart = lastPart.split('?') const queryParams = altLastPart[altLastPart.length - 1] // Encode the file name part using encodeURIComponent // const encodedFileNamePart = encodeURIComponent(fileNamePart); // Reconstruct the download URL return `${urlParts.join('/')}/${originalFileName}${queryParams ? '?' + queryParams : ''}`; } // Encode the file name and obtain the download URL const encodedFileName = encodeURIComponent(fileName) // Set the object URL const objectUrl = `https://api.github.com/repos/${this.orgName}/${this.repoName}/contents/${encodedFileName}` // Set the headers const headers = { 'Authorization': `token ${this.token}` } // Obtain the download URL const result = await axios.get(objectUrl, { headers }) let downloadUrl = result.data.download_url // Attempt to download the file from the repository let blobData = await downloadFile(downloadUrl) // Check if the file was downloaded successfully if (blobData[0]) { return [ true, { status_code: 200, status_msg: `read object [${fileName}]` }, blobData[1] ] // In this case, the error is due to unescaped characters in the URL and we need to re-encode the file name } else { // Put an if statement here to check if the error is due to unescaped characters by checking the error message if (blobData[1] === 'ERR_UNESCAPED_CHARACTERS') { downloadUrl = reEncodeDownloadUrl(downloadUrl, originalFileNameEncoded) // Try to download the file from the repository again blobData = await downloadFile(downloadUrl) if (blobData[0]) { return [ true, { status_code: 200, status_msg: `read object [${fileName}]` }, blobData[1] ] } } } return [ false, { status_code: 503, status_msg: `unable to read object [${fileName}] due to [${blobData[1]}].` }, blobData[1] ] } // async readBlob(fileName) { // // Encode the file name and obtain the download URL // const encodedFileName = encodeURIComponent(fileName) // // Set the object URL // const objectUrl = `https://api.github.com/repos/${this.orgName}/${this.repoName}/contents/${encodedFileName}` // // Set the headers // const headers = { 'Authorization': `token ${this.token}` } // // Obtain the download URL // const result = await axios.get(objectUrl, { headers }) // console.log(result) // let downloadUrl = result.data.download_url // // try { // const downloadResult = await axios.get(downloadUrl, { responseType: 'arraybuffer' }) // // console.log(downloadResult) // return [true, downloadResult, downloadUrl] // // } catch (e) { // // console.log(e) // // return [false, e, downloadUrl] // // } // } // Create a method using the octokit called deleteBlob to delete a file from the repo async deleteBlob(containerName, fileName, branchName, sha) { // Using the github API delete a file from the container try { const deleteResponse = await this.octCtl.rest.repos.deleteFile({ owner: this.orgName, repo: this.repoName, path: `${containerName}/${fileName}`, branch: branchName, message: `Delete object [${fileName}]`, sha: sha }) // Return the delete response if the delete was successful or an error if not return [true, {status_code: 200, status_msg: `deleted object [${fileName}] from container [${containerName}]`}, deleteResponse] } catch (err) { // Return the error return [false, {status_code: 503, status_msg: `unable to delete object [${fileName}] from container [${containerName}]`}, err] } } // Create a method using the octokit to write a file to the repo async writeBlob(containerName, fileName, blob, branchName, sha) { // Only pull in the file name const fileBits = fileName.split('/') const shortFilename = fileBits[fileBits.length - 1] // Using the github API write a file to the container let octoObj = { owner: this.orgName, repo: this.repoName, path: `${containerName}/${shortFilename}`, message: `Create object [${shortFilename}]`, content: blob, branch: branchName } if(sha) { octoObj.sha = sha } try { const writeResponse = await this.octCtl.rest.repos.createOrUpdateFileContents(octoObj) // Return the write response if the write was successful or an error if not return [true, `SUCCESS: wrote object [${fileName}] to container [${containerName}]`, writeResponse] } catch (err) { // Return the error return [false, `ERROR: unable to write object [${fileName}] to container [${containerName}]`, err] } } /** * @function writeObject * @description Writes an object to a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to write the object to. * @param {object} obj - The object to write to the container. * @param {string} ref - The reference to use when writing the object. * @returns {Promise&lt;string&gt;} A promise that resolves to the response from the GitHub API. * @throws {Error} If an error occurs while writing the object. * @memberof GitHubFunctions * @todo Add a check to see if the container is locked and if so return an error. */ async writeObject(containerName, obj, ref, mySha) { // Using the github API write a file to the container try { const writeResponse = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: `${containerName}/${this.objectFiles[containerName]}`, message: `Create object [${this.objectFiles[containerName]}]`, content: Buffer.from(JSON.stringify(obj)).toString('base64'), branch: ref, sha: mySha }) // Return the write response if the write was successful or an error if not return [true, `SUCCESS: wrote object [${this.objectFiles[containerName]}] to container [${containerName}]`, writeResponse] } catch (err) { // Return the error return [false, `ERROR: unable to write object [${this.objectFiles[containerName]}] to container [${containerName}]`, err] } } /** * @function readObjects * @description Reads objects from a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to read objects from. * @returns {Promise&lt;string&gt;} A promise that resolves to the decoded contents of the objects. * @throws {Error} If an error occurs while getting the content or parsing it. * @memberof GitHubFunctions */ async readObjects(containerName) { // Using the GitHub API get the contents of a file try { let objectContents = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, path: `${containerName}/${this.objectFiles[containerName]}` }) // Decode the contents const decodedContents = Buffer.from(objectContents.data.content, 'base64').toString() // Parse the contents objectContents.mrJson = JSON.parse(decodedContents) // Return the contents return [true, `SUCCESS: read and returned [${containerName}/${this.objectFiles[containerName]}]`, objectContents] } catch (err) { // Return the error return [false, `ERROR: unable to read [${containerName}/${this.objectFiles[containerName]}]`, err] } } /** * @function updateObject * @description Reads an object from a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to read the object from. * @param {string} objName - The name of the object to update. * @param {string} key - The key of the object to update. * @param {string} value - The value to update the key with. * @param {boolean} [dontWrite=false] - A flag to indicate if the object should be written back to the container or not. * @param {boolean} [system=false] - A flag to indicate if the update is a system call or not. * @param {Array} [whiteList=[]] - A list of keys that are allowed to be updated. * @returns {Promise&lt;Array&gt;} A promise that resolves to the decoded contents of the object. * @memberof GitHubFunctions * @todo As deleteObject progresses look to see if we can improve here too */ async updateObject(containerName, objName, key, value, dontWrite=false, system=false, whiteList=[]) { // console.log(`Updating object [${objName}] in container [${containerName}] with key [${key}] and value [${value}]`) // Check to see if this is a system call or not if(!system) { // Since this is not a system call check to see if the key is in the white list if(!whiteList.includes(key)) { return [ false, { status_code: 403, status_msg: `Updating the key [${key}] is not supported.` }, null ] } } // Using the method above read the objects const readResponse = await this.readObjects(containerName) // Check to see if the read was successful if(!readResponse[0]) { return [ false, {status_code: 500, status_msg: `Unable to read source objects from GitHub.`}, readResponse ] } // Catch the container if needed let repoMetadata = { containers: {}, branch: {} } // If dontWrite is true then don't catch the container let caught = {} if(!dontWrite) { repoMetadata.containers[containerName] = {} caught = await this.catchContainer(repoMetadata) } // Loop through the objects, find and update the objects matching the name for (const obj in readResponse[2].mrJson) { if(readResponse[2].mrJson[obj].name === objName) { readResponse[2].mrJson[obj][key] = value // Update the modified date of the object const now = new Date() readResponse[2].mrJson[obj].modification_date = now.toISOString() } } // If this flag is set merely return the modified object(s) to the caller if (dontWrite) { return [ true, { status_code: 200, status_msg: `Merged updates object(s) with [${containerName}] objects.` }, readResponse[2].mrJson ] } // Call the method above to write the object const writeResponse = await this.writeObject( containerName, readResponse[2].mrJson, caught[2].branch.name, caught[2].containers[containerName].objectSha) // Check to see if the write was successful and return the error if not if(!writeResponse[0]) { return [ false, {status_code: 503, status_msg: `Unable to write the objects.`}, writeResponse ] } // Release the container const released = await this.releaseContainer(caught[2]) if(!released[0]) { return [ false, { status_code: 503, status_msg: `Cannot release the container please check [${containerName}] in GitHub.` }, released ] } // Finally return success with the results of the release return [ true, { status_code: 200, status_msg: `Updated [${containerName}] object of the name [${objName}] with [${key} = ${value}].` }, released ] } /** * @function deleteObject * @description Deletes an object from a specified container using the GitHub API. * @async * @param {string} objName - The name of the object to delete. * @param {object} source - The source object that contains the from and to containers. * @returns {Promise&lt;Array&gt;} A promise that resolves to the decoded contents of the object. * @memberof GitHubFunctions */ async deleteObject(objName, source, repoMetadata=null, catchIt=true) { // NOTE: source has a weakness we will have to remedy later, notably from can be Studies and Companies // source = { // from: 'Interactions', // to: ['Companies'] // } // Create an object that maps the from object type to the to object type fields to be updated const fieldMap = { Interactions: { Companies: 'linked_interactions', // Studies: 'linked_interactions' }, Companies: { Interactions: 'linked_companies', // Studies: 'linked_companies' }, Studies: { Interactions: 'linked_studies', Companies: 'linked_studies' } } // Catch the container if needed if(catchIt) { repoMetadata = { containers: {}, branch: {} } // Catch the container(s) repoMetadata.containers[source.from] = {} repoMetadata.containers[source.to[0]] = {} let caught = await this.catchContainer(repoMetadata) repoMetadata = caught[2] } // Loop through the from objects, find and remove the objects matching the name for (const obj in repoMetadata.containers[source.from].objects) { if(repoMetadata.containers[source.from].objects[obj].name === objName) { // If from is Interactions then we need to delete the actual file from the repo based on objName if(source.from === 'Interactions') { // Obtain the sha of the object to delete by obtaining the file name from the url attribute of the Interaction const fileName = repoMetadata.containers[source.from].objects[obj].url // Obtain the sha for fileName using octokit const { data } = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, path: fileName }) // Remove the path from the file name const fileBits = fileName.split('/') const shortFilename = fileBits[fileBits.length - 1] // Call the method above to delete the object using data.sha const deleteResponse = await this.deleteBlob( source.from, shortFilename, repoMetadata.branch.name, data.sha ) // Check to see if the delete was successful and return the error if not if(!deleteResponse[0]) { return [ false, {status_code: 503, status_msg: `Unable to delete the [${source.from}] object [${objName}].`}, deleteResponse ] } } // Remove the object from the array repoMetadata.containers[source.from].objects.splice(obj, 1) } } // Loop through the to objects, find and remove objName from the linked objects and update the modification date for (const obj in repoMetadata.containers[source.to[0]].objects) { if(objName in repoMetadata.containers[source.to[0]].objects[obj][fieldMap[source.from][source.to[0]]]) { // Delete the object from the linked objects object delete repoMetadata.containers[source.to[0]].objects[obj][fieldMap[source.from][source.to[0]]][objName] // Update the modification date of the object const now = new Date() repoMetadata.containers[source.to[0]].objects[obj].modification_date = now.toISOString() } } // Call getSha to get the sha of the from object const fromSha = await this.getSha(source.from, this.objectFiles[source.from], repoMetadata.branch.name) // Check to see if the sha was captured and return the error if not if(!fromSha[0]) { return [ false, {status_code: 503, status_msg: `Unable to capture the [${source.from}] sha.`}, fromSha ] } // Call the method above to write the from objects const writeResponse = await this.writeObject( source.from, repoMetadata.containers[source.from].objects, repoMetadata.branch.name, fromSha[2]) // Check to see if the write was successful and return the error if not if(!writeResponse[0]) { console.log(writeResponse) return [ false, {status_code: 503, status_msg: `Unable to write the [${source.from}] objects.`}, writeResponse ] } // Call getSha to get the sha of the to object const toSha = await this.getSha(source.to[0], this.objectFiles[source.to[0]], repoMetadata.branch.name) // Check to see if the sha was captured and return the error if not if(!toSha[0]) { return [ false, {status_code: 503, status_msg: `Unable to capture the [${source.to[0]}] sha.`}, toSha ] } // Call the method above to write the to objects const writeResponse2 = await this.writeObject( source.to, repoMetadata.containers[source.to[0]].objects, repoMetadata.branch.name, toSha[2]) // Check to see if the write was successful and return the error if not if(!writeResponse2[0]) { return [ false, {status_code: 503, status_msg: `Unable to write the [${source.to}] objects.`}, writeResponse2 ] } // Release the container if(catchIt){ const released = await this.releaseContainer(repoMetadata) if(!released[0]) { return [ false, { status_code: 503, status_msg: `Cannot release the container please check [${source.from}] in GitHub.` }, released ] } // Finally return success with the results of the release return [ true, { status_code: 200, status_msg: `Deleted [${source.from}] object of the name [${objName}], and links in associated objects.` }, released ] } else { // Return success with the write reponses return [ true, { status_code: 200, status_msg: `Deleted [${source.from}] object of the name [${objName}], and links in associated objects.` }, [writeResponse, writeResponse2] ] } } /** * @function catchContainer * @description Catches a container by locking it, creating a new branch, reading the objects, and returning the metadata. * @param {Object} repoMetadata - The metadata object that contains the containers and branch information. * @returns {Promise&lt;Array&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the metadata object. * @memberof GitHubFunctions */ async catchContainer(repoMetadata) { // Check to see if the containers are locked for (const container in repoMetadata.containers) { // Call the method above to check for a lock const lockExists = await this.checkForLock(container) // If the lock exists return an error if(lockExists[0]) { return [false, {status_code: 503, status_msg:`the container [${container}] is locked unable and cannot perform creates, updates or deletes on objects.`}, lockExists] } } // Lock the containers for (const container in repoMetadata.containers) { // Call the method above to lock the container const locked = await this.lockContainer(container) // Check to see if the container was locked and return the error if not if(!locked[0]) { return [false, {status_code: 503, status_msg: `unable to lock [${container}] and cannot perform creates, updates or deletes on objects.`}, locked] } // Save the lock sha repoMetadata.containers[container].lockSha = locked[2].data.content.sha } // Call the method above createBranchFromMain to create a new branch const branchCreated = await this.createBranchFromMain() // Check to see if the branch was created if(!branchCreated[0]) { return [false, {status_code: 503, status_msg: `unable to create new branch`}, branchCreated] } // Save the branch sha into containers as a separate object repoMetadata.branch = { name: branchCreated[2].data.ref, sha: branchCreated[2].data.object.sha } // Read the objects from the containers for (const container in repoMetadata.containers) { // Call the method above to read the objects const readResponse = await this.readObjects(container) // Check to see if the read was successful if(!readResponse[0]) { return [false, {status_code: 503, status_msg: `Unable to read the source objects [${container}/${this.objectFiles[container]}].`}, readResponse] } // Save the object sha into containers as a separate object repoMetadata.containers[container].objectSha = readResponse[2].data.sha // Save the objects into containers as a separate object repoMetadata.containers[container].objects = readResponse[2].mrJson } return [true,{status_code: 200, status_msg: `${repoMetadata.containers.length} containers are ready for use.`}, repoMetadata] } /** * @function releaseContainer * @description Releases a container by unlocking it and merging the branch to main. * @param {Object} repoMetadata - The metadata object that contains the containers and branch information. * @returns {Promise&lt;Array&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @memberof GitHubFunctions */ async releaseContainer(repoMetadata) { // Merge the branch to main const mergeResponse = await this.mergeBranchToMain(repoMetadata.branch.name, repoMetadata.branch.sha) // Check to see if the merge was successful and return the error if not if(!mergeResponse[0]) { return [false,{status_code:503, status_msg: `Unable to merge the branch to main.`}, mergeResponse] } // Unlock the containers by looping through them for (const container in repoMetadata.containers) { // Call the method above to unlock the container const branchUnlocked = await this.unlockContainer( container, repoMetadata.containers[container].lockSha, repoMetadata.branch.name) if(!branchUnlocked[0]) { return [false, {status_code: 503, status_msg: `Unable to unlock the container, objects may have been written please check [${container}] for objects and the lock file.`}, branchUnlocked] } // Unlock main const mainUnlocked = await this.unlockContainer( container, repoMetadata.containers[container].lockSha ) if(!mainUnlocked[0]) { return [false, {status_code: 503, status_msg: `Unable to unlock the container, objects may have been written please check [${container}] for objects and the lock file.`}, mainUnlocked] } } // Return success with number of objects written return [true, {status_code: 200, status_msg: `Released [${repoMetadata.containers.length}] containers.`}, null] } } export default GitHubFunctions × Search results Close "},"authorize.js.html":{"id":"authorize.js.html","title":"Source: authorize.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: authorize.js /** * @fileoverview This file contains the code to authorize the user to the GitHub API * @license Apache-2.0 * @version 2.0.0 * * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file authorize.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * * @class GitHubAuth * @classdesc This class is used to authorize the user to the GitHub API * * @requires axios * @requires open * @requires octoDevAuth * @requires chalk * @requires cli-table3 * @requires configparser * @requires FilesystemOperators * * @exports GitHubAuth * * @example * import {GitHubAuth} from './api/authorize.js' * const github = new GitHubAuth(env, environ, configFile) * const githubToken = github.verifyAccessToken() * */ import open from \"open\" import * as octoDevAuth from '@octokit/auth-oauth-device' import chalk from \"chalk\" import Table from 'cli-table3' import FilesystemOperators from '../cli/filesystem.js' class GitHubAuth { /** * @constructor * @param {Object} env - The environment object * @param {Object} environ - The environmentals object * @param {String} configFile - The configuration file */ constructor (env, environ, configFile, configExists) { this.env = env this.clientType = 'github-app' this.configFile = configFile this.configExists = configExists this.filesystem = new FilesystemOperators() this.environ = environ // Use ternary operator to determine if the config file exists and if it does read it else set it to null this.config = configExists ? environ.readConfig(configFile) : null } verifyGitHubSection () { if (!this.config) { return false } return this.config.hasSection('GitHub') } _getFromConfig (section, option) { const hasOption = this.config.hasKey(section, option) if (hasOption) { return this.config.get(section, option) } else { return null } } getAccessTokenFromConfig () { return this._getFromConfig('GitHub', 'token') } getAuthTypeFromConfig () { return this._getFromConfig('GitHub', 'authType') } async checkTokenExpiration(token) { const response = await fetch('https://api.github.com/user', { method: 'GET', headers: { 'Authorization': `token ${token}`, 'Accept': 'application/vnd.github.v3+json' } }) if (!response.ok) { return [false, {status_code: 500, status_msg: response.statusText}, null] } const data = await response.json() return [true, {status_code: 200, status_msg: response.statusText}, data] } /** * @async * @function getAccessTokenDeviceFlow * @description Get the access token using the device flow * @returns {Object} The access token object */ async getAccessTokenDeviceFlow() { // Set the clientId depending on if the config file exists const clientId = this.configExists ? this.env.clientId : this.env.GitHub.clientId // Construct the oAuth device flow object which starts the browser let deviceCode // Provide a place for the device code to be captured const deviceauth = octoDevAuth.createOAuthDeviceAuth({ clientType: this.clientType, clientId: clientId, onVerification(verifier) { deviceCode = verifier.device_code // Print the verification artifact to the console console.log( chalk.blue.bold(`If supported opening your browser to the Authorization website.\\nIf your browser doesn't open, please copy and paste the Authorization website URL into your browser's address bar.\\n`) ) const authWebsitePrefix = `Authorization website:` const authCodePrefix = `Authorization code:` const authWebsite = chalk.bold.red(verifier.verification_uri) const authCode = chalk.bold.red(verifier.user_code) const table = new Table({ rows: [ [authWebsitePrefix, authWebsite], [authCodePrefix, authCode] ] }) // Get the table as a string const tableString = table.toString() // Check to see if the table string is empty if (tableString !== '') { // Print the table to the console, since not empty console.log(tableString) } else { // Print strings to the console, since empty console.log(`\\t${authWebsitePrefix} ${authWebsite}`) console.log(`\\t${authCodePrefix} ${authCode}`) } console.log(`\\nCopy and paste the Authorization code into correct field on the Authorization website. Once authorized setup will continue.\\n`) open(verifier.verification_uri) } }) // Call GitHub to obtain the token let accessToken = await deviceauth({type: 'oauth'}) accessToken.deviceCode = deviceCode return accessToken } /** * @async * @function verifyAccessToken * @description Verify if the access token is valid and if not get a new one depending on this.env.authType * @param {Boolean} saveToConfig - Save to the configuration file, default is true */ async verifyAccessToken (saveToConfig=true) { if (this.configExists) { // Get key variables from the config file const hasGitHubSection = this.verifyGitHubSection() // If the GitHub section is not available, then the token is not available, return false. // This is only to be used when called from a function that intendes to setup the configuration file, but // just in case this condition occurs we want to return clearly to the caller. if (!hasGitHubSection) { return [false, {status_code: 500, status_msg: 'The GitHub section is not available in the configuration file'}, null] } } // Get the access token and authType from the config file since the section is available let accessToken // If the configuration exists then we can obtain the token and authType from the config file, but if // the configuration is not present and the intention is to use PAT this code won't be executed. Therefore, // prompting the user for the PAT, verifyin the PAT, and saving the PAT to the config file will be done in the // caller. However, if the intention is to use deviceFlow then we can support that here and return the token to the // caller which will then save the token and the authType to the config file. let authType = 'deviceFlow' if (this.configExists) { accessToken = this.getAccessTokenFromConfig() authType = this.getAuthTypeFromConfig() } // Check to see if the token is valid but if the config isn't present then we can't check the token const validToken = this.configExists ? await this.checkTokenExpiration(accessToken) : [false, {status_code: 500, status_msg: 'The configuration file isn\\'t present'}, null] if (validToken[0] &amp;&amp; this.configExists) { return [ true, {status_code: 200, status_msg: validToken[1].status_msg}, {token: accessToken, authType: authType} ] // If the token is not valid, then we need to return to the caller (PAT) or get a new token (deviceFlow) } else { // Case for a Personal Access Token if (authType === 'pat') { // Return the error message to the caller return [ false, {status_code: 500, status_msg: `The Personal Access Token appears to be invalid and was rejected with an error message [${validToken[1].status_msg}].\\n\\tPlease obtain a new PAT and update the GitHub token setting in the configuration file [${this.configFile}].`}, null ] // Case for the device flow } else if (authType === 'deviceFlow') { // Get the new access token accessToken = await this.getAccessTokenDeviceFlow() // Update the config if the config file exists and if saveToConfig is true if (this.configExists &amp;&amp; this.config &amp;&amp; this.saveToConfig) { let tmpConfig = this.environ.updateConfigSetting(this.config, 'GitHub', 'token', accessToken.token) tmpConfig = this.environ.updateConfigSetting(tmpConfig[1], 'GitHub', 'authType', authType) tmpConfig = this.environ.updateConfigSetting(tmpConfig[1], 'GitHub', 'deviceCode', accessToken.deviceCode) // Save the config file if needed this.config = tmpConfig[1] if (saveToConfig) { await this.config.write(this.configFile) } } return [ true, {status_code: 200, status_msg: `The access token has been successfully updated and saved to the configuration file [${this.configFile}]`}, {token: accessToken.token, authType: authType, deviceCode: accessToken.deviceCode} ] } } } decodeJWT (token) { if(token !== null || token !== undefined){ const base64String = token.split('.')[1] const decodedValue = JSON.parse( Buffer.from( base64String, 'base64') .toString('ascii') ) return decodedValue } return null } } export {GitHubAuth} × Search results Close "},"gitHubServer.js.html":{"id":"gitHubServer.js.html","title":"Source: gitHubServer.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: gitHubServer.js /** * A class for authenticating and talking to the mediumroast.io backend * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file gitHubServer.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * @license Apache-2.0 * @version 2.0.0 * * @class baseObjects * @classdesc An implementation for interacting with the GitHub backend. * * @requires GitHubFunctions * @requires crypto * @requires fs * @requires path * @requires fileURLToPath * * @exports {Studies, Companies, Interactions, Users, Storage, Actions} * * @example * import {Companies, Interactions, Users, Billings} from './api/gitHubServer.js' * const companies = new Companies(token, org, processName) * const interactions = new Interactions(token, org, processName) * const users = new Users(token, org, processName) * const billings = new Billings(token, org, processName) * * const allCompanies = await companies.getAll() * const allInteractions = await interactions.getAll() * const allUsers = await users.getAll() * const allBillings = await billings.getAll() * * const company = await companies.findByName('myCompany') * const interaction = await interactions.findByName('myInteraction') * const user = await users.findByName('myUser') * */ // Import required modules import GitHubFunctions from './github.js' import { createHash } from 'crypto' import fs from 'fs' import * as path from 'path' import { fileURLToPath } from 'url' class baseObjects { constructor(token, org, processName, objType) { this.serverCtl = new GitHubFunctions(token, org, processName) this.objType = objType this.objectFiles = { Studies: 'Studies.json', Companies: 'Companies.json', Interactions: 'Interactions.json', Users: null } } /** * @async * @function getAll * @description Get all objects from the mediumroast.io application * @returns {Array} the results from the called function mrRest class */ async getAll() { return await this.serverCtl.readObjects(this.objType) } /** * @async * @function findByName * @description Find all objects by name from the mediumroast.io application * @param {String} name - the name of the object to find * @returns {Array} the results from the called function mrRest class */ async findByName(name) { return this.findByX('name', name) } /** * @async * @function findById * @description Find all objects by id from the mediumroast.io application * @param {String} id - the id of the object to find * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class * @deprecated */ async findById(id) { return false const fullEndpoint = '/' + this.apiVersion + '/' + this.objType + '/' + endpoint const my_obj = {findByX: \"id\", xEquals: id} return this.rest.postObj(fullEndpoint, my_obj) } /** * @async * @function findByX * @description Find all objects by attribute and value pair from the mediumroast.io application * @param {String} attribute - the attribute used to find objects * @param {String} value - the value for the defined attribute * @returns {Array} the results from the called function mrRest class */ async findByX(attribute, value, allObjects=null) { if(attribute === 'name') { value = value.toLowerCase() } // console.log(`Searching for ${this.objType} where ${attribute} = ${value}`) let myObjects = [] if(allObjects === null) { const allObjectsResp = await this.serverCtl.readObjects(this.objType) allObjects = allObjectsResp[2].mrJson } // If the length of allObjects is 0 then return an error // This will occur when there are no objects of the type in the backend if(allObjects.length === 0) { return [false, {status_code: 404, status_msg: `no ${this.objType} found`}, null] } for(const obj in allObjects) { let currentObject attribute == 'name' ? currentObject = allObjects[obj][attribute].toLowerCase() : currentObject = allObjects[obj][attribute] if(currentObject === value) { myObjects.push(allObjects[obj]) } } if (myObjects.length === 0) { return [false, {status_code: 404, status_msg: `no ${this.objType} found where ${attribute} = ${value}`}, null] } else { return [true, `SUCCESS: found all objects where ${attribute} = ${value}`, myObjects] } } /** * @async * @function createObj * @description Create objects in the mediumroast.io application * @param {Array} objs - the objects to create in the backend * @returns {Array} the results from the called function mrRest class */ // async createObj1(objs) { // return await this.serverCtl.createObjects(this.objType, objs) // } async createObj(objs) { // Create the repoMetadata object let repoMetadata = { containers: { [this.objType]: {} }, branch: {} } // Catch the container const caught = await this.serverCtl.catchContainer(repoMetadata) // If the container is locked then return the caught object if(!caught[0]) { return caught } // Get the sha for the current branch/object const sha = await this.serverCtl.getSha( this.objType, this.objectFiles[this.objType], repoMetadata.branch.name ) // If the sha is not found then return the sha object if(!sha[0]) { return sha } // Append the new object to the existing objects const mergedObjects = [...caught[2].containers[this.objType].objects, ...objs] // Write the new objects to the container const writeResp = await this.serverCtl.writeObject( this.objType, mergedObjects, repoMetadata.branch.name, sha[2] ) // If the write fails then return the writeResp if(!writeResp[0]) { return writeResp } // Release the container const released = await this.serverCtl.releaseContainer(caught[2]) // If the release fails then return the released object if(!released[0]) { return released } // Return a success message return [true, {status_code: 200, status_msg: `created [${objs.length}] ${this.objType}`}, null] } /** * @async * @function updateObj * @description Update an object in the mediumroast.io application * @param {Object} obj - the object to update in the backend which includes the id and, the attribute and value to be updated * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class */ async updateObj(objName, key, value, dontWrite, system, whiteList) { return await this.serverCtl.updateObject(this.objType, objName, key, value, dontWrite, system, whiteList) } /** * @async * @function deleteObj * @description Delete an object in the mediumroast.io application * @param {String} id - the object to be deleted in the mediumroast.io application * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class * @todo implment when available in the backend */ async deleteObj(objName, source, repoMetadata=null, catchIt=true) { return await this.serverCtl.deleteObject(objName, source, repoMetadata, catchIt) } /** * @async * @function linkObj * @description Link objects in the mediumroast.io application * @param {Array} objs - the objects to link in the backend * @returns {Array} the results from the called function mrRest class */ linkObj(objs) { let linkedObjs = {} for(const obj in objs) { const objName = objs[obj].name const sha256Hash = createHash('sha256').update(objName).digest('hex') linkedObjs[objName] = sha256Hash } return linkedObjs } // Create a function that checks for a locked container using the serverCtl.checkForLock() function async checkForLock() { return await this.serverCtl.checkForLock(this.objType) } } class Studies extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the study objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Studies') } } // Create a subclass called Users that inherits from baseObjects class Users extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the user objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Users') } // Create a new method for getAll that is specific to the Users class using getUser() in github.js async getAll() { return await this.serverCtl.getAllUsers() } // Create a new method for findMyself that is specific to the Users class using getUser() in github.js async getMyself() { return await this.serverCtl.getUser() } async findByName(name) { return this.findByX('login', name) } async findByX(attribute, value) { let myUsers = [] const allUsersResp = await this.getAll() const allUsers = allUsersResp[2] for(const user in allUsers) { if(allUsers[user][attribute] === value) { myUsers.push(allUsers[user]) } } return [true, `SUCCESS: found all users where ${attribute} = ${value}`, myUsers] } } // Create a subclass called Users that inherits from baseObjects class Storage extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the user objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Billings') } // Create a new method for getAll that is specific to the Billings class using getBillings() in github.js async getAll() { return await this.serverCtl.getRepoSize() } // Create a new method of to get the storage billing status only async getStorageBilling() { return await this.serverCtl.getStorageBillings() } } class Companies extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the company objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Companies') } async updateObj(objToUpdate, dontWrite=false, system=false) { // Destructure objToUpdate const { name, key, value } = objToUpdate // Define the attributes that can be updated by the user const whiteList = [ 'description', 'company_type', 'url', 'role', 'wikipedia_url', 'status', 'logo_url', 'region', 'country', 'city', 'state_province', 'zip_postal', 'street_address', 'latitude', 'longitude','phone', 'google_maps_url', 'google_news_url', 'google_finance_url','google_patents_url', 'cik', 'stock_symbol', 'stock_exchange', 'recent_10k_url', 'recent_10q_url', 'firmographic_url', 'filings_url', 'owner_tranasactions', 'industry', 'industry_code', 'industry_group_code', 'industry_group_description', 'major_group_code','major_group_description' ] return await super.updateObj(name, key, value, dontWrite, system, whiteList) } async deleteObj(objName, allowOrphans=false) { let source = { from: 'Companies', to: ['Interactions'] } // If allowOrphans is true then use the baseObjects deleteObj if(allowOrphans){ return await super.deleteObj(objName, source) } // Catch the Companies and Interaction containers // Assign repoMetadata to capture Companies nad Studies let repoMetadata = { containers: { Companies: {}, Interactions: {} }, branch: {} } const caught = await this.serverCtl.catchContainer(repoMetadata) // Use findByX to get all linkedInteractions // NOTE: This has to be done here because the company has been deleted in the next step const getCompanyObject = await this.findByX('name', objName, caught[2].containers.Companies.objects) if(!getCompanyObject[0]) { return getCompanyObject } const linkedInteractions = getCompanyObject[2][0].linked_interactions // Delete the company // Use deleteObj to delete the company const deleteCompanyObjResp = await this.serverCtl.deleteObject( objName, source, caught[2], false ) if(!deleteCompanyObjResp[0]) { return deleteCompanyObjResp } // Delete all linkedInteractions // Update source to be from the perspective of the Interactions source = { from: 'Interactions', to: ['Companies'] } // Use deleteObect to delete all linkedInteractions for(const interaction in linkedInteractions) { const deleteInteractionObjResp = await this.serverCtl.deleteObject( interaction, source, caught[2], false ) if(!deleteInteractionObjResp[0]) { return deleteInteractionObjResp } } // Release the container const relased = await this.serverCtl.releaseContainer(caught[2]) if(!relased[0]) { return relased } // Return the response return [true, {status_code: 200, status_msg: `deleted company [${objName}] and all linked interactions`}, null] } } class Interactions extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the interaction objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Interactions') } async updateObj(objToUpdate, dontWrite=false, system=false) { // Destructure objToUpdate const { name, key, value } = objToUpdate // Define the attributes that can be updated by the user const whiteList = [ 'status', 'content_type', 'file_size', 'reading_time', 'word_count', 'page_count', 'description', 'abstract', 'region', 'country', 'city', 'state_province', 'zip_postal', 'street_address', 'latitude', 'longitude', 'public', 'groups' ] return await super.updateObj(name, key, value, dontWrite, system, whiteList) } async deleteObj(objName) { const source = { from: 'Interactions', to: ['Companies'] } return await super.deleteObj(objName, source) } async findByHash(hash) { return this.findByX('file_hash', hash) } } class Actions extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the interaction objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Actions') } _generateManifest(dir, filelist) { // Define which content to skip const skipContent = ['.DS_Store', 'node_modules'] const __filename = fileURLToPath(import.meta.url) const __dirname = path.dirname(__filename); // Use regex to prune everything after mediumroast_js/ const basePath = __dirname.match(/.*mediumroast_js\\//)[0]; // Append cli/actions to the base path dir = dir || path.resolve(path.join(basePath, 'cli/actions')) const files = fs.readdirSync(dir) filelist = filelist || []; files.forEach((file) =&gt; { // Skip unneeded directories if (skipContent.includes(file)) { return } const fullPath = path.join(dir, file); if (fs.statSync(fullPath).isDirectory()) { filelist = this._generateManifest(path.join(dir, file), filelist) } else { // Substitute .github for the first part of the path, in the variable dir if (dir.includes('./')) { dir = dir.replace('./', '') } // This will be the repository name let dotGitHub = dir.replace(/.*(workflows|actions)/, '.github/$1') filelist.push({ fileName: file, containerName: dotGitHub, srcURL: new URL(`file://${fullPath}`) }) } }) return filelist } async updateActions() { // Discover the manifest const actionsManifest = this._generateManifest() // Capture detailed install status let installStatus = { successCount: 0, failCount: 0, success: [], fail: [], total: actionsManifest.length } for (const action of actionsManifest) { // Loop through the actionsManifest and install each action let status = false let blobData try { // Read in the blob file blobData = fs.readFileSync(action.srcURL, 'base64') status = true } catch (err) { // console.log(`Unable to read file [${action.fileName}] because: ${err}`) return [false,{status_code: 500, status_msg: `Unable to read file [${action.fileName}] because: ${err}`}, installStatus] } if(status) { // Get the sha for the current branch/object const sha = await this.serverCtl.getSha( action.containerName, action.fileName, 'main' ) // Keep action update failures // Install the action const installResp = await this.serverCtl.writeBlob( action.containerName, action.fileName, blobData, 'main', sha[2] ) if(installResp[0]){ installStatus.success.push({fileName: action.fileName, containerName: action.catchContainer, installMsg: installResp[1].status_msg}) installStatus.successCount++ } else { installStatus.fail.push({fileName: action.fileName, containerName: action.catchContainer, installMsg: installResp[1].status_msg}) installStatus.failCount++ } } else { return [false, {status_code: 503,status_msg:`Failed to read item [${action.fileName}]`}, installStatus] } } return [true, {status_code: 200, status_msg:`All actions installed`}, installStatus] } // Create a new method of to get the actions billing status only async getActionsBilling() { return await this.serverCtl.getActionsBillings() } async getAll() { return await this.serverCtl.getWorkflowRuns() } } // Export classes for consumers export { Studies, Companies, Interactions, Users, Storage, Actions } × Search results Close "},"modules.list.html":{"id":"modules.list.html","title":"Modules","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Modules × Search results Close "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Classes × Search results Close "},"tutorials.list.html":{"id":"tutorials.list.html","title":"Tutorials","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Tutorials × Search results Close "},"index.html":{"id":"index.html","title":"Index","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Welcome Mediumroast for GitHub Products organizations must build evidence based product plans from competitive and customer interactions. Using Artificial Intelligence and Machine Learning, Mediumroast for GitHub realizes an active product planning repository for Product Managers and Developers everyone can see, use, and reference. The repository is built on GitHub and is accessible via Command Line Interface (CLI) and a Software Development Kit (SDK). This CLI and SDK are built on Node.js and is available for Linux and MacOS operating systems. A GitHub Page Version of this content is also available, but the screencasts and videos won't display. Installation and configuration Mediumroast for GitHub includes a GitHub Application, a Command Line Interface, and a Software Development Kit. The following steps show you how to install the App and the CLI with SDK. Preinstallation requirements A GitHub organization Permissions in your GitHub organization to install a GitHub application. Access to a command line terminal on Linux or MacOS. Node.js installed, ideally globally for all users. NPM installed, ideally globally for all users. Step 1 - Install the GitHub App Browse to the Mediumroast for GitHub GitHub Application and: Click install, Choose the location for the installation, usually your organization, Confirm the requested permissions, and Browse to your organization's Settings &gt; Third-Party Access &gt; GitHub Apps and confirm that Mediumroast for GitHub is installed. Step 2 - Install mediumroast_js This package mediumroast_js can be installed and removed via npm, several ways to install follow. For Linux and MacOS Assuming the preinstallation requirements, installation of node.js and npm, are met please one one of the following. Global installation for all users: sudo npm i -g mediumroast_js Local installation for a developer or single user: npm i mediumroast_js For WinOS Coming soon. Step 3.1 - Upgrade the CLI After installation there are times when you may want to upgrade the CLI to the latest version, run the following. Global upgrade for all users: sudo npm i -g mediumroast_js Local upgrade for a developer or single user: npm i mediumroast_js Step 3.2 - Upgrade Actions After upgrading the CLI it may be necessary to upgrade the actions in the repository. To do this run mrcli actions --update and the actions will be updated to the latest version. Step 4.1 - Setup the CLI Before you can use the Mediumroast for GitHub CLI the environment must be setup. With the CLI installed please run mrcli setup to start the setup process, note there's a video of the setup process in CLI README. Running mrcli setup creates a repository in your oganization called &lt;organization_name&gt;_discovery to contain all interactions and companies, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below. Step 4.2 - Setup the CLI after initial setup Running mrcli setup a second time on an existing repository will not create a new one, instead it will detect the existing repository and prompt to update your authentication method and report theme. This is used typically when another user in your organization needs to access the repository. Step 5.1 - Verify your installation via the CLI After the setup process is complete you can verify the installation by running mrcli company to see the companies in the repository. Example screenshot of companies table Step 5.2 - Verify your installation via GitHub actions Additionally, two GitHub Actions are installed in the repository, one to clean up branches and the other to generate reports. To verify the actions are installed browse to the repository and click on the Actions tab to see the actions running. These actions are set to run on a schedule, but can be run manually. When a run you'll find an automatically generated README.md file in the repository and links to company reports in the README.md, an example screenshot of the repository companies report is below. Example screenshot of in repository companies report Warning Since Mediumroast for GitHub creates a regular repository you can interact with it as normal, but doing so is not recommended. If you interact with the repository, in regular ways, this could result in Mediumroast for GitHub becoming inoperable. There are cases where it may become necessary to directly work with the repository, but that should be rare. Contributing If you're interested in contributing to the Mediumroast for GitHub project, please review the CONTRIBUTING.md file in the .github directory of the repository. The file contains information on how to get started, how to clone the repository, and how to install the SDK for development. Issues If you detect a problem or want to suggest an improvement open an issue and we will work with you to resolve or respond. Support If you need support or would like to have Mediumroast run the Caffeine Machine Intelligence service on your repository please contact the Mediumroast team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Release notes Version 0.8.06.01 The latest version of the SDK and CLI package now includes an initial implementation of Studies with the Foundation study. The SDK and CLI may run on for Windows OS, but it has not been tested. If you choose to install and run into problems please open an issue and we will work with you to resolve the matter. cli-table has been replaced by cli-table3 to ensure that CLI tabular outputs are on a stable and maintained package. The xlsx package has been removed and replaced with exceljs for improved output to Excel files, and due to the security vulnerability in the xlsx package. × Search results Close "},"GitHubFunctions.GitHubFunctions.html":{"id":"GitHubFunctions.GitHubFunctions.html","title":"Class: GitHubFunctions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: GitHubFunctions GitHubFunctions Core functions needed to interact with the GitHub API for mediumroast.io. new GitHubFunctions(token, org, processName) Parameters: Name Type Description token String the GitHub token for the mediumroast.io application org String the GitHub organization for the mediumroast.io application processName String the name of the process that is using the GitHub API Source: github.js, line 36 × Search results Close "},"module-GitHubAuth.html":{"id":"module-GitHubAuth.html","title":"Module: GitHubAuth","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: GitHubAuth authorize.js Version: 2.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: authorize.js, line 1 Example import {GitHubAuth} from './api/authorize.js' const github = new GitHubAuth(env, environ, configFile) const githubToken = github.verifyAccessToken() Requires module:axios module:open module:octoDevAuth module:chalk module:cli-table3 module:configparser module:FilesystemOperators Classes GitHubAuth Methods &lt;async, inner&gt; getAccessTokenDeviceFlow() Get the access token using the device flow Source: authorize.js, line 97 Returns: The access token object Type Object &lt;async, inner&gt; verifyAccessToken(saveToConfig) Verify if the access token is valid and if not get a new one depending on this.env.authType Parameters: Name Type Description saveToConfig Boolean Save to the configuration file, default is true Source: authorize.js, line 149 × Search results Close "},"module-GitHubAuth-GitHubAuth.html":{"id":"module-GitHubAuth-GitHubAuth.html","title":"Class: GitHubAuth","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: GitHubAuth GitHubAuth~ GitHubAuth new GitHubAuth(env, environ, configFile) Parameters: Name Type Description env Object The environment object environ Object The environmentals object configFile String The configuration file Source: authorize.js, line 44 × Search results Close "},"module-GitHubFunctions.html":{"id":"module-GitHubFunctions.html","title":"Module: GitHubFunctions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: GitHubFunctions github.js Version: 1.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: github.js, line 1 Example const gitHubCtl = new GitHubFunctions(accessToken, myOrgName, 'mr-cli-setup') const createRepoResp = await gitHubCtl.createRepository() Requires module:octokit module:axios Methods &lt;inner&gt; createContainers() Creates the top level Study, Company and Interaction containers for all mediumroast.io assets Source: github.js, line 302 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the responses or error messages. Type Array &lt;inner&gt; createRepository() Creates a repository, at the organization level, for keeping track of all mediumroast.io assets Source: github.js, line 152 To Do: Make sure the repo is not public Returns: An array with position 0 being boolean to signify success/failure and position 1 being the created repo or error message. Type Array &lt;async, inner&gt; getActionsBillings() Gets the complete billing status for actions from the GitHub API Source: github.js, line 116 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getAllUsers() Gets all of the users from the GitHub API Source: github.js, line 96 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;inner&gt; getGitHubOrg() If the GitHub organization exists retrieves the detail about it and returns to the caller Source: github.js, line 172 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the org or error message. Type Array &lt;async, inner&gt; getStorageBillings() Gets the complete billing status for actions from the GitHub API Source: github.js, line 134 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getUser() Gets the authenticated user from the GitHub API Source: github.js, line 78 To Do: Add a check to see if the user is a member of the organization Add a check to see if the user has admin rights to the organization Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getWorkflowRuns() Gets all of the workflow runs for the repository Source: github.js, line 188 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the response or error message. Type Array × Search results Close "},"module-baseObjects.html":{"id":"module-baseObjects.html","title":"Module: baseObjects","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: baseObjects gitHubServer.js Version: 2.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: gitHubServer.js, line 1 Example import {Companies, Interactions, Users, Billings} from './api/gitHubServer.js' const companies = new Companies(token, org, processName) const interactions = new Interactions(token, org, processName) const users = new Users(token, org, processName) const billings = new Billings(token, org, processName) const allCompanies = await companies.getAll() const allInteractions = await interactions.getAll() const allUsers = await users.getAll() const allBillings = await billings.getAll() const company = await companies.findByName('myCompany') const interaction = await interactions.findByName('myInteraction') const user = await users.findByName('myUser') Requires module:GitHubFunctions module:crypto module:fs module:path module:fileURLToPath Classes Actions Companies Interactions Storage Studies Users Methods &lt;async, inner&gt; createObj(objs) Create objects in the mediumroast.io application Parameters: Name Type Description objs Array the objects to create in the backend Source: gitHubServer.js, line 134 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; deleteObj(id, endpoint) Delete an object in the mediumroast.io application Parameters: Name Type Description id String the object to be deleted in the mediumroast.io application endpoint String defaults to findbyx and is combined with credential and version info Source: gitHubServer.js, line 204 To Do: implment when available in the backend Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findById(id, endpoint) Find all objects by id from the mediumroast.io application Parameters: Name Type Description id String the id of the object to find endpoint String defaults to findbyx and is combined with credential and version info Deprecated: Yes Source: gitHubServer.js, line 80 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findByName(name) Find all objects by name from the mediumroast.io application Parameters: Name Type Description name String the name of the object to find Source: gitHubServer.js, line 69 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findByX(attribute, value) Find all objects by attribute and value pair from the mediumroast.io application Parameters: Name Type Description attribute String the attribute used to find objects value String the value for the defined attribute Source: gitHubServer.js, line 96 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; getAll() Get all objects from the mediumroast.io application Source: gitHubServer.js, line 59 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; linkObj(objs) Link objects in the mediumroast.io application Parameters: Name Type Description objs Array the objects to link in the backend Source: gitHubServer.js, line 217 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; updateObj(obj, endpoint) Update an object in the mediumroast.io application Parameters: Name Type Description obj Object the object to update in the backend which includes the id and, the attribute and value to be updated endpoint String defaults to findbyx and is combined with credential and version info Source: gitHubServer.js, line 192 Returns: the results from the called function mrRest class Type Array × Search results Close "},"module-baseObjects-Actions.html":{"id":"module-baseObjects-Actions.html","title":"Class: Actions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Actions baseObjects~ Actions A subclass of baseObjects that construct the interaction objects new Actions(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 470 × Search results Close "},"module-baseObjects-Companies.html":{"id":"module-baseObjects-Companies.html","title":"Class: Companies","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Companies baseObjects~ Companies A subclass of baseObjects that construct the company objects new Companies(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 328 × Search results Close "},"module-baseObjects-Interactions.html":{"id":"module-baseObjects-Interactions.html","title":"Class: Interactions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Interactions baseObjects~ Interactions A subclass of baseObjects that construct the interaction objects new Interactions(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 431 × Search results Close "},"module-baseObjects-Storage.html":{"id":"module-baseObjects-Storage.html","title":"Class: Storage","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Storage baseObjects~ Storage A subclass of baseObjects that construct the user objects new Storage(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 305 × Search results Close "},"module-baseObjects-Studies.html":{"id":"module-baseObjects-Studies.html","title":"Class: Studies","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Studies baseObjects~ Studies A subclass of baseObjects that construct the study objects new Studies(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 249 × Search results Close "},"module-baseObjects-Users.html":{"id":"module-baseObjects-Users.html","title":"Class: Users","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Users baseObjects~ Users A subclass of baseObjects that construct the user objects new Users(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 263 × Search results Close "},"tutorial-Company.html":{"id":"tutorial-Company.html","title":"Tutorial: Company Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Company Subcommand Companies Company objects are central to Mediumroast for GitHub. Interactions and in the future Studies rely on Companies to function. After setup is run, via mrcli setup, two companies are present to work with. Additional Companies can be added, updated, or removed; essentially, company is an mrcli sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for mrcli company are described in this document. Notice(s) Some command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Similarity comparisons of Companies requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the company sub-command and exits. Command(s) run mrcli company --help Screenshot with output List company objects Print out one or more Companies to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Companies with specific attributes. List all company objects in a table format This is the default output when running mrcli c or mrcli company which prints a text table to STDOUT. Command(s) run mrcli c mrcli company Screenshot with output List all company objects in JSON format Output a list of company objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli c --output=json mrcli company --output=json Screenshot with output List all company objects and output to a CSV Company data can be output in CSV files to enable consumption in common tools like Microsoft Excel or Apple Numbers. The resulting files will be stored in $HOME/Documents directory as Mr_Companies.csv. Command(s) run mrcli c --output=csv mrcli company --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter company outputs The CLI offers the ability to filter outputs by almost any company attribute. This is manifest by two switches on the company sub-command one specific to finding companies by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a company using any attribute you have to fully provide the attribute's value (i.e., \"Med\" would not match \"Mediumroast, Inc.\", but \"Mediumroast, Inc.\" would). Filter in a company by name To zero in on a specific company using the find by name switch is provided. Command(s) run mrcli c --find_by_name=\"Mediumroast, Inc.\" Screenshot with output Filter a company by attribute Find a specific company by a particular attribute in the example below the switch filters on the attribute company_type. Command(s) run mrcli c --find_by_x='{\"company_type\": \"Public\"}' Screenshot with output Update a company attribute To update a company attribute the --update switch is provided. A properly formatted JSON stanza is supplied to the --update switch that specifies the name of the company to update, the key to update, and finally the value of the key to update. Command(s) run mrcli c --update='{\"name\": \"Atlassian Corp\", \"key\": \"company_type\", \"value\": \"Public\"}' Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/a74cb8cd-f8cb-4a8d-8968-ccf9b875d86b Delete a company Remove a company and associated interactions if in the repository. There is a confirmation prompt which defaults to yes. Note that the exact company name is needed to proceed with a deletion. Command(s) run mrcli c --delete=\"Atlassian Corp\" Screenshot with output Add a company A command line prompt based wizard steps the user through either a semi-automated process or a fully-automated process to define a company. The semi-automated process is typically used for companies that aren't public. While the fully-automated process is typically used for companies that are public. In either case the user is asked to verify the steps taken before the company is committed to the repository. Command(s) run mrcli c --add_wizard Screenshot with output Report on a company Produce a MS Word document report on a company. The report includes a dashboard with a company similarity report, company firmographics, detail on similar companies, and summaries for all interactions associated to the company reported on. The report is stored in the $HOME/Documents directory as &lt;company_name&gt;.docx. Optionally, if the --package switch is used the report is zipped and stored in the $HOME/Documents directory as &lt;company_name&gt;.zip including all of the interactions associated to the company and the set of most and least similar companies. Command(s) run mrcli c --report=\"Atlassian Corp\" mrcli c --report=\"Atlassian Corp\" --package Screenshot of the report dashboard × Search results Close "},"tutorial-Demo.html":{"id":"tutorial-Demo.html","title":"Tutorial: Demo","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Demo Introduction To help users get started with Mediumroast for GitHub, a demo repository has been created in the organization MegaRoast. The demo repository is a clone of our repository, but without actions that automatically generate reports and clean up branches. Further, the demo repository is regularly cloned to reflect the latest changes from our main repository on a weekly basis. So while you can make changes to the demo repository, they will be overwritten on the next clone. This is to ensure that the demo repository is always in sync with the main repository. To gain access to the demo repository, please follow the steps in the main README to install the CLI. From there run mrcli setup and when prompted enter the GitHub organization MegaRoast. Because the demo repository is a clone of our repository the setup will not create a new repository, but instead prompt you for your authentication method and report theme. Once you've completed the setup process you will have access to the demo repository and can begin to explore the capabilities of Mediumroast for GitHub. However, if you've installed the CLI and run mrcli setup you can merely modify your $HOME/.mediumroast/config.ini file to point to the MegaRoast organization. This will enable you to access the demo repository without running mrcli setup again. Example config.ini file With this configuration file by updating the org value to MegaRoast you can access the demo repository without running mrcli setup again. [DEFAULT] company_dns=https://company-dns.mediumroast.io company_logos=https://icon-server.mediumroast.io/allicons.json?url= echarts=https://echart-server.mediumroast.io:11000 nominatim=https://nominatim.openstreetmap.org/search?addressdetails=1&amp;q= working_directory=working report_output_dir=Documents theme=coffee [GitHub] clientId=Iv1.f5c0a4eb1f0606f8 appId=650476 authType=deviceFlow org=&lt;ORGANIZATION&gt; token=&lt;TOKEN&gt; Limitations The following limitations are in place for the demo repository: The demo repository is a clone of the main repository and is updated weekly. The demo repository does not have the actions that automatically generate reports and clean up branches, which means that mrcli actions will not work as expected. The demo repository is a shared read-only repository, meaning you can't push changes to it. If you need to test changes, please use your own repository. × Search results Close "},"tutorial-Interaction.html":{"id":"tutorial-Interaction.html","title":"Tutorial: Interaction Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Interaction Subcommand Interactions After running mrcli setup you can start adding Interactions. An Interaction can be as simple as an email thread between an account team and a customer, a detailed customer interview or even documentation about a competitor. Additional Interactions can be added, updated, or removed; essentially, interaction is an mrcli sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for mrcli interaction are described in this document. Notice(s) Some command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Summarization of Interaction contents and generating proto-requirements plus competitive insights requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the interaction sub-command and exits. Command(s) run mrcli interaction --help Screenshot with output List interaction objects Print out one or more Interaction to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Interactions with specific attributes. List all interaction objects in a table format This is the default output when running mrcli i or mrcli interaction which prints a text table to STDOUT. Command(s) run mrcli i mrcli interaction Screenshot with output List all interaction objects in JSON format Output a list of company objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli i --output=json mrcli interaction --output=json Screenshot with output List all interaction objects and output to a CSV Interaction data can be output in CSV files to enable consumption in common tools like Microsoft Excel or Apple Numbers. The resulting files will be stored in $HOME/Documents directory as Mr_Interactions.csv. Command(s) run mrcli i --output=csv mrcli interaction --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter interaction outputs The CLI offers the ability to filter outputs by almost any interaction attribute. This is manifest by two switches on the interaction sub-command one specific to finding Interactions by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a interaction using any attribute you have to fully provide the attribute's value (i.e., \"The\" would not match \"The 7 Strategic Phases of the Product Planning Process\" , but \"The 7 Strategic Phases of the Product Planning Process\" would). Filter in a interaction by name To zero in on a specific interaction using the find by name switch is provided. Command(s) run mrcli i --find_by_name=\"The 7 Strategic Phases of the Product Planning Process\" Screenshot with output Filter an interaction by attribute Find a specific interaction by a particular attribute in the example below the switch filters on the attribute city. Command(s) run mrcli i --find_by_x='{\"city\": \"Santa Barbara\"}' Screenshot with output Update an interaction attribute To update an interaction attribute the --update switch is provided. A properly formatted JSON stanza is supplied to the --update switch that specifies the name of the interaction to update, the key to update, and finally the value of the key to update. Command(s) run mrcli c --update='{\"name\": \"Atlassian Corp\", \"key\": \"company_type\", \"value\": \"Public\"}' Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/e11256e7-28ca-47d5-b131-58a2036671a6 Delete an interaction Remove a company and associated interactions if in the repository. There is a confirmation prompt which defaults to yes. Note that the exact company name is needed to proceed with a deletion. Command(s) run mrcli i --delete=\"Atlassian Corp\" Screenshot with output Add an interaction A command line prompt based wizard steps the user through a semi-automated process process to define an interaction. The user is asked to verify the steps taken before the interaction(s) is committed to the repository. Command(s) run mrcli i --add_wizard Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/0b28db90-d6ba-4224-a9ae-4c301c2b9614 Report on an interaction Produce a MS Word document report on an interaction. The report includes a dashboard with interaction metadata, interaction abstract, and proto-requirements. The report is stored in the $HOME/Documents directory as &lt;interaction_name&gt;.docx. Optionally, if the --package switch is used the report is zipped and stored in the $HOME/Documents directory as &lt;interaction_name&gt;.zip including the interaction content. Command(s) run mrcli i --report=\"Atlassian Corp\" mrcli i --report=\"Atlassian Corp\" --package Screenshot of the report dashboard × Search results Close "},"tutorial-README.html":{"id":"tutorial-README.html","title":"Tutorial: Administrative Subcommands","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Administrative Subcommands Mediumroast for GitHub CLI (Command Line Interface) The CLI is divided into two sets one for administrative interactions with the system and another for interacting with Mediumroast for GitHub objects like Companies and Interactions. This document covers both the administrative CLI and makes reference to the CLI set for Mediumroast for GitHub objects. Authentication Mediumroast for GitHub uses either Device Flow or a Personal Access Token for authentication. The setup CLI will prompt you to choose the type of authentication and then store the necessary information in the ${HOME}/.mediumroast/config.ini file. If you need to change the authentication configuration you can run mrcli setup to reset the configuration file. Required permissions for the Personal Access Token (PAT) If you create a PAT before the Mediumroast for GitHub repository exists the required scope is for all repositories in your organization. At PAT renewal or if you want to reduce the scope to only the Mediumroast for GitHub repository this can be done later. The Personal Access Token must have the following permissions on all repositories to perform the necessary actions including setup. Actions: read/write Administration: read/write Contents: read/write Metadata: read Pull requests: read/write Workflows: read/write For background and directions on creating a PAT see the GitHub documentation. Administrative CLIs To enable setup and operational reporting of Mediumroast for GitHub several CLIs are available, each is described below. Storage reporting Reports storage consumed by Mediumroast for GitHub. A screenshot showing the usage information and outputs for major functions is included below. Command(s) run mrcli t mrcli storage Screenshot with ouput Actions Reports actions minutes consumed by Mediumroast for GitHub and enables a user to update their repository as new versions of actions are released. A screenshot showing the usage information and outputs for major functions is included below. Command(s) run mrcli actions mrcli a --update Screenshot with ouput User reporting Reports on all users who can access the repository that contains the Mediumroast for GitHub. A screenshot showing the usage information and outputs for major functions is included below, and notice, user names and other personally identifiable information has been redacted from the screenshot below. Command(s) run mrcli u mrcli u --my_user Screenshot with ouput Setup To help users quickly get on board with Mediumroast for GitHub the setup CLI is used. This CLI creates the ${HOME}/.mediumroast/config.ini file, creates the repository including key directories, and creates two initial companies. A screencast video showing the process for setting up the CLI environment and creating two companies is available below. Command(s) run mrcli setup Screencast showing setup process Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/68c08502-4f59-4981-a001-0d9c9bd1d4d2 Deprecated commands The following commands are deprecated, are disabled and will be removed in a future release of the CLI. Billing reporting Is replaced by storage and actions commands in Mediumroast for GitHub. If you run this command it will immediately exit stating it is no longer supported. Command(s) run mrcli b mrcli billing [Company Subcommand] | [Interaction Subcommand | [Studies Subcommand] × Search results Close "},"tutorial-Study.html":{"id":"tutorial-Study.html","title":"Tutorial: Study Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Study Subcommand Studies Study objects are central to Mediumroast for GitHub. Studies rely on Interactions and Companies to function. At this time only the Foundation study is implemented; a future update will add support for user defined studies. To enable the Foundation study run mrcli study --init_foundation, which will create the basic structures of the study in the repository. Each of the major functions for mrcli study are described in this document. Notice(s) Some of the command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Study deletion is not yet implemented and not present. The only update possible to the Foundation study is to reset its status to cause Caffeine to reprocess the study. Populating the Foundation study requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the study sub-command and exits. Command(s) run mrcli study --help Screenshot with output List study objects Print out one or more Studies to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Studies with specific attributes. List all study objects in a table format This is the default output when running mrcli s or mrcli study which prints a text table to STDOUT. Command(s) run mrcli s mrcli study Screenshot with output List all study objects in JSON format Output a list of study objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli s --output=json mrcli study --output=json Screenshot with output List all study objects and output to a CSV Study data can be output in a CSV file to enable consumption in common tools like Microsoft Excel. The resulting file will be stored in $HOME/Documents directory as Mr_Studies.csv. Command(s) run mrcli s --output=csv mrcli study --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter study outputs The CLI offers the ability to filter outputs by almost any study attribute. This is manifest by two switches on the study sub-command one specific to finding studies by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a study using any attribute you have to fully provide the attribute's value (i.e., \"Med\" would not match \"Mediumroast Study\", but \"Mediumroast Study\" would). Filter a study by name To zero in on a specific study using the find by name switch is provided. Command(s) run mrcli s --find_by_name=\"Foundation\" Screenshot with output Filter a study by attribute Find a specific study by a particular attribute in the example below the switch filters on the attribute status. Command(s) run mrcli s --find_by_x='{\"status\": \"0\"}' Screenshot with output Initialize the Foundation study Initializes the Foundation study with core attributes and data. This is the first step in setting up the Foundation study. Command(s) run mrcli s --init_foundation Screenshot with output Report on a study Produce a report on a study. The report provides the most important insights per company in Microsoft Excel format as of the current release. The report is stored in the $HOME/Documents directory as &lt;study_name&gt;.xlsx. Command(s) run mrcli s --report=\"Foundation\" Screenshot of the report Reset the status of a study Reset the status of a study will cause Caffeine to reprocess the study on its next run. This is useful when the study has been updated and needs to be reprocessed. Command(s) run mrcli s --reset_by_name=\"Foundation\" Screenshot with output × Search results Close "}}
+    {"github.js.html":{"id":"github.js.html","title":"Source: github.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: github.js /** * @fileoverview A class that safely wraps RESTful calls to the GitHub API * @license Apache-2.0 * @version 1.0.0 * * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file github.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * * @class GitHubFunctions * @classdesc Core functions needed to interact with the GitHub API for mediumroast.io. * * @requires octokit * @requires axios * * @exports GitHubFunctions * * @example * const gitHubCtl = new GitHubFunctions(accessToken, myOrgName, 'mr-cli-setup') * const createRepoResp = await gitHubCtl.createRepository() */ import { Octokit } from \"octokit\" import axios from \"axios\" class GitHubFunctions { /** * @constructor * @classdesc Core functions needed to interact with the GitHub API for mediumroast.io. * @param {String} token - the GitHub token for the mediumroast.io application * @param {String} org - the GitHub organization for the mediumroast.io application * @param {String} processName - the name of the process that is using the GitHub API * @memberof GitHubFunctions */ constructor (token, org, processName) { this.token = token this.orgName = org this.repoName = `${org}_discovery` this.repoDesc = `A repository for all of the mediumroast.io application assets.` this.octCtl = new Octokit({auth: token}) // NOTE: The lockfile name needs to be more flexible in checking for the lockfile this.lockFileName = `${processName}.lock` this.mainBranchName = 'main' this.objectFiles = { Studies: 'Studies.json', Companies: 'Companies.json', Interactions: 'Interactions.json', Users: null, Billings: null } } /** * @async * @function getSha * @description Gets the SHA of a file in a container on a branch * @param {String} containerName - the name of the container to get the SHA from * @param {String} fileName - the short name of the file to get the SHA from * @param {String} branchName - the name of the branch to get the SHA from * @returns {Array} An array with position 0 being boolean to signify success/failure, position 1 being the response or error message, and position 2 being the SHA. * @memberof GitHubFunctions */ async getSha(containerName, fileName, branchName) { try { const response = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: branchName, path: `${containerName}/${fileName}` }) return [true, {status_code:200, status_msg: `captured sha for [${containerName}/${fileName}]`}, response.data.sha] } catch (err) { return [false, {status_code: 500, status_msg: `unable to capture sha for [${containerName}/${fileName}] due to [${err.message}]`}, err] } } /** * @async * @function getUser * @description Gets the authenticated user from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. * @todo Add a check to see if the user is a member of the organization * @todo Add a check to see if the user has admin rights to the organization */ async getUser() { // using try and catch to handle errors get user info try { const response = await this.octCtl.rest.users.getAuthenticated() return [true, `SUCCESS: able to capture current user info`, response.data] } catch (err) { return [false, `ERROR: unable to capture current user info due to [${err}]`, err.message] } } /** * @async * @function getAllUsers * @description Gets all of the users from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getAllUsers() { // using try and catch to handle errors get info for all users try { const response = await this.octCtl.rest.repos.listCollaborators({ owner: this.orgName, repo: this.repoName, affiliation: 'all' }) return [true, `SUCCESS: able to capture info for all users`, response.data] } catch (err) { return [false, `ERROR: unable to capture info for all users due to [${err}]`, err.message] } } /** * @async * @function getActionsBillings * @description Gets the complete billing status for actions from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getActionsBillings() { // using try and catch to handle errors get info for all billings data try { const response = await this.octCtl.rest.billing.getGithubActionsBillingOrg({ org: this.orgName, }) return [true, `SUCCESS: able to capture info for actions billing`, response.data] } catch (err) { return [false, {status_code: 404, status_msg: `unable to capture info for actions billing due to [${err}]`}, err.message] } } /** * @async * @function getStorageBillings * @description Gets the complete billing status for actions from the GitHub API * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. */ async getStorageBillings() { // using try and catch to handle errors get info for all billings data try { const response = await this.octCtl.rest.billing.getSharedStorageBillingOrg({ org: this.orgName, }) return [true, `SUCCESS: able to capture info for storage billing`, response.data] } catch (err) { return [false, {status_code: 404, status_msg: `unable to capture info for storage billing due to [${err}]`}, err.message] } } /** * @function createRepository * @description Creates a repository, at the organization level, for keeping track of all mediumroast.io assets * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the created repo or error message. * @todo Make sure the repo is not public */ async createRepository () { try { const response = await this.octCtl.rest.repos.createInOrg({ org: this.orgName, name: this.repoName, description: this.repoDesc, private: true }) return [true, response.data] } catch (err) { return[false, err.message] } } /** * @function getGitHubOrg * @description If the GitHub organization exists retrieves the detail about it and returns to the caller * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the org or error message. */ async getGitHubOrg () { try { const response = await this.octCtl.rest.orgs.get({ org: this.orgName }) return[true, response.data] } catch (err) { return[false, err.message] } } /** * @async * @function getWorkflowRuns * @description Gets all of the workflow runs for the repository * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the response or error message. */ async getWorkflowRuns () { let workflows try { workflows = await this.octCtl.rest.actions.listWorkflowRunsForRepo({ owner: this.orgName, repo: this.repoName }) } catch (err) { return [false, {status_code: 500, status_msg: err.message}, err] } const workflowList = [] let totalRunTimeThisMonth = 0 for (const workflow of workflows.data.workflow_runs) { // Get the current month const currentMonth = new Date().getMonth() // Compute the runtime and if the time is less than 60s round it to 1m const runTime = Math.ceil((new Date(workflow.updated_at) - new Date(workflow.created_at)) / 1000 / 60) &lt; 1 ? 1 : Math.ceil((new Date(workflow.updated_at) - new Date(workflow.created_at)) / 1000 / 60) // If the month of the workflow is not the current month, then skip it if (new Date(workflow.updated_at).getMonth() !== currentMonth) { continue } totalRunTimeThisMonth += runTime // Add the workflow to the workflowList workflowList.push({ // Create name where the path is the name of the workflow, but remove the path and the .yml extension name: workflow.path.replace('.github/workflows/', '').replace('.yml', ''), title: workflow.display_title, id: workflow.id, workflowId: workflow.workflow_id, runTimeMinutes: runTime, status: workflow.status, conclusion: workflow.conclusion, event: workflow.event, path: workflow.path, }) } // Sort the worflowList to put the most recent workflows first workflowList.sort((a, b) =&gt; new Date(b.updated_at) - new Date(a.updated_at)) return [true, { status_code: 200, status_msg: `discovered [${workflowList.length}] workflow runs for [${this.repoName}]`,}, workflowList ] } // Create a method using the octokit to get the size of the repository and return the size in MB async getRepoSize() { let repoData = { size: 0, numFiles: 0, name: this.repoName, org: this.orgName, } // Count the number of files in the repository const countFiles = async (path = '') =&gt; { try { const response = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, path: path }) let fileCount = 0; for (const item of response.data) { if (item.type === 'file') { fileCount += 1; } else if (item.type === 'dir') { fileCount += await countFiles(item.path) } } return fileCount } catch (err) { return 0 } } try { repoData.numFiles = await countFiles() } catch (err) { repoData.numFiles = 'Unknown' } const getRepoSize = async () =&gt; { try { const response = await this.octCtl.rest.repos.get({ owner: this.orgName, repo: this.repoName }) const sizeInKB = response.data.size; const sizeInMB = sizeInKB / 1024; return sizeInMB.toFixed(2); // Convert to MB and format to 2 decimal places } catch (err) { return 0 } } try { repoData.size = await getRepoSize() } catch (err) { repoData.size = 'Unknown' } return [true, {status_code: 200, status_msg: `discovered size of [${this.repoName}]`}, repoData] } /** * @function createContainers * @description Creates the top level Study, Company and Interaction containers for all mediumroast.io assets * @returns {Array} An array with position 0 being boolean to signify success/failure and position 1 being the responses or error messages. */ async createContainers (containers = ['Studies', 'Companies', 'Interactions']) { let responses = [] let emptyJson = Buffer.from(JSON.stringify([])).toString('base64') for (const containerName in containers) { try { const response = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: `${containers[containerName]}/${containers[containerName]}.json`, message: `Create container [${containers[containerName]}]`, content: emptyJson, // Create a valid empty JSON file, but this must be Base64 encoded }) responses.push(response) } catch (err) { return[false, err] } } return [true, responses] } /** * @description Creates a new branch from the main branch. * @function createBranchFromMain * @async * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the main branch reference or creating the new branch. * @memberof GitHubFunctions */ async createBranchFromMain() { // Define the branch name const branchName = Date.now().toString() try { // Get the SHA of the latest commit on the main branch const mainBranchRef = await this.octCtl.rest.git.getRef({ owner: this.orgName, repo: this.repoName, ref: `heads/${this.mainBranchName}`, }) // Create a new branch based on the latest commit on the main branch const newBranchResp = await this.octCtl.rest.git.createRef({ owner: this.orgName, repo: this.repoName, ref: `refs/heads/${branchName}`, sha: mainBranchRef.data.object.sha, }) return [true, `SUCCESS: created branch [${branchName}]`, newBranchResp] } catch (error) { return [false, `FAILED: unable to create branch [${branchName}] due to [${error.message}]`, newBranchResp] } } /** * @description Merges a specified branch into the main branch by creating a pull request. * @function mergeBranchToMain * @async * @param {string} branchName - The name of the branch to merge into main. * @param {string} mySha - The SHA of the commit to use as the head of the pull request. * @param {string} [commitDescription='Performed CRUD operation on objects.'] - The description of the commit. * @returns {Promise&lt;Aray&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while creating the branch or the pull request. * @memberof GitHubFunctions */ async mergeBranchToMain(branchName, mySha, commitDescription='Performed CRUD operation on objects.') { try { // Create a new branch // const createBranchResponse = await this.octCtl.rest.git.createRef({ // owner: this.orgName, // repo: this.repoName, // ref: branchName, // sha: mySha, // }) // console.log(createBranchResponse.data) // Create a pull request const createPullRequestResponse = await this.octCtl.rest.pulls.create({ owner: this.orgName, repo: this.repoName, title: commitDescription, head: branchName, base: this.mainBranchName, body: commitDescription, }) // Merge the pull request const mergeResponse = await this.octCtl.rest.pulls.merge({ owner: this.orgName, repo: this.repoName, pull_number: createPullRequestResponse.data.number, commit_title: commitDescription, }) return [true, 'SUCCESS: Pull request created and merged successfully', mergeResponse] } catch (error) { return [false, `FAILED: Pull request not created or merged successfully due to [${error.message}]`, null] } } /** * @description Checks to see if a container is locked. * @function checkForLock * @async * @param {string} containerName - The name of the container to check for a lock. * @returns {Promise&lt;Array&lt;boolean, string&gt;&gt;} A promise that resolves to an array containing a boolean indicating success and a message. * @throws {Error} If an error occurs while getting the latest commit or the contents of the container. * @memberof GitHubFunctions * @todo Add a check to see if the lock file is older than 24 hours and if so delete it. */ async checkForLock(containerName) { // Get the latest commit const latestCommit = await this.octCtl.rest.repos.getCommit({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, }) // Check to see if the lock file exists const mainContents = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: latestCommit.data.sha, path: containerName }) // Can we search for a file with an extension of .lock? // This is due to the fact that there are other processes that may create lock files. const lockExists = mainContents.data.some( item =&gt; item.path === `${containerName}/${this.lockFileName}` ) if (lockExists) { return [true, {status_code: 200, status_msg: `container [${containerName}] is locked with lock file [${this.lockFileName}]`}, lockExists] } else { return [false, {status_code: 404, status_msg: `container [${containerName}] is not locked with lock file [${this.lockFileName}]`}, lockExists] } } /** * @description Locks a container by creating a lock file in the container. * @function lockContainer * @async * @param {string} containerName - The name of the container to lock. * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the latest commit or creating the lock file. * @memberof GitHubFunctions */ async lockContainer(containerName) { // Define the full path to the lockfile const lockFile = `${containerName}/${this.lockFileName}` // Get the latest commit const {data: latestCommit} = await this.octCtl.rest.repos.getCommit({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, }) let lockResponse try { lockResponse = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: lockFile, content: '', branch: this.mainBranchName, message: `Locking container [${containerName}]`, sha: latestCommit.sha }) return [true, `SUCCESS: Locked the container [${containerName}]`, lockResponse] } catch(err) { return [false, `FAILED: Unable to lock the container [${containerName}]`, err] } } /** * @description Unlocks a container by deleting the lock file in the container. * @function unlockContainer * @async * @param {string} containerName - The name of the container to unlock. * @param {string} commitSha - The SHA of the commit to use as the head of the pull request. * @returns {Promise&lt;Array&lt;boolean, string, object&gt;&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @throws {Error} If an error occurs while getting the latest commit or deleting the lock file. * @memberof GitHubFunctions */ async unlockContainer(containerName, commitSha, branchName = this.mainBranchName) { // Define the full path to the lockfile const lockFile = `${containerName}/${this.lockFileName}` const lockExists = await this.checkForLock(containerName) // TODO: Change to try and catch if(lockExists[0]) { // NOTICE: DON'T USE DELETE AS THIS COMPLETELY REMOVES THE REPOSITORY WITHOUT MUCH WARNING const unlockResponse = await this.octCtl.rest.repos.deleteFile({ owner: this.orgName, repo: this.repoName, path: lockFile, branch: branchName, message: `Unlocking container [${containerName}]`, sha: commitSha }) return [true, `SUCCESS: Unlocked the container [${containerName}]`, unlockResponse] } else { return [false, `FAILED: Unable to unlock the container [${containerName}]`, null] } } /** * Read a blob (file) from a container (directory) in a specific branch. * * @param {string} fileName - The name of the blob to read with a complete path to the file (e.g. dirname/filename.ext). * @returns {Array} A list containing a boolean indicating success or failure, a status message, and the blob's raw data (or the error message in case of failure). */ async readBlob(fileName) { // Encode the file name including files with special characters like question marks // Custom encoding function to handle special characters const customEncodeURIComponent = (str) =&gt; { return str.split('').map(char =&gt; { return encodeURIComponent(char).replace(/[!'()*]/g, (c) =&gt; { return '%' + c.charCodeAt(0).toString(16).toUpperCase(); }); }).join(''); } const originalFileNameEncoded = customEncodeURIComponent(fileName) // Try to download the file from the repository using the download URL const downloadFile = async (url) =&gt; { try { const downloadResult = await axios.get(url, { responseType: 'arraybuffer' }) return [true, downloadResult.data] } catch (e) { if (e instanceof TypeError &amp;&amp; (e.message.includes('Request path contains unescaped characters') || e.message.includes('ERR_UNESCAPED_CHARACTERS'))) { // Handle the specific error here // For example, you can re-encode the URL or log the error return [false, 'ERR_UNESCAPED_CHARACTERS'] } return [false, e] } } // Re-encode the download URL const reEncodeDownloadUrl = (url, originalFileName) =&gt; { // Extract the base URL and the file name part let urlParts = url.split('/'); const lastPart = urlParts.pop(); // Get the last part of the URL which contains the file name and possibly query parameters // Remove the last item from the URL parts urlParts.pop() // Find the position of the first question mark that indicates the start of query parameters const altLastPart = lastPart.split('?') const queryParams = altLastPart[altLastPart.length - 1] // Encode the file name part using encodeURIComponent // const encodedFileNamePart = encodeURIComponent(fileNamePart); // Reconstruct the download URL return `${urlParts.join('/')}/${originalFileName}${queryParams ? '?' + queryParams : ''}`; } // Encode the file name and obtain the download URL const encodedFileName = encodeURIComponent(fileName) // Set the object URL const objectUrl = `https://api.github.com/repos/${this.orgName}/${this.repoName}/contents/${encodedFileName}` // Set the headers const headers = { 'Authorization': `token ${this.token}` } // Obtain the download URL const result = await axios.get(objectUrl, { headers }) let downloadUrl = result.data.download_url // Attempt to download the file from the repository let blobData = await downloadFile(downloadUrl) // Check if the file was downloaded successfully if (blobData[0]) { return [ true, { status_code: 200, status_msg: `read object [${fileName}]` }, blobData[1] ] // In this case, the error is due to unescaped characters in the URL and we need to re-encode the file name } else { // Put an if statement here to check if the error is due to unescaped characters by checking the error message if (blobData[1] === 'ERR_UNESCAPED_CHARACTERS') { downloadUrl = reEncodeDownloadUrl(downloadUrl, originalFileNameEncoded) // Try to download the file from the repository again blobData = await downloadFile(downloadUrl) if (blobData[0]) { return [ true, { status_code: 200, status_msg: `read object [${fileName}]` }, blobData[1] ] } } } return [ false, { status_code: 503, status_msg: `unable to read object [${fileName}] due to [${blobData[1]}].` }, blobData[1] ] } // async readBlob(fileName) { // // Encode the file name and obtain the download URL // const encodedFileName = encodeURIComponent(fileName) // // Set the object URL // const objectUrl = `https://api.github.com/repos/${this.orgName}/${this.repoName}/contents/${encodedFileName}` // // Set the headers // const headers = { 'Authorization': `token ${this.token}` } // // Obtain the download URL // const result = await axios.get(objectUrl, { headers }) // console.log(result) // let downloadUrl = result.data.download_url // // try { // const downloadResult = await axios.get(downloadUrl, { responseType: 'arraybuffer' }) // // console.log(downloadResult) // return [true, downloadResult, downloadUrl] // // } catch (e) { // // console.log(e) // // return [false, e, downloadUrl] // // } // } // Create a method using the octokit called deleteBlob to delete a file from the repo async deleteBlob(containerName, fileName, branchName, sha) { // Using the github API delete a file from the container try { const deleteResponse = await this.octCtl.rest.repos.deleteFile({ owner: this.orgName, repo: this.repoName, path: `${containerName}/${fileName}`, branch: branchName, message: `Delete object [${fileName}]`, sha: sha }) // Return the delete response if the delete was successful or an error if not return [true, {status_code: 200, status_msg: `deleted object [${fileName}] from container [${containerName}]`}, deleteResponse] } catch (err) { // Return the error return [false, {status_code: 503, status_msg: `unable to delete object [${fileName}] from container [${containerName}]`}, err] } } // Create a method using the octokit to write a file to the repo async writeBlob(containerName, fileName, blob, branchName, sha) { // Only pull in the file name const fileBits = fileName.split('/') const shortFilename = fileBits[fileBits.length - 1] // Using the github API write a file to the container let octoObj = { owner: this.orgName, repo: this.repoName, path: `${containerName}/${shortFilename}`, message: `Create object [${shortFilename}]`, content: blob, branch: branchName } if(sha) { octoObj.sha = sha } try { const writeResponse = await this.octCtl.rest.repos.createOrUpdateFileContents(octoObj) // Return the write response if the write was successful or an error if not return [true, `SUCCESS: wrote object [${fileName}] to container [${containerName}]`, writeResponse] } catch (err) { // Return the error return [false, `ERROR: unable to write object [${fileName}] to container [${containerName}]`, err] } } /** * @function writeObject * @description Writes an object to a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to write the object to. * @param {object} obj - The object to write to the container. * @param {string} ref - The reference to use when writing the object. * @returns {Promise&lt;string&gt;} A promise that resolves to the response from the GitHub API. * @throws {Error} If an error occurs while writing the object. * @memberof GitHubFunctions * @todo Add a check to see if the container is locked and if so return an error. */ async writeObject(containerName, obj, ref, mySha) { // Using the github API write a file to the container try { const writeResponse = await this.octCtl.rest.repos.createOrUpdateFileContents({ owner: this.orgName, repo: this.repoName, path: `${containerName}/${this.objectFiles[containerName]}`, message: `Create object [${this.objectFiles[containerName]}]`, content: Buffer.from(JSON.stringify(obj)).toString('base64'), branch: ref, sha: mySha }) // Return the write response if the write was successful or an error if not return [true, `SUCCESS: wrote object [${this.objectFiles[containerName]}] to container [${containerName}]`, writeResponse] } catch (err) { // Return the error return [false, `ERROR: unable to write object [${this.objectFiles[containerName]}] to container [${containerName}]`, err] } } /** * @function readObjects * @description Reads objects from a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to read objects from. * @returns {Promise&lt;string&gt;} A promise that resolves to the decoded contents of the objects. * @throws {Error} If an error occurs while getting the content or parsing it. * @memberof GitHubFunctions */ async readObjects(containerName) { // Using the GitHub API get the contents of a file try { let objectContents = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, ref: this.mainBranchName, path: `${containerName}/${this.objectFiles[containerName]}` }) // Decode the contents const decodedContents = Buffer.from(objectContents.data.content, 'base64').toString() // Parse the contents objectContents.mrJson = JSON.parse(decodedContents) // Return the contents return [true, `SUCCESS: read and returned [${containerName}/${this.objectFiles[containerName]}]`, objectContents] } catch (err) { // Return the error return [false, `ERROR: unable to read [${containerName}/${this.objectFiles[containerName]}]`, err] } } /** * @function updateObject * @description Reads an object from a specified container using the GitHub API. * @async * @param {string} containerName - The name of the container to read the object from. * @param {string} objName - The name of the object to update. * @param {string} key - The key of the object to update. * @param {string} value - The value to update the key with. * @param {boolean} [dontWrite=false] - A flag to indicate if the object should be written back to the container or not. * @param {boolean} [system=false] - A flag to indicate if the update is a system call or not. * @param {Array} [whiteList=[]] - A list of keys that are allowed to be updated. * @returns {Promise&lt;Array&gt;} A promise that resolves to the decoded contents of the object. * @memberof GitHubFunctions * @todo As deleteObject progresses look to see if we can improve here too */ async updateObject(containerName, objName, key, value, dontWrite=false, system=false, whiteList=[]) { // console.log(`Updating object [${objName}] in container [${containerName}] with key [${key}] and value [${value}]`) // Check to see if this is a system call or not if(!system) { // Since this is not a system call check to see if the key is in the white list if(!whiteList.includes(key)) { return [ false, { status_code: 403, status_msg: `Updating the key [${key}] is not supported.` }, null ] } } // Using the method above read the objects const readResponse = await this.readObjects(containerName) // Check to see if the read was successful if(!readResponse[0]) { return [ false, {status_code: 500, status_msg: `Unable to read source objects from GitHub.`}, readResponse ] } // Catch the container if needed let repoMetadata = { containers: {}, branch: {} } // If dontWrite is true then don't catch the container let caught = {} if(!dontWrite) { repoMetadata.containers[containerName] = {} caught = await this.catchContainer(repoMetadata) } // Loop through the objects, find and update the objects matching the name for (const obj in readResponse[2].mrJson) { if(readResponse[2].mrJson[obj].name === objName) { readResponse[2].mrJson[obj][key] = value // Update the modified date of the object const now = new Date() readResponse[2].mrJson[obj].modification_date = now.toISOString() } } // If this flag is set merely return the modified object(s) to the caller if (dontWrite) { return [ true, { status_code: 200, status_msg: `Merged updates object(s) with [${containerName}] objects.` }, readResponse[2].mrJson ] } // Call the method above to write the object const writeResponse = await this.writeObject( containerName, readResponse[2].mrJson, caught[2].branch.name, caught[2].containers[containerName].objectSha) // Check to see if the write was successful and return the error if not if(!writeResponse[0]) { return [ false, {status_code: 503, status_msg: `Unable to write the objects.`}, writeResponse ] } // Release the container const released = await this.releaseContainer(caught[2]) if(!released[0]) { return [ false, { status_code: 503, status_msg: `Cannot release the container please check [${containerName}] in GitHub.` }, released ] } // Finally return success with the results of the release return [ true, { status_code: 200, status_msg: `Updated [${containerName}] object of the name [${objName}] with [${key} = ${value}].` }, released ] } /** * @function deleteObject * @description Deletes an object from a specified container using the GitHub API. * @async * @param {string} objName - The name of the object to delete. * @param {object} source - The source object that contains the from and to containers. * @returns {Promise&lt;Array&gt;} A promise that resolves to the decoded contents of the object. * @memberof GitHubFunctions */ async deleteObject(objName, source, repoMetadata=null, catchIt=true) { // NOTE: source has a weakness we will have to remedy later, notably from can be Studies and Companies // source = { // from: 'Interactions', // to: ['Companies'] // } // Create an object that maps the from object type to the to object type fields to be updated const fieldMap = { Interactions: { Companies: 'linked_interactions', // Studies: 'linked_interactions' }, Companies: { Interactions: 'linked_companies', // Studies: 'linked_companies' }, Studies: { Interactions: 'linked_studies', Companies: 'linked_studies' } } // Catch the container if needed if(catchIt) { repoMetadata = { containers: {}, branch: {} } // Catch the container(s) repoMetadata.containers[source.from] = {} repoMetadata.containers[source.to[0]] = {} let caught = await this.catchContainer(repoMetadata) repoMetadata = caught[2] } // Loop through the from objects, find and remove the objects matching the name for (const obj in repoMetadata.containers[source.from].objects) { if(repoMetadata.containers[source.from].objects[obj].name === objName) { // If from is Interactions then we need to delete the actual file from the repo based on objName if(source.from === 'Interactions') { // Obtain the sha of the object to delete by obtaining the file name from the url attribute of the Interaction const fileName = repoMetadata.containers[source.from].objects[obj].url // Obtain the sha for fileName using octokit const { data } = await this.octCtl.rest.repos.getContent({ owner: this.orgName, repo: this.repoName, path: fileName }) // Remove the path from the file name const fileBits = fileName.split('/') const shortFilename = fileBits[fileBits.length - 1] // Call the method above to delete the object using data.sha const deleteResponse = await this.deleteBlob( source.from, shortFilename, repoMetadata.branch.name, data.sha ) // Check to see if the delete was successful and return the error if not if(!deleteResponse[0]) { return [ false, {status_code: 503, status_msg: `Unable to delete the [${source.from}] object [${objName}].`}, deleteResponse ] } } // Remove the object from the array repoMetadata.containers[source.from].objects.splice(obj, 1) } } // Loop through the to objects, find and remove objName from the linked objects and update the modification date for (const obj in repoMetadata.containers[source.to[0]].objects) { if(objName in repoMetadata.containers[source.to[0]].objects[obj][fieldMap[source.from][source.to[0]]]) { // Delete the object from the linked objects object delete repoMetadata.containers[source.to[0]].objects[obj][fieldMap[source.from][source.to[0]]][objName] // Update the modification date of the object const now = new Date() repoMetadata.containers[source.to[0]].objects[obj].modification_date = now.toISOString() } } // Call getSha to get the sha of the from object const fromSha = await this.getSha(source.from, this.objectFiles[source.from], repoMetadata.branch.name) // Check to see if the sha was captured and return the error if not if(!fromSha[0]) { return [ false, {status_code: 503, status_msg: `Unable to capture the [${source.from}] sha.`}, fromSha ] } // Call the method above to write the from objects const writeResponse = await this.writeObject( source.from, repoMetadata.containers[source.from].objects, repoMetadata.branch.name, fromSha[2]) // Check to see if the write was successful and return the error if not if(!writeResponse[0]) { console.log(writeResponse) return [ false, {status_code: 503, status_msg: `Unable to write the [${source.from}] objects.`}, writeResponse ] } // Call getSha to get the sha of the to object const toSha = await this.getSha(source.to[0], this.objectFiles[source.to[0]], repoMetadata.branch.name) // Check to see if the sha was captured and return the error if not if(!toSha[0]) { return [ false, {status_code: 503, status_msg: `Unable to capture the [${source.to[0]}] sha.`}, toSha ] } // Call the method above to write the to objects const writeResponse2 = await this.writeObject( source.to, repoMetadata.containers[source.to[0]].objects, repoMetadata.branch.name, toSha[2]) // Check to see if the write was successful and return the error if not if(!writeResponse2[0]) { return [ false, {status_code: 503, status_msg: `Unable to write the [${source.to}] objects.`}, writeResponse2 ] } // Release the container if(catchIt){ const released = await this.releaseContainer(repoMetadata) if(!released[0]) { return [ false, { status_code: 503, status_msg: `Cannot release the container please check [${source.from}] in GitHub.` }, released ] } // Finally return success with the results of the release return [ true, { status_code: 200, status_msg: `Deleted [${source.from}] object of the name [${objName}], and links in associated objects.` }, released ] } else { // Return success with the write reponses return [ true, { status_code: 200, status_msg: `Deleted [${source.from}] object of the name [${objName}], and links in associated objects.` }, [writeResponse, writeResponse2] ] } } /** * @function catchContainer * @description Catches a container by locking it, creating a new branch, reading the objects, and returning the metadata. * @param {Object} repoMetadata - The metadata object that contains the containers and branch information. * @returns {Promise&lt;Array&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the metadata object. * @memberof GitHubFunctions */ async catchContainer(repoMetadata) { // Check to see if the containers are locked for (const container in repoMetadata.containers) { // Call the method above to check for a lock const lockExists = await this.checkForLock(container) // If the lock exists return an error if(lockExists[0]) { return [false, {status_code: 503, status_msg:`the container [${container}] is locked unable and cannot perform creates, updates or deletes on objects.`}, lockExists] } } // Lock the containers for (const container in repoMetadata.containers) { // Call the method above to lock the container const locked = await this.lockContainer(container) // Check to see if the container was locked and return the error if not if(!locked[0]) { return [false, {status_code: 503, status_msg: `unable to lock [${container}] and cannot perform creates, updates or deletes on objects.`}, locked] } // Save the lock sha repoMetadata.containers[container].lockSha = locked[2].data.content.sha } // Call the method above createBranchFromMain to create a new branch const branchCreated = await this.createBranchFromMain() // Check to see if the branch was created if(!branchCreated[0]) { return [false, {status_code: 503, status_msg: `unable to create new branch`}, branchCreated] } // Save the branch sha into containers as a separate object repoMetadata.branch = { name: branchCreated[2].data.ref, sha: branchCreated[2].data.object.sha } // Read the objects from the containers for (const container in repoMetadata.containers) { // Call the method above to read the objects const readResponse = await this.readObjects(container) // Check to see if the read was successful if(!readResponse[0]) { return [false, {status_code: 503, status_msg: `Unable to read the source objects [${container}/${this.objectFiles[container]}].`}, readResponse] } // Save the object sha into containers as a separate object repoMetadata.containers[container].objectSha = readResponse[2].data.sha // Save the objects into containers as a separate object repoMetadata.containers[container].objects = readResponse[2].mrJson } return [true,{status_code: 200, status_msg: `${repoMetadata.containers.length} containers are ready for use.`}, repoMetadata] } /** * @function releaseContainer * @description Releases a container by unlocking it and merging the branch to main. * @param {Object} repoMetadata - The metadata object that contains the containers and branch information. * @returns {Promise&lt;Array&gt;} A promise that resolves to an array containing a boolean indicating success, a success message, and the response from the GitHub API. * @memberof GitHubFunctions */ async releaseContainer(repoMetadata) { // Merge the branch to main const mergeResponse = await this.mergeBranchToMain(repoMetadata.branch.name, repoMetadata.branch.sha) // Check to see if the merge was successful and return the error if not if(!mergeResponse[0]) { return [false,{status_code:503, status_msg: `Unable to merge the branch to main.`}, mergeResponse] } // Unlock the containers by looping through them for (const container in repoMetadata.containers) { // Call the method above to unlock the container const branchUnlocked = await this.unlockContainer( container, repoMetadata.containers[container].lockSha, repoMetadata.branch.name) if(!branchUnlocked[0]) { return [false, {status_code: 503, status_msg: `Unable to unlock the container, objects may have been written please check [${container}] for objects and the lock file.`}, branchUnlocked] } // Unlock main const mainUnlocked = await this.unlockContainer( container, repoMetadata.containers[container].lockSha ) if(!mainUnlocked[0]) { return [false, {status_code: 503, status_msg: `Unable to unlock the container, objects may have been written please check [${container}] for objects and the lock file.`}, mainUnlocked] } } // Return success with number of objects written return [true, {status_code: 200, status_msg: `Released [${repoMetadata.containers.length}] containers.`}, null] } } export default GitHubFunctions × Search results Close "},"authorize.js.html":{"id":"authorize.js.html","title":"Source: authorize.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: authorize.js /** * @fileoverview This file contains the code to authorize the user to the GitHub API * @license Apache-2.0 * @version 2.0.0 * * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file authorize.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * * @class GitHubAuth * @classdesc This class is used to authorize the user to the GitHub API * * @requires axios * @requires open * @requires octoDevAuth * @requires chalk * @requires cli-table3 * @requires configparser * @requires FilesystemOperators * * @exports GitHubAuth * * @example * import {GitHubAuth} from './api/authorize.js' * const github = new GitHubAuth(env, environ, configFile) * const githubToken = github.verifyAccessToken() * */ import open from \"open\" import * as octoDevAuth from '@octokit/auth-oauth-device' import chalk from \"chalk\" import Table from 'cli-table3' import FilesystemOperators from '../cli/filesystem.js' class GitHubAuth { /** * @constructor * @param {Object} env - The environment object * @param {Object} environ - The environmentals object * @param {String} configFile - The configuration file */ constructor (env, environ, configFile, configExists) { this.env = env this.clientType = 'github-app' this.configFile = configFile this.configExists = configExists this.filesystem = new FilesystemOperators() this.environ = environ // Use ternary operator to determine if the config file exists and if it does read it else set it to null this.config = configExists ? environ.readConfig(configFile) : null } verifyGitHubSection () { if (!this.config) { return false } return this.config.hasSection('GitHub') } _getFromConfig (section, option) { const hasOption = this.config.hasKey(section, option) if (hasOption) { return this.config.get(section, option) } else { return null } } getAccessTokenFromConfig () { return this._getFromConfig('GitHub', 'token') } getAuthTypeFromConfig () { return this._getFromConfig('GitHub', 'authType') } async checkTokenExpiration(token) { const response = await fetch('https://api.github.com/user', { method: 'GET', headers: { 'Authorization': `token ${token}`, 'Accept': 'application/vnd.github.v3+json' } }) if (!response.ok) { return [false, {status_code: 500, status_msg: response.statusText}, null] } const data = await response.json() return [true, {status_code: 200, status_msg: response.statusText}, data] } /** * @async * @function getAccessTokenDeviceFlow * @description Get the access token using the device flow * @returns {Object} The access token object */ async getAccessTokenDeviceFlow() { // Set the clientId depending on if the config file exists const clientId = this.configExists ? this.env.clientId : this.env.GitHub.clientId // Construct the oAuth device flow object which starts the browser let deviceCode // Provide a place for the device code to be captured const deviceauth = octoDevAuth.createOAuthDeviceAuth({ clientType: this.clientType, clientId: clientId, onVerification(verifier) { deviceCode = verifier.device_code // Print the verification artifact to the console console.log( chalk.blue.bold(`If supported opening your browser to the Authorization website.\\nIf your browser doesn't open, please copy and paste the Authorization website URL into your browser's address bar.\\n`) ) const authWebsitePrefix = `Authorization website:` const authCodePrefix = `Authorization code:` const authWebsite = chalk.bold.red(verifier.verification_uri) const authCode = chalk.bold.red(verifier.user_code) const table = new Table({ rows: [ [authWebsitePrefix, authWebsite], [authCodePrefix, authCode] ] }) // Get the table as a string const tableString = table.toString() // Check to see if the table string is empty if (tableString !== '') { // Print the table to the console, since not empty console.log(tableString) } else { // Print strings to the console, since empty console.log(`\\t${authWebsitePrefix} ${authWebsite}`) console.log(`\\t${authCodePrefix} ${authCode}`) } console.log(`\\nCopy and paste the Authorization code into correct field on the Authorization website. Once authorized setup will continue.\\n`) open(verifier.verification_uri) } }) // Call GitHub to obtain the token let accessToken = await deviceauth({type: 'oauth'}) accessToken.deviceCode = deviceCode return accessToken } /** * @async * @function verifyAccessToken * @description Verify if the access token is valid and if not get a new one depending on this.env.authType * @param {Boolean} saveToConfig - Save to the configuration file, default is true */ async verifyAccessToken (saveToConfig=true) { if (this.configExists) { // Get key variables from the config file const hasGitHubSection = this.verifyGitHubSection() // If the GitHub section is not available, then the token is not available, return false. // This is only to be used when called from a function that intendes to setup the configuration file, but // just in case this condition occurs we want to return clearly to the caller. if (!hasGitHubSection) { return [false, {status_code: 500, status_msg: 'The GitHub section is not available in the configuration file'}, null] } } // Get the access token and authType from the config file since the section is available let accessToken // If the configuration exists then we can obtain the token and authType from the config file, but if // the configuration is not present and the intention is to use PAT this code won't be executed. Therefore, // prompting the user for the PAT, verifyin the PAT, and saving the PAT to the config file will be done in the // caller. However, if the intention is to use deviceFlow then we can support that here and return the token to the // caller which will then save the token and the authType to the config file. let authType = 'deviceFlow' if (this.configExists) { accessToken = this.getAccessTokenFromConfig() authType = this.getAuthTypeFromConfig() } // Check to see if the token is valid but if the config isn't present then we can't check the token const validToken = this.configExists ? await this.checkTokenExpiration(accessToken) : [false, {status_code: 500, status_msg: 'The configuration file isn\\'t present'}, null] if (validToken[0] &amp;&amp; this.configExists) { return [ true, {status_code: 200, status_msg: validToken[1].status_msg}, {token: accessToken, authType: authType} ] // If the token is not valid, then we need to return to the caller (PAT) or get a new token (deviceFlow) } else { // Case for a Personal Access Token if (authType === 'pat') { // Return the error message to the caller return [ false, {status_code: 500, status_msg: `The Personal Access Token appears to be invalid and was rejected with an error message [${validToken[1].status_msg}].\\n\\tPlease obtain a new PAT and update the GitHub token setting in the configuration file [${this.configFile}].`}, null ] // Case for the device flow } else if (authType === 'deviceFlow') { // Get the new access token accessToken = await this.getAccessTokenDeviceFlow() // Update the config if the config file exists and if saveToConfig is true if (this.configExists &amp;&amp; this.config &amp;&amp; this.saveToConfig) { let tmpConfig = this.environ.updateConfigSetting(this.config, 'GitHub', 'token', accessToken.token) tmpConfig = this.environ.updateConfigSetting(tmpConfig[1], 'GitHub', 'authType', authType) tmpConfig = this.environ.updateConfigSetting(tmpConfig[1], 'GitHub', 'deviceCode', accessToken.deviceCode) // Save the config file if needed this.config = tmpConfig[1] if (saveToConfig) { await this.config.write(this.configFile) } } return [ true, {status_code: 200, status_msg: `The access token has been successfully updated and saved to the configuration file [${this.configFile}]`}, {token: accessToken.token, authType: authType, deviceCode: accessToken.deviceCode} ] } } } decodeJWT (token) { if(token !== null || token !== undefined){ const base64String = token.split('.')[1] const decodedValue = JSON.parse( Buffer.from( base64String, 'base64') .toString('ascii') ) return decodedValue } return null } } export {GitHubAuth} × Search results Close "},"gitHubServer.js.html":{"id":"gitHubServer.js.html","title":"Source: gitHubServer.js","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Source: gitHubServer.js /** * A class for authenticating and talking to the mediumroast.io backend * @author Michael Hay &lt;michael.hay@mediumroast.io&gt; * @file gitHubServer.js * @copyright 2024 Mediumroast, Inc. All rights reserved. * @license Apache-2.0 * @version 2.0.0 * * @class baseObjects * @classdesc An implementation for interacting with the GitHub backend. * * @requires GitHubFunctions * @requires crypto * @requires fs * @requires path * @requires fileURLToPath * * @exports {Studies, Companies, Interactions, Users, Storage, Actions} * * @example * import {Companies, Interactions, Users, Billings} from './api/gitHubServer.js' * const companies = new Companies(token, org, processName) * const interactions = new Interactions(token, org, processName) * const users = new Users(token, org, processName) * const billings = new Billings(token, org, processName) * * const allCompanies = await companies.getAll() * const allInteractions = await interactions.getAll() * const allUsers = await users.getAll() * const allBillings = await billings.getAll() * * const company = await companies.findByName('myCompany') * const interaction = await interactions.findByName('myInteraction') * const user = await users.findByName('myUser') * */ // Import required modules import GitHubFunctions from './github.js' import { createHash } from 'crypto' import fs from 'fs' import * as path from 'path' import { fileURLToPath } from 'url' class baseObjects { constructor(token, org, processName, objType) { this.serverCtl = new GitHubFunctions(token, org, processName) this.objType = objType this.objectFiles = { Studies: 'Studies.json', Companies: 'Companies.json', Interactions: 'Interactions.json', Users: null } } /** * @async * @function getAll * @description Get all objects from the mediumroast.io application * @returns {Array} the results from the called function mrRest class */ async getAll() { return await this.serverCtl.readObjects(this.objType) } /** * @async * @function findByName * @description Find all objects by name from the mediumroast.io application * @param {String} name - the name of the object to find * @returns {Array} the results from the called function mrRest class */ async findByName(name) { return this.findByX('name', name) } /** * @async * @function findById * @description Find all objects by id from the mediumroast.io application * @param {String} id - the id of the object to find * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class * @deprecated */ async findById(id) { return false const fullEndpoint = '/' + this.apiVersion + '/' + this.objType + '/' + endpoint const my_obj = {findByX: \"id\", xEquals: id} return this.rest.postObj(fullEndpoint, my_obj) } /** * @async * @function findByX * @description Find all objects by attribute and value pair from the mediumroast.io application * @param {String} attribute - the attribute used to find objects * @param {String} value - the value for the defined attribute * @returns {Array} the results from the called function mrRest class */ async findByX(attribute, value, allObjects=null) { if(attribute === 'name') { value = value.toLowerCase() } // console.log(`Searching for ${this.objType} where ${attribute} = ${value}`) let myObjects = [] if(allObjects === null) { const allObjectsResp = await this.serverCtl.readObjects(this.objType) allObjects = allObjectsResp[2].mrJson } // If the length of allObjects is 0 then return an error // This will occur when there are no objects of the type in the backend if(allObjects.length === 0) { return [false, {status_code: 404, status_msg: `no ${this.objType} found`}, null] } for(const obj in allObjects) { let currentObject attribute == 'name' ? currentObject = allObjects[obj][attribute].toLowerCase() : currentObject = allObjects[obj][attribute] if(currentObject === value) { myObjects.push(allObjects[obj]) } } if (myObjects.length === 0) { return [false, {status_code: 404, status_msg: `no ${this.objType} found where ${attribute} = ${value}`}, null] } else { return [true, `SUCCESS: found all objects where ${attribute} = ${value}`, myObjects] } } /** * @async * @function createObj * @description Create objects in the mediumroast.io application * @param {Array} objs - the objects to create in the backend * @returns {Array} the results from the called function mrRest class */ // async createObj1(objs) { // return await this.serverCtl.createObjects(this.objType, objs) // } async createObj(objs) { // Create the repoMetadata object let repoMetadata = { containers: { [this.objType]: {} }, branch: {} } // Catch the container const caught = await this.serverCtl.catchContainer(repoMetadata) // If the container is locked then return the caught object if(!caught[0]) { return caught } // Get the sha for the current branch/object const sha = await this.serverCtl.getSha( this.objType, this.objectFiles[this.objType], repoMetadata.branch.name ) // If the sha is not found then return the sha object if(!sha[0]) { return sha } // Append the new object to the existing objects const mergedObjects = [...caught[2].containers[this.objType].objects, ...objs] // Write the new objects to the container const writeResp = await this.serverCtl.writeObject( this.objType, mergedObjects, repoMetadata.branch.name, sha[2] ) // If the write fails then return the writeResp if(!writeResp[0]) { return writeResp } // Release the container const released = await this.serverCtl.releaseContainer(caught[2]) // If the release fails then return the released object if(!released[0]) { return released } // Return a success message return [true, {status_code: 200, status_msg: `created [${objs.length}] ${this.objType}`}, null] } /** * @async * @function updateObj * @description Update an object in the mediumroast.io application * @param {Object} obj - the object to update in the backend which includes the id and, the attribute and value to be updated * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class */ async updateObj(objName, key, value, dontWrite, system, whiteList) { return await this.serverCtl.updateObject(this.objType, objName, key, value, dontWrite, system, whiteList) } /** * @async * @function deleteObj * @description Delete an object in the mediumroast.io application * @param {String} id - the object to be deleted in the mediumroast.io application * @param {String} endpoint - defaults to findbyx and is combined with credential and version info * @returns {Array} the results from the called function mrRest class * @todo implment when available in the backend */ async deleteObj(objName, source, repoMetadata=null, catchIt=true) { return await this.serverCtl.deleteObject(objName, source, repoMetadata, catchIt) } /** * @async * @function linkObj * @description Link objects in the mediumroast.io application * @param {Array} objs - the objects to link in the backend * @returns {Array} the results from the called function mrRest class */ linkObj(objs) { let linkedObjs = {} for(const obj in objs) { const objName = objs[obj].name const sha256Hash = createHash('sha256').update(objName).digest('hex') linkedObjs[objName] = sha256Hash } return linkedObjs } // Create a function that checks for a locked container using the serverCtl.checkForLock() function async checkForLock() { return await this.serverCtl.checkForLock(this.objType) } } class Studies extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the study objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Studies') } } // Create a subclass called Users that inherits from baseObjects class Users extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the user objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Users') } // Create a new method for getAll that is specific to the Users class using getUser() in github.js async getAll() { return await this.serverCtl.getAllUsers() } // Create a new method for findMyself that is specific to the Users class using getUser() in github.js async getMyself() { return await this.serverCtl.getUser() } async findByName(name) { return this.findByX('login', name) } async findByX(attribute, value) { let myUsers = [] const allUsersResp = await this.getAll() const allUsers = allUsersResp[2] for(const user in allUsers) { if(allUsers[user][attribute] === value) { myUsers.push(allUsers[user]) } } return [true, `SUCCESS: found all users where ${attribute} = ${value}`, myUsers] } } // Create a subclass called Users that inherits from baseObjects class Storage extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the user objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Billings') } // Create a new method for getAll that is specific to the Billings class using getBillings() in github.js async getAll() { return await this.serverCtl.getRepoSize() } // Create a new method of to get the storage billing status only async getStorageBilling() { return await this.serverCtl.getStorageBillings() } } class Companies extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the company objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Companies') } async updateObj(objToUpdate, dontWrite=false, system=false) { // Destructure objToUpdate const { name, key, value } = objToUpdate // Define the attributes that can be updated by the user const whiteList = [ 'description', 'company_type', 'url', 'role', 'wikipedia_url', 'status', 'logo_url', 'region', 'country', 'city', 'state_province', 'zip_postal', 'street_address', 'latitude', 'longitude','phone', 'google_maps_url', 'google_news_url', 'google_finance_url','google_patents_url', 'cik', 'stock_symbol', 'stock_exchange', 'recent_10k_url', 'recent_10q_url', 'firmographic_url', 'filings_url', 'owner_tranasactions', 'industry', 'industry_code', 'industry_group_code', 'industry_group_description', 'major_group_code','major_group_description' ] return await super.updateObj(name, key, value, dontWrite, system, whiteList) } async deleteObj(objName, allowOrphans=false) { let source = { from: 'Companies', to: ['Interactions'] } // If allowOrphans is true then use the baseObjects deleteObj if(allowOrphans){ return await super.deleteObj(objName, source) } // Catch the Companies and Interaction containers // Assign repoMetadata to capture Companies nad Studies let repoMetadata = { containers: { Companies: {}, Interactions: {} }, branch: {} } const caught = await this.serverCtl.catchContainer(repoMetadata) // Use findByX to get all linkedInteractions // NOTE: This has to be done here because the company has been deleted in the next step const getCompanyObject = await this.findByX('name', objName, caught[2].containers.Companies.objects) if(!getCompanyObject[0]) { return getCompanyObject } const linkedInteractions = getCompanyObject[2][0].linked_interactions // Delete the company // Use deleteObj to delete the company const deleteCompanyObjResp = await this.serverCtl.deleteObject( objName, source, caught[2], false ) if(!deleteCompanyObjResp[0]) { return deleteCompanyObjResp } // Delete all linkedInteractions // Update source to be from the perspective of the Interactions source = { from: 'Interactions', to: ['Companies'] } // Use deleteObect to delete all linkedInteractions for(const interaction in linkedInteractions) { const deleteInteractionObjResp = await this.serverCtl.deleteObject( interaction, source, caught[2], false ) if(!deleteInteractionObjResp[0]) { return deleteInteractionObjResp } } // Release the container const relased = await this.serverCtl.releaseContainer(caught[2]) if(!relased[0]) { return relased } // Return the response return [true, {status_code: 200, status_msg: `deleted company [${objName}] and all linked interactions`}, null] } } class Interactions extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the interaction objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Interactions') } async updateObj(objToUpdate, dontWrite=false, system=false) { // Destructure objToUpdate const { name, key, value } = objToUpdate // Define the attributes that can be updated by the user const whiteList = [ 'status', 'content_type', 'file_size', 'reading_time', 'word_count', 'page_count', 'description', 'abstract', 'region', 'country', 'city', 'state_province', 'zip_postal', 'street_address', 'latitude', 'longitude', 'public', 'groups' ] return await super.updateObj(name, key, value, dontWrite, system, whiteList) } async deleteObj(objName) { const source = { from: 'Interactions', to: ['Companies'] } return await super.deleteObj(objName, source) } async findByHash(hash) { return this.findByX('file_hash', hash) } } class Actions extends baseObjects { /** * @constructor * @classdesc A subclass of baseObjects that construct the interaction objects * @param {String} token - the token for the GitHub application * @param {String} org - the organization for the GitHub application * @param {String} processName - the process name for the GitHub application */ constructor (token, org, processName) { super(token, org, processName, 'Actions') } _generateManifest(dir, filelist) { // Define which content to skip const skipContent = ['.DS_Store', 'node_modules'] const __filename = fileURLToPath(import.meta.url) const __dirname = path.dirname(__filename); // Use regex to prune everything after mediumroast_js/ const basePath = __dirname.match(/.*mediumroast_js\\//)[0]; // Append cli/actions to the base path dir = dir || path.resolve(path.join(basePath, 'cli/actions')) const files = fs.readdirSync(dir) filelist = filelist || []; files.forEach((file) =&gt; { // Skip unneeded directories if (skipContent.includes(file)) { return } const fullPath = path.join(dir, file); if (fs.statSync(fullPath).isDirectory()) { filelist = this._generateManifest(path.join(dir, file), filelist) } else { // Substitute .github for the first part of the path, in the variable dir if (dir.includes('./')) { dir = dir.replace('./', '') } // This will be the repository name let dotGitHub = dir.replace(/.*(workflows|actions)/, '.github/$1') filelist.push({ fileName: file, containerName: dotGitHub, srcURL: new URL(`file://${fullPath}`) }) } }) return filelist } async updateActions() { // Discover the manifest const actionsManifest = this._generateManifest() // Capture detailed install status let installStatus = { successCount: 0, failCount: 0, success: [], fail: [], total: actionsManifest.length } for (const action of actionsManifest) { // Loop through the actionsManifest and install each action let status = false let blobData try { // Read in the blob file blobData = fs.readFileSync(action.srcURL, 'base64') status = true } catch (err) { // console.log(`Unable to read file [${action.fileName}] because: ${err}`) return [false,{status_code: 500, status_msg: `Unable to read file [${action.fileName}] because: ${err}`}, installStatus] } if(status) { // Get the sha for the current branch/object const sha = await this.serverCtl.getSha( action.containerName, action.fileName, 'main' ) // Keep action update failures // Install the action const installResp = await this.serverCtl.writeBlob( action.containerName, action.fileName, blobData, 'main', sha[2] ) if(installResp[0]){ installStatus.success.push({fileName: action.fileName, containerName: action.catchContainer, installMsg: installResp[1].status_msg}) installStatus.successCount++ } else { installStatus.fail.push({fileName: action.fileName, containerName: action.catchContainer, installMsg: installResp[1].status_msg}) installStatus.failCount++ } } else { return [false, {status_code: 503,status_msg:`Failed to read item [${action.fileName}]`}, installStatus] } } return [true, {status_code: 200, status_msg:`All actions installed`}, installStatus] } // Create a new method of to get the actions billing status only async getActionsBilling() { return await this.serverCtl.getActionsBillings() } async getAll() { return await this.serverCtl.getWorkflowRuns() } } // Export classes for consumers export { Studies, Companies, Interactions, Users, Storage, Actions } × Search results Close "},"modules.list.html":{"id":"modules.list.html","title":"Modules","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Modules × Search results Close "},"classes.list.html":{"id":"classes.list.html","title":"Classes","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Classes × Search results Close "},"tutorials.list.html":{"id":"tutorials.list.html","title":"Tutorials","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Tutorials × Search results Close "},"index.html":{"id":"index.html","title":"Index","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Welcome Mediumroast for GitHub Products organizations must build evidence based product plans from competitive and customer interactions. Using Artificial Intelligence and Machine Learning, Mediumroast for GitHub realizes an active product planning repository for Product Managers and Developers everyone can see, use, and reference. The repository is built on GitHub and is accessible via Command Line Interface (CLI) and a Software Development Kit (SDK). This CLI and SDK are built on Node.js and is available for Linux and MacOS operating systems. A GitHub Page Version of this content is also available, but the screencasts and videos won't display. Installation and configuration Mediumroast for GitHub includes a GitHub Application, a Command Line Interface, and a Software Development Kit. The following steps show you how to install the App and the CLI with SDK. Preinstallation requirements A GitHub organization Permissions in your GitHub organization to install a GitHub application. Access to a command line terminal on Linux or MacOS. Node.js installed, ideally globally for all users. NPM installed, ideally globally for all users. Step 1 - Install the GitHub App Browse to the Mediumroast for GitHub GitHub Application and: Click install, Choose the location for the installation, usually your organization, Confirm the requested permissions, and Browse to your organization's Settings &gt; Third-Party Access &gt; GitHub Apps and confirm that Mediumroast for GitHub is installed. Step 2 - Install mediumroast_js This package mediumroast_js can be installed and removed via npm, several ways to install follow. For Linux and MacOS Assuming the preinstallation requirements, installation of node.js and npm, are met please one one of the following. Global installation for all users: sudo npm i -g mediumroast_js Local installation for a developer or single user: npm i mediumroast_js For WinOS Coming soon. Step 3.1 - Upgrade the CLI After installation there are times when you may want to upgrade the CLI to the latest version, run the following. Global upgrade for all users: sudo npm i -g mediumroast_js Local upgrade for a developer or single user: npm i mediumroast_js Step 3.2 - Upgrade Actions After upgrading the CLI it may be necessary to upgrade the actions in the repository. To do this run mrcli actions --update and the actions will be updated to the latest version. Step 4.1 - Setup the CLI Before you can use the Mediumroast for GitHub CLI the environment must be setup. With the CLI installed please run mrcli setup to start the setup process, note there's a video of the setup process in CLI README. Running mrcli setup creates a repository in your oganization called &lt;organization_name&gt;_discovery to contain all interactions and companies, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below. Step 4.2 - Setup the CLI after initial setup Running mrcli setup a second time on an existing repository will not create a new one, instead it will detect the existing repository and prompt to update your authentication method and report theme. This is used typically when another user in your organization needs to access the repository. Step 5.1 - Verify your installation via the CLI After the setup process is complete you can verify the installation by running mrcli company to see the companies in the repository. Example screenshot of companies table Step 5.2 - Verify your installation via GitHub actions Additionally, two GitHub Actions are installed in the repository, one to clean up branches and the other to generate reports. To verify the actions are installed browse to the repository and click on the Actions tab to see the actions running. These actions are set to run on a schedule, but can be run manually. When a run you'll find an automatically generated README.md file in the repository and links to company reports in the README.md, an example screenshot of the repository companies report is below. Example screenshot of in repository companies report Warning Since Mediumroast for GitHub creates a regular repository you can interact with it as normal, but doing so is not recommended. If you interact with the repository, in regular ways, this could result in Mediumroast for GitHub becoming inoperable. There are cases where it may become necessary to directly work with the repository, but that should be rare. Contributing If you're interested in contributing to the Mediumroast for GitHub project, please review the CONTRIBUTING.md file in the .github directory of the repository. The file contains information on how to get started, how to clone the repository, and how to install the SDK for development. Issues If you detect a problem or want to suggest an improvement open an issue and we will work with you to resolve or respond. Support If you need support or would like to have Mediumroast run the Caffeine Machine Intelligence service on your repository please contact the Mediumroast team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Release notes Version 0.8.06.02 Resolved documentation errata for Demo.md Updated text for basic reporting workflow and action to show both companies and study reports are running. Removed debugging logging statements from basic reporting action. Version 0.8.06.01 The latest version of the SDK and CLI package now includes an initial implementation of Studies with the Foundation study. The SDK and CLI may run on for Windows OS, but it has not been tested. If you choose to install and run into problems please open an issue and we will work with you to resolve the matter. cli-table has been replaced by cli-table3 to ensure that CLI tabular outputs are on a stable and maintained package. The xlsx package has been removed and replaced with exceljs for improved output to Excel files, and due to the security vulnerability in the xlsx package. × Search results Close "},"GitHubFunctions.GitHubFunctions.html":{"id":"GitHubFunctions.GitHubFunctions.html","title":"Class: GitHubFunctions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: GitHubFunctions GitHubFunctions Core functions needed to interact with the GitHub API for mediumroast.io. new GitHubFunctions(token, org, processName) Parameters: Name Type Description token String the GitHub token for the mediumroast.io application org String the GitHub organization for the mediumroast.io application processName String the name of the process that is using the GitHub API Source: github.js, line 36 × Search results Close "},"module-GitHubAuth.html":{"id":"module-GitHubAuth.html","title":"Module: GitHubAuth","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: GitHubAuth authorize.js Version: 2.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: authorize.js, line 1 Example import {GitHubAuth} from './api/authorize.js' const github = new GitHubAuth(env, environ, configFile) const githubToken = github.verifyAccessToken() Requires module:axios module:open module:octoDevAuth module:chalk module:cli-table3 module:configparser module:FilesystemOperators Classes GitHubAuth Methods &lt;async, inner&gt; getAccessTokenDeviceFlow() Get the access token using the device flow Source: authorize.js, line 97 Returns: The access token object Type Object &lt;async, inner&gt; verifyAccessToken(saveToConfig) Verify if the access token is valid and if not get a new one depending on this.env.authType Parameters: Name Type Description saveToConfig Boolean Save to the configuration file, default is true Source: authorize.js, line 149 × Search results Close "},"module-GitHubAuth-GitHubAuth.html":{"id":"module-GitHubAuth-GitHubAuth.html","title":"Class: GitHubAuth","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: GitHubAuth GitHubAuth~ GitHubAuth new GitHubAuth(env, environ, configFile) Parameters: Name Type Description env Object The environment object environ Object The environmentals object configFile String The configuration file Source: authorize.js, line 44 × Search results Close "},"module-GitHubFunctions.html":{"id":"module-GitHubFunctions.html","title":"Module: GitHubFunctions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: GitHubFunctions github.js Version: 1.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: github.js, line 1 Example const gitHubCtl = new GitHubFunctions(accessToken, myOrgName, 'mr-cli-setup') const createRepoResp = await gitHubCtl.createRepository() Requires module:octokit module:axios Methods &lt;inner&gt; createContainers() Creates the top level Study, Company and Interaction containers for all mediumroast.io assets Source: github.js, line 302 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the responses or error messages. Type Array &lt;inner&gt; createRepository() Creates a repository, at the organization level, for keeping track of all mediumroast.io assets Source: github.js, line 152 To Do: Make sure the repo is not public Returns: An array with position 0 being boolean to signify success/failure and position 1 being the created repo or error message. Type Array &lt;async, inner&gt; getActionsBillings() Gets the complete billing status for actions from the GitHub API Source: github.js, line 116 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getAllUsers() Gets all of the users from the GitHub API Source: github.js, line 96 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;inner&gt; getGitHubOrg() If the GitHub organization exists retrieves the detail about it and returns to the caller Source: github.js, line 172 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the org or error message. Type Array &lt;async, inner&gt; getStorageBillings() Gets the complete billing status for actions from the GitHub API Source: github.js, line 134 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getUser() Gets the authenticated user from the GitHub API Source: github.js, line 78 To Do: Add a check to see if the user is a member of the organization Add a check to see if the user has admin rights to the organization Returns: An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message. Type Array &lt;async, inner&gt; getWorkflowRuns() Gets all of the workflow runs for the repository Source: github.js, line 188 Returns: An array with position 0 being boolean to signify success/failure and position 1 being the response or error message. Type Array × Search results Close "},"module-baseObjects.html":{"id":"module-baseObjects.html","title":"Module: baseObjects","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Module: baseObjects gitHubServer.js Version: 2.0.0 Author: Michael Hay Copyright: 2024 Mediumroast, Inc. All rights reserved. License: Apache-2.0 Source: gitHubServer.js, line 1 Example import {Companies, Interactions, Users, Billings} from './api/gitHubServer.js' const companies = new Companies(token, org, processName) const interactions = new Interactions(token, org, processName) const users = new Users(token, org, processName) const billings = new Billings(token, org, processName) const allCompanies = await companies.getAll() const allInteractions = await interactions.getAll() const allUsers = await users.getAll() const allBillings = await billings.getAll() const company = await companies.findByName('myCompany') const interaction = await interactions.findByName('myInteraction') const user = await users.findByName('myUser') Requires module:GitHubFunctions module:crypto module:fs module:path module:fileURLToPath Classes Actions Companies Interactions Storage Studies Users Methods &lt;async, inner&gt; createObj(objs) Create objects in the mediumroast.io application Parameters: Name Type Description objs Array the objects to create in the backend Source: gitHubServer.js, line 134 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; deleteObj(id, endpoint) Delete an object in the mediumroast.io application Parameters: Name Type Description id String the object to be deleted in the mediumroast.io application endpoint String defaults to findbyx and is combined with credential and version info Source: gitHubServer.js, line 204 To Do: implment when available in the backend Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findById(id, endpoint) Find all objects by id from the mediumroast.io application Parameters: Name Type Description id String the id of the object to find endpoint String defaults to findbyx and is combined with credential and version info Deprecated: Yes Source: gitHubServer.js, line 80 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findByName(name) Find all objects by name from the mediumroast.io application Parameters: Name Type Description name String the name of the object to find Source: gitHubServer.js, line 69 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; findByX(attribute, value) Find all objects by attribute and value pair from the mediumroast.io application Parameters: Name Type Description attribute String the attribute used to find objects value String the value for the defined attribute Source: gitHubServer.js, line 96 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; getAll() Get all objects from the mediumroast.io application Source: gitHubServer.js, line 59 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; linkObj(objs) Link objects in the mediumroast.io application Parameters: Name Type Description objs Array the objects to link in the backend Source: gitHubServer.js, line 217 Returns: the results from the called function mrRest class Type Array &lt;async, inner&gt; updateObj(obj, endpoint) Update an object in the mediumroast.io application Parameters: Name Type Description obj Object the object to update in the backend which includes the id and, the attribute and value to be updated endpoint String defaults to findbyx and is combined with credential and version info Source: gitHubServer.js, line 192 Returns: the results from the called function mrRest class Type Array × Search results Close "},"module-baseObjects-Actions.html":{"id":"module-baseObjects-Actions.html","title":"Class: Actions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Actions baseObjects~ Actions A subclass of baseObjects that construct the interaction objects new Actions(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 470 × Search results Close "},"module-baseObjects-Companies.html":{"id":"module-baseObjects-Companies.html","title":"Class: Companies","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Companies baseObjects~ Companies A subclass of baseObjects that construct the company objects new Companies(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 328 × Search results Close "},"module-baseObjects-Interactions.html":{"id":"module-baseObjects-Interactions.html","title":"Class: Interactions","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Interactions baseObjects~ Interactions A subclass of baseObjects that construct the interaction objects new Interactions(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 431 × Search results Close "},"module-baseObjects-Storage.html":{"id":"module-baseObjects-Storage.html","title":"Class: Storage","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Storage baseObjects~ Storage A subclass of baseObjects that construct the user objects new Storage(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 305 × Search results Close "},"module-baseObjects-Studies.html":{"id":"module-baseObjects-Studies.html","title":"Class: Studies","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Studies baseObjects~ Studies A subclass of baseObjects that construct the study objects new Studies(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 249 × Search results Close "},"module-baseObjects-Users.html":{"id":"module-baseObjects-Users.html","title":"Class: Users","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Class: Users baseObjects~ Users A subclass of baseObjects that construct the user objects new Users(token, org, processName) Parameters: Name Type Description token String the token for the GitHub application org String the organization for the GitHub application processName String the process name for the GitHub application Source: gitHubServer.js, line 263 × Search results Close "},"tutorial-Company.html":{"id":"tutorial-Company.html","title":"Tutorial: Company Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Company Subcommand Companies Company objects are central to Mediumroast for GitHub. Interactions and in the future Studies rely on Companies to function. After setup is run, via mrcli setup, two companies are present to work with. Additional Companies can be added, updated, or removed; essentially, company is an mrcli sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for mrcli company are described in this document. Notice(s) Some command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Similarity comparisons of Companies requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the company sub-command and exits. Command(s) run mrcli company --help Screenshot with output List company objects Print out one or more Companies to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Companies with specific attributes. List all company objects in a table format This is the default output when running mrcli c or mrcli company which prints a text table to STDOUT. Command(s) run mrcli c mrcli company Screenshot with output List all company objects in JSON format Output a list of company objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli c --output=json mrcli company --output=json Screenshot with output List all company objects and output to a CSV Company data can be output in CSV files to enable consumption in common tools like Microsoft Excel or Apple Numbers. The resulting files will be stored in $HOME/Documents directory as Mr_Companies.csv. Command(s) run mrcli c --output=csv mrcli company --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter company outputs The CLI offers the ability to filter outputs by almost any company attribute. This is manifest by two switches on the company sub-command one specific to finding companies by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a company using any attribute you have to fully provide the attribute's value (i.e., \"Med\" would not match \"Mediumroast, Inc.\", but \"Mediumroast, Inc.\" would). Filter in a company by name To zero in on a specific company using the find by name switch is provided. Command(s) run mrcli c --find_by_name=\"Mediumroast, Inc.\" Screenshot with output Filter a company by attribute Find a specific company by a particular attribute in the example below the switch filters on the attribute company_type. Command(s) run mrcli c --find_by_x='{\"company_type\": \"Public\"}' Screenshot with output Update a company attribute To update a company attribute the --update switch is provided. A properly formatted JSON stanza is supplied to the --update switch that specifies the name of the company to update, the key to update, and finally the value of the key to update. Command(s) run mrcli c --update='{\"name\": \"Atlassian Corp\", \"key\": \"company_type\", \"value\": \"Public\"}' Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/a74cb8cd-f8cb-4a8d-8968-ccf9b875d86b Delete a company Remove a company and associated interactions if in the repository. There is a confirmation prompt which defaults to yes. Note that the exact company name is needed to proceed with a deletion. Command(s) run mrcli c --delete=\"Atlassian Corp\" Screenshot with output Add a company A command line prompt based wizard steps the user through either a semi-automated process or a fully-automated process to define a company. The semi-automated process is typically used for companies that aren't public. While the fully-automated process is typically used for companies that are public. In either case the user is asked to verify the steps taken before the company is committed to the repository. Command(s) run mrcli c --add_wizard Screenshot with output Report on a company Produce a MS Word document report on a company. The report includes a dashboard with a company similarity report, company firmographics, detail on similar companies, and summaries for all interactions associated to the company reported on. The report is stored in the $HOME/Documents directory as &lt;company_name&gt;.docx. Optionally, if the --package switch is used the report is zipped and stored in the $HOME/Documents directory as &lt;company_name&gt;.zip including all of the interactions associated to the company and the set of most and least similar companies. Command(s) run mrcli c --report=\"Atlassian Corp\" mrcli c --report=\"Atlassian Corp\" --package Screenshot of the report dashboard × Search results Close "},"tutorial-Demo.html":{"id":"tutorial-Demo.html","title":"Tutorial: Demo","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Demo Introduction To help users get started with Mediumroast for GitHub, a demo repository has been created in the organization MegaRoast. The demo repository is a clone of our repository, but without actions that automatically generate reports and clean up branches. Further, the demo repository is regularly cloned to reflect the latest changes from our main repository on a weekly basis. So while you can make changes to the demo repository, they will be overwritten on the next clone. This is to ensure that the demo repository is always in sync with the main repository. To gain access to the demo repository, please follow the steps in the main README to install the CLI. From there run mrcli setup and when prompted enter the GitHub organization MegaRoast. Because the demo repository is a clone of our repository the setup will not create a new repository, but instead prompt you for your authentication method and report theme. Once you've completed the setup process you will have access to the demo repository and can begin to explore the capabilities of Mediumroast for GitHub. However, if you've installed the CLI and run mrcli setup you can merely modify your $HOME/.mediumroast/config.ini file to point to the MegaRoast organization. This will enable you to access the demo repository without running mrcli setup again. Example config.ini file With this configuration file by updating the org value to MegaRoast you can access the demo repository without running mrcli setup again. [DEFAULT] company_dns=https://company-dns.mediumroast.io company_logos=https://icon-server.mediumroast.io/allicons.json?url= echarts=https://chart-server.mediumroast.io:11000 nominatim=https://nominatim.openstreetmap.org/search?addressdetails=1&amp;q= working_directory=working report_output_dir=Documents theme=latte [GitHub] clientId=Iv1.f5c0a4eb1f0606f8 appId=650476 token=&lt;TOKEN&gt; authType=deviceFlow org=MegaRoast Limitations The following limitations are in place for the demo repository: The demo repository is a clone of the main repository and is updated weekly. The demo repository does not have the actions that automatically generate reports and clean up branches, which means that mrcli actions will not work as expected. The demo repository is a shared read-only repository, meaning you can't push changes to it. If you need to test changes, please use your own repository. × Search results Close "},"tutorial-Interaction.html":{"id":"tutorial-Interaction.html","title":"Tutorial: Interaction Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Interaction Subcommand Interactions After running mrcli setup you can start adding Interactions. An Interaction can be as simple as an email thread between an account team and a customer, a detailed customer interview or even documentation about a competitor. Additional Interactions can be added, updated, or removed; essentially, interaction is an mrcli sub-command that affords users Create, Read, Update and Delete capabilities. Each of the major functions for mrcli interaction are described in this document. Notice(s) Some command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Summarization of Interaction contents and generating proto-requirements plus competitive insights requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the interaction sub-command and exits. Command(s) run mrcli interaction --help Screenshot with output List interaction objects Print out one or more Interaction to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Interactions with specific attributes. List all interaction objects in a table format This is the default output when running mrcli i or mrcli interaction which prints a text table to STDOUT. Command(s) run mrcli i mrcli interaction Screenshot with output List all interaction objects in JSON format Output a list of company objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli i --output=json mrcli interaction --output=json Screenshot with output List all interaction objects and output to a CSV Interaction data can be output in CSV files to enable consumption in common tools like Microsoft Excel or Apple Numbers. The resulting files will be stored in $HOME/Documents directory as Mr_Interactions.csv. Command(s) run mrcli i --output=csv mrcli interaction --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter interaction outputs The CLI offers the ability to filter outputs by almost any interaction attribute. This is manifest by two switches on the interaction sub-command one specific to finding Interactions by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a interaction using any attribute you have to fully provide the attribute's value (i.e., \"The\" would not match \"The 7 Strategic Phases of the Product Planning Process\" , but \"The 7 Strategic Phases of the Product Planning Process\" would). Filter in a interaction by name To zero in on a specific interaction using the find by name switch is provided. Command(s) run mrcli i --find_by_name=\"The 7 Strategic Phases of the Product Planning Process\" Screenshot with output Filter an interaction by attribute Find a specific interaction by a particular attribute in the example below the switch filters on the attribute city. Command(s) run mrcli i --find_by_x='{\"city\": \"Santa Barbara\"}' Screenshot with output Update an interaction attribute To update an interaction attribute the --update switch is provided. A properly formatted JSON stanza is supplied to the --update switch that specifies the name of the interaction to update, the key to update, and finally the value of the key to update. Command(s) run mrcli c --update='{\"name\": \"Atlassian Corp\", \"key\": \"company_type\", \"value\": \"Public\"}' Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/e11256e7-28ca-47d5-b131-58a2036671a6 Delete an interaction Remove a company and associated interactions if in the repository. There is a confirmation prompt which defaults to yes. Note that the exact company name is needed to proceed with a deletion. Command(s) run mrcli i --delete=\"Atlassian Corp\" Screenshot with output Add an interaction A command line prompt based wizard steps the user through a semi-automated process process to define an interaction. The user is asked to verify the steps taken before the interaction(s) is committed to the repository. Command(s) run mrcli i --add_wizard Screencast with output Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/0b28db90-d6ba-4224-a9ae-4c301c2b9614 Report on an interaction Produce a MS Word document report on an interaction. The report includes a dashboard with interaction metadata, interaction abstract, and proto-requirements. The report is stored in the $HOME/Documents directory as &lt;interaction_name&gt;.docx. Optionally, if the --package switch is used the report is zipped and stored in the $HOME/Documents directory as &lt;interaction_name&gt;.zip including the interaction content. Command(s) run mrcli i --report=\"Atlassian Corp\" mrcli i --report=\"Atlassian Corp\" --package Screenshot of the report dashboard × Search results Close "},"tutorial-README.html":{"id":"tutorial-README.html","title":"Tutorial: Administrative Subcommands","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Administrative Subcommands Mediumroast for GitHub CLI (Command Line Interface) The CLI is divided into two sets one for administrative interactions with the system and another for interacting with Mediumroast for GitHub objects like Companies and Interactions. This document covers both the administrative CLI and makes reference to the CLI set for Mediumroast for GitHub objects. Authentication Mediumroast for GitHub uses either Device Flow or a Personal Access Token for authentication. The setup CLI will prompt you to choose the type of authentication and then store the necessary information in the ${HOME}/.mediumroast/config.ini file. If you need to change the authentication configuration you can run mrcli setup to reset the configuration file. Required permissions for the Personal Access Token (PAT) If you create a PAT before the Mediumroast for GitHub repository exists the required scope is for all repositories in your organization. At PAT renewal or if you want to reduce the scope to only the Mediumroast for GitHub repository this can be done later. The Personal Access Token must have the following permissions on all repositories to perform the necessary actions including setup. Actions: read/write Administration: read/write Contents: read/write Metadata: read Pull requests: read/write Workflows: read/write For background and directions on creating a PAT see the GitHub documentation. Administrative CLIs To enable setup and operational reporting of Mediumroast for GitHub several CLIs are available, each is described below. Storage reporting Reports storage consumed by Mediumroast for GitHub. A screenshot showing the usage information and outputs for major functions is included below. Command(s) run mrcli t mrcli storage Screenshot with ouput Actions Reports actions minutes consumed by Mediumroast for GitHub and enables a user to update their repository as new versions of actions are released. A screenshot showing the usage information and outputs for major functions is included below. Command(s) run mrcli actions mrcli a --update Screenshot with ouput User reporting Reports on all users who can access the repository that contains the Mediumroast for GitHub. A screenshot showing the usage information and outputs for major functions is included below, and notice, user names and other personally identifiable information has been redacted from the screenshot below. Command(s) run mrcli u mrcli u --my_user Screenshot with ouput Setup To help users quickly get on board with Mediumroast for GitHub the setup CLI is used. This CLI creates the ${HOME}/.mediumroast/config.ini file, creates the repository including key directories, and creates two initial companies. A screencast video showing the process for setting up the CLI environment and creating two companies is available below. Command(s) run mrcli setup Screencast showing setup process Notice: Only the markdown version rendered through the GitHub web interface will display the screencast. If you're viewing these files through the GitHub Page Version the link below will just show up as text. https://github.com/mediumroast/mediumroast_js/assets/10818650/68c08502-4f59-4981-a001-0d9c9bd1d4d2 Deprecated commands The following commands are deprecated, are disabled and will be removed in a future release of the CLI. Billing reporting Is replaced by storage and actions commands in Mediumroast for GitHub. If you run this command it will immediately exit stating it is no longer supported. Command(s) run mrcli b mrcli billing [Company Subcommand] | [Interaction Subcommand | [Studies Subcommand] × Search results Close "},"tutorial-Study.html":{"id":"tutorial-Study.html","title":"Tutorial: Study Subcommand","body":" Mediumroast for GitHub SDK and CLI Modules GitHubAuthGitHubFunctionsbaseObjects Classes GitHubFunctions.GitHubFunctionsGitHubAuth~GitHubAuthbaseObjects~ActionsbaseObjects~CompaniesbaseObjects~InteractionsbaseObjects~StoragebaseObjects~StudiesbaseObjects~Users Tutorials Company SubcommandDemoInteraction SubcommandAdministrative SubcommandsStudy Subcommand Study Subcommand Studies Study objects are central to Mediumroast for GitHub. Studies rely on Interactions and Companies to function. At this time only the Foundation study is implemented; a future update will add support for user defined studies. To enable the Foundation study run mrcli study --init_foundation, which will create the basic structures of the study in the repository. Each of the major functions for mrcli study are described in this document. Notice(s) Some of the command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit. Study deletion is not yet implemented and not present. The only update possible to the Foundation study is to reset its status to cause Caffeine to reprocess the study. Populating the Foundation study requires a run of the Mediumroast for GitHub Caffeine Machine Intelligence service. If you're interested in running the Caffeine Machine Intelligence service please contact the Mediumroast for GitHub team via Discord or email us at [hello@mediumroast.io], (mailto:hello@mediumroast.io). Help Prints the usage for the study sub-command and exits. Command(s) run mrcli study --help Screenshot with output List study objects Print out one or more Studies to the command line or an alternative output mechanism like a CSV file. Filtering can be applied to find Studies with specific attributes. List all study objects in a table format This is the default output when running mrcli s or mrcli study which prints a text table to STDOUT. Command(s) run mrcli s mrcli study Screenshot with output List all study objects in JSON format Output a list of study objects in properly formatted JSON to STDOUT which can be viewed, redirected to a file, or piped to another command. Command(s) run mrcli s --output=json mrcli study --output=json Screenshot with output List all study objects and output to a CSV Study data can be output in a CSV file to enable consumption in common tools like Microsoft Excel. The resulting file will be stored in $HOME/Documents directory as Mr_Studies.csv. Command(s) run mrcli s --output=csv mrcli study --output=csv Screenshot of commands being run Screenshot of CSV imported into MacOS numbers Filter study outputs The CLI offers the ability to filter outputs by almost any study attribute. This is manifest by two switches on the study sub-command one specific to finding studies by name, --find_by_name and the other by an arbitrary attribute, --find_by_x. Note all output format options, like JSON, CSV, etc., are available when the outputs are filtered. Finally, only exact matches are supported, meaning if you want to search for a study using any attribute you have to fully provide the attribute's value (i.e., \"Med\" would not match \"Mediumroast Study\", but \"Mediumroast Study\" would). Filter a study by name To zero in on a specific study using the find by name switch is provided. Command(s) run mrcli s --find_by_name=\"Foundation\" Screenshot with output Filter a study by attribute Find a specific study by a particular attribute in the example below the switch filters on the attribute status. Command(s) run mrcli s --find_by_x='{\"status\": \"0\"}' Screenshot with output Initialize the Foundation study Initializes the Foundation study with core attributes and data. This is the first step in setting up the Foundation study. Command(s) run mrcli s --init_foundation Screenshot with output Report on a study Produce a report on a study. The report provides the most important insights per company in Microsoft Excel format as of the current release. The report is stored in the $HOME/Documents directory as &lt;study_name&gt;.xlsx. Command(s) run mrcli s --report=\"Foundation\" Screenshot of the report Reset the status of a study Reset the status of a study will cause Caffeine to reprocess the study on its next run. This is useful when the study has been updated and needs to be reprocessed. Command(s) run mrcli s --reset_by_name=\"Foundation\" Screenshot with output × Search results Close "}}
     </script>
 
     <script type="text/javascript">
diff --git a/docs/tutorial-Company.html b/docs/tutorial-Company.html
index 3f13942..f20d3c1 100644
--- a/docs/tutorial-Company.html
+++ b/docs/tutorial-Company.html
@@ -227,7 +227,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/tutorial-Demo.html b/docs/tutorial-Demo.html
index 026c4d8..6c41e31 100644
--- a/docs/tutorial-Demo.html
+++ b/docs/tutorial-Demo.html
@@ -96,18 +96,18 @@ <h3>Example config.ini file</h3>
 <pre class="prettyprint source lang-ini"><code>[DEFAULT]
 company_dns=https://company-dns.mediumroast.io
 company_logos=https://icon-server.mediumroast.io/allicons.json?url=
-echarts=https://echart-server.mediumroast.io:11000
+echarts=https://chart-server.mediumroast.io:11000
 nominatim=https://nominatim.openstreetmap.org/search?addressdetails=1&q=
 working_directory=working
 report_output_dir=Documents
-theme=coffee
+theme=latte
 
 [GitHub]
 clientId=Iv1.f5c0a4eb1f0606f8
 appId=650476
-authType=deviceFlow
-org=&lt;ORGANIZATION>
 token=&lt;TOKEN>
+authType=deviceFlow
+org=MegaRoast
 </code></pre>
 <h3>Limitations</h3>
 <p>The following limitations are in place for the demo repository:</p>
@@ -157,7 +157,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/tutorial-Interaction.html b/docs/tutorial-Interaction.html
index 4cc66b7..0f1ea6b 100644
--- a/docs/tutorial-Interaction.html
+++ b/docs/tutorial-Interaction.html
@@ -228,7 +228,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/tutorial-README.html b/docs/tutorial-README.html
index d6e7e92..c9b2c1a 100644
--- a/docs/tutorial-README.html
+++ b/docs/tutorial-README.html
@@ -192,7 +192,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/tutorial-Study.html b/docs/tutorial-Study.html
index 0fbe6a1..d57c0f4 100644
--- a/docs/tutorial-Study.html
+++ b/docs/tutorial-Study.html
@@ -218,7 +218,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/docs/tutorials.list.html b/docs/tutorials.list.html
index 953660b..41ab9b4 100644
--- a/docs/tutorials.list.html
+++ b/docs/tutorials.list.html
@@ -207,7 +207,7 @@ <h4 class="modal-title">Search results</h4>
 <span class="jsdoc-message">
 	Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a>
 	
-		on Sat Dec 28th 2024
+		on Sun Dec 29th 2024
 	
 	using the <a href="https://github.com/docstrap/docstrap">DocStrap template</a>.
 </span>
diff --git a/package.json b/package.json
index 595517a..509de75 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mediumroast_js",
-  "version": "0.8.06.01",
+  "version": "0.8.06.02",
   "description": "A Command Line Interface (CLI) and Javascript SDK to interact with Mediumroast for GitHub.",
   "main": "cli/mrcli.js",
   "scripts": {