Documentation

Class: Gitlab

Description: The Gitlab class provides a set of functions for interacting with Gitlab APIs. It utilizes the axios library for making HTTP requests and handles authentication, error handling, and common data processing.

Methods

Method: isInstalled

Description: Checks if the user has an active Gitlab installation.

Parameters: None

Returns:

  • boolean: true if the user has an active Gitlab installation, false otherwise.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const isUserInstalled = await Gitlab.isInstalled(); 
console.log("User has Gitlab installation:", isUserInstalled);

Method: getAvatar

Description: Fetches the avatar URL for a given Gitlab user.

Parameters:

  • login (string): The Gitlab username.

Returns:

  • string: The avatar URL for the specified user.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const avatarUrl = await Gitlab.getAvatar("john.doe"); 
console.log("User avatar URL:", avatarUrl);

Method: getRepo

Description: Fetches information about a Gitlab repository.

Parameters:

  • repo (object): An object containing the repository owner and name.
    • owner (string): The Gitlab username of the repository owner.
    • name (string): The name of the repository.
  • branches (boolean): (Optional, default: false) Whether to include a list of branches for the repository.

Returns:

  • object: An object containing information about the Gitlab repository. Includes branches if the branches parameter is set to true.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const repoInfo = await Gitlab.getRepo({ owner: "john.doe", name: "my-project" }, true);
console.log("Repository information:", repoInfo);

Method: getBranches

Description: Fetches a list of branches for a given Gitlab repository.

Parameters:

  • repo (object): An object containing the repository owner and name.
    • owner (string): The Gitlab username of the repository owner.
    • name (string): The name of the repository.

Returns:

  • array: An array of branch objects.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const branches = await Gitlab.getBranches({ owner: "john.doe", name: "my-project" });
console.log("Branches:", branches);

Method: getFiles

Description: Fetches a list of files in a Gitlab repository.

Parameters:

  • repo (object): An object containing the repository owner and name.
    • owner (string): The Gitlab username of the repository owner.
    • name (string): The name of the repository.
  • path (string): (Optional, default: null) The path to the directory to fetch files from. If omitted, the default branch is used.
  • recursive (boolean): (Optional, default: false) Whether to recursively fetch files within subdirectories.

Returns:

  • object: An object containing the list of files and their metadata.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const files = await Gitlab.getFiles({ owner: "john.doe", name: "my-project" }, "src", true);
console.log("Files:", files);

Method: getFile

Description: Fetches the content of a specific file from a Gitlab repository.

Parameters:

  • repo (object): An object containing the repository owner and name.
    • owner (string): The Gitlab username of the repository owner.
    • name (string): The name of the repository.
  • file (string): The name of the file to fetch.
  • ref (string): The branch or commit reference to fetch the file from.

Returns:

  • object: An object containing the file content, metadata, and decoded content as a string.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const fileContent = await Gitlab.getFile({ owner: "john.doe", name: "my-project" }, "index.js", "main");
console.log("File content:", fileContent);

Method: saveFile

Description: Saves changes to a file in a Gitlab repository.

Parameters:

  • file (object): An object containing the file information.
    • path (string): The path to the file.
    • sha (string): The SHA hash of the existing file.
  • content (string): The new content of the file.
  • repo (object): An object containing the repository owner and name.
    • owner (string): The Gitlab username of the repository owner.
    • name (string): The name of the repository.
  • msg (string): The commit message for the changes.
  • branch (string): The branch to save the changes to.

Returns:

  • object: An object containing the response from the Gitlab API.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example:

const file = { path: "index.js", sha: "a1b2c3d4e5f6" };
const newContent = "console.log('Hello, world!');";
const response = await Gitlab.saveFile(file, newContent, { owner: "john.doe", name: "my-project" }, "Update index.js", "main");
console.log("Save file response:", response);

Method: _request

Description: A private helper method for making authenticated HTTP requests to the Gitlab API.

Parameters:

  • path (string): The API endpoint path.
  • args (object): (Optional, default: null) Additional request arguments, such as params, data, etc.
  • method (string): (Optional, default: "GET") The HTTP method to use.

Returns:

  • object: The response data from the Gitlab API.

Throws:

  • Error: If there is an error making the request to the Gitlab API.

Example: (Not directly called by users, used internally within other Gitlab methods.)

Static Properties

Static Property: URLs

Description: A static object containing pre-defined Gitlab URLs. This object provides functions for constructing URLs for different Gitlab resources based on provided information.

Properties:

  • base (string): The base URL of Gitlab.
  • user (function): A function that constructs a user URL based on the owner's username.
  • repo (function): A function that constructs a repository URL based on the owner's username and repository name.
  • branch (function): A function that constructs a branch URL based on the owner's username, repository name, and branch name.
  • pull (function): A function that constructs a pull request URL based on the owner's username, repository name, and pull request number.
  • file (function): A function that constructs a file URL based on the owner's username, repository name, branch name, and file path.

Example:

const userUrl = Gitlab.URLs.user({ owner: "john.doe" });
console.log("User URL:", userUrl);

Important Considerations:

  • Authentication: The Gitlab class relies on the getAccessToken() function to obtain a valid access token for authentication with the Gitlab API. Ensure that this function correctly fetches and returns a valid token.
  • Error Handling: Error handling is implemented within each method. However, it is essential to be aware of potential error scenarios and implement appropriate error handling in your application.
  • Rate Limiting: Be mindful of Gitlab API rate limits. The code does not currently implement rate limiting, so excessive calls to the Gitlab API can lead to rate limiting.
  • API Changes: Gitlab APIs can evolve over time. It is essential to stay informed about potential changes and update the Gitlab class accordingly to ensure compatibility.

Potential Pitfalls:

  • Invalid Access Token: If the getAccessToken() function fails to obtain a valid token, the API requests will fail.
  • Incorrect URL Construction: Ensure that the URLs object correctly constructs Gitlab URLs for the required resources.
  • Incorrect API Endpoint: The GITHUB_API_ENDPOINT variable must be correctly set to the appropriate Gitlab API endpoint.
  • Unhandled Errors: Always handle potential errors returned from the Gitlab API to avoid unexpected behavior in your application.