Skip to content

api-docs.md

Latest commit

 

History

History
389 lines (288 loc) · 20 KB

api-docs.md

File metadata and controls

389 lines (288 loc) · 20 KB

Modules

GitHubAuth

authorize.js

GitHubFunctions

github.js

api/gitHubServer.js

gitHubServer.js

GitHubAuth

authorize.js

Requires: module:open, module:octoDevAuth, module:chalk, module:cli-table3
Version: 3.0.0
Author: Michael Hay michael.hay@mediumroast.io
License: Apache-2.0
Copyright: 2025 Mediumroast, Inc. All rights reserved.
Example

import {GitHubAuth} from './api/authorize.js'
const github = new GitHubAuth(env, environ, configFile)
const githubToken = github.verifyAccessToken()

GitHubAuth~GitHubAuth

Kind: inner class of GitHubAuth

new GitHubAuth(env, environ, configFile, configExists)

Param Type Description
env Object The environment object
environ Object The environmentals object
configFile String The configuration file path
configExists Boolean Whether the configuration file exists

gitHubAuth.verifyGitHubSection() ⇒ Boolean

Verifies if the GitHub section exists in the configuration

Kind: instance method of GitHubAuth
Returns: Boolean - True if the GitHub section exists, otherwise false

gitHubAuth.getAccessTokenFromConfig() ⇒ String | null

Gets the access token from the configuration file

Kind: instance method of GitHubAuth
Returns: String | null - The access token or null if not found

gitHubAuth.getAuthTypeFromConfig() ⇒ String | null

Gets the authentication type from the configuration file

Kind: instance method of GitHubAuth
Returns: String | null - The authentication type or null if not found

gitHubAuth.checkTokenExpiration(token) ⇒ Array

Checks if a GitHub token is valid and not expired

Kind: instance method of GitHubAuth
Returns: Array - [isValid, statusObject, userData]

Param Type Description
token String The GitHub token to check

gitHubAuth.getAccessTokenDeviceFlow() ⇒ Object

Gets an access token using the GitHub device flow

Kind: instance method of GitHubAuth
Returns: Object - The access token object

gitHubAuth.verifyAccessToken(saveToConfig) ⇒ Array

Verifies if the access token is valid and gets a new one if needed

Kind: instance method of GitHubAuth
Returns: Array - [success, statusObject, tokenData]

Param Type Default Description
saveToConfig Boolean true Whether to save to the configuration file, default is true

GitHubFunctions

github.js

Requires: module:octokit
Version: 3.0.0
Author: Michael Hay michael.hay@mediumroast.io
License: Apache-2.0
Copyright: 2025 Mediumroast, Inc. All rights reserved.
Example

const gitHubCtl = new GitHubFunctions(accessToken, myOrgName, 'mr-cli-setup')
const createRepoResp = await gitHubCtl.createRepository()

GitHubFunctions~getUser() ⇒ Array

Gets the authenticated user from the GitHub API

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message.

GitHubFunctions~getAllUsers() ⇒ Array

Gets all of the users from the GitHub API

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message.

GitHubFunctions~getActionsBillings() ⇒ Array

Gets the complete billing status for actions from the GitHub API

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message.

GitHubFunctions~getStorageBillings() ⇒ Array

Gets the complete billing status for actions from the GitHub API

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the user info or error message.

GitHubFunctions~createRepository() ⇒ Array

Creates a repository, at the organization level, for keeping track of all mediumroast.io assets

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the created repo or error message.

GitHubFunctions~getGitHubOrg() ⇒ Array

If the GitHub organization exists retrieves the detail about it and returns to the caller

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the org or error message.

GitHubFunctions~getWorkflowRuns() ⇒ Array

Gets all of the workflow runs for the repository

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the response or error message.

GitHubFunctions~getRepoSize() ⇒ Array

Gets the size of the repository in MB

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the response or error message.

GitHubFunctions~createContainers() ⇒ Array

Creates the top level Study, Company and Interaction containers for all mediumroast.io assets

Kind: inner method of GitHubFunctions
Returns: Array - An array with position 0 being boolean to signify success/failure and position 1 being the responses or error messages.

GitHubFunctions~createBranchFromMain() ⇒ Promise.<Array>

Creates a new branch from the main branch.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - A promise that resolves to an array containing a boolean indicating success, a message, and the response.

GitHubFunctions~mergeBranchToMain(branchName, mySha, [commitDescription]) ⇒ Promise.<Array>

Merges a specified branch into the main branch by creating a pull request.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - A promise that resolves to an array containing success status, message, and response.

Param Type Default Description
branchName string The name of the branch to merge into main.
mySha string The SHA of the commit to use as the head of the pull request.
[commitDescription] string "'Performed CRUD operation on objects.'" The description of the commit.

GitHubFunctions~checkForLock(containerName) ⇒ Promise.<Array>

Checks to see if a container is locked.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - A promise that resolves to an array containing status and message.

Param Type Description
containerName string The name of the container to check for a lock.

GitHubFunctions~lockContainer(containerName) ⇒ Promise.<Array>

Locks a container by creating a lock file in the container.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - A promise that resolves to an array containing status and message.

Param Type Description
containerName string The name of the container to lock.

GitHubFunctions~unlockContainer(containerName, commitSha, branchName) ⇒ Promise.<Array>

Unlocks a container by deleting the lock file in the container.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - A promise that resolves to an array containing status and message.

Param Type Description
containerName string The name of the container to unlock.
commitSha string The SHA of the commit to use as the head of the pull request.
branchName string The name of the branch to unlock the container on.

GitHubFunctions~writeObject(containerName, obj, ref, mySha) ⇒ Promise.<Array>

Writes an object to a specified container using the GitHub API.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and response

Param Type Description
containerName string The name of the container to write the object to.
obj object The object to write to the container.
ref string The reference to use when writing the object.
mySha string The SHA of the current file if updating.

GitHubFunctions~readObjects(containerName) ⇒ Promise.<Array>

Reads objects from a specified container using the GitHub API.

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and contents

Param Type Description
containerName string The name of the container to read objects from.

GitHubFunctions~updateObject(containerName, objName, key, value, [dontWrite], [system], [whiteList]) ⇒ Promise.<Array>

Updates an object in a specified container

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and response

Param Type Default Description
containerName string The name of the container containing the object
objName string The name of the object to update
key string The key of the object to update
value string The value to update the key with
[dontWrite] boolean false A flag to indicate if the object should be written back
[system] boolean false A flag to indicate if the update is a system call
[whiteList] Array [] A list of keys that are allowed to be updated

GitHubFunctions~deleteObject(objName, source, repoMetadata, catchIt) ⇒ Promise.<Array>

Deletes an object from a specified container

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and response

Param Type Description
objName string The name of the object to delete
source object The source object that contains the from and to containers
repoMetadata object The repository metadata
catchIt boolean Whether to catch the container

GitHubFunctions~catchContainer(repoMetadata) ⇒ Promise.<Array>

Catches a container by locking it, creating a new branch, reading the objects

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and metadata

Param Type Description
repoMetadata Object The metadata object

GitHubFunctions~releaseContainer(repoMetadata) ⇒ Promise.<Array>

Releases a container by unlocking it and merging the branch

Kind: inner method of GitHubFunctions
Returns: Promise.<Array> - Status, message, and response

Param Type Description
repoMetadata Object The metadata object

api/gitHubServer.js

gitHubServer.js

Version: 3.0.0
Author: Michael Hay michael.hay@mediumroast.io
License: Apache-2.0
Copyright: 2025 Mediumroast, Inc. All rights reserved.

Additional Documentation

.gitkeep File Management

For information about the intelligent .gitkeep file management and cleanup functionality, see:

This functionality addresses production issues with stale .gitkeep files and provides automated cleanup for GitHub Actions installations.

Fuzzy Search Functionality

Enhanced search capabilities for BaseObjects with fuzzy (partial string) matching support:

This enhancement allows for partial string matching in findByName() and findByX() methods, making object discovery more flexible and user-friendly.