feat: add GitLab API

src/api.ts

@@ -0,0 +1,533 @@
+/*
+ * Copyright (C) 2018 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import {Logger} from '@openstapps/logger';
+import * as request from 'request-promise-native';
+import {AccessLevel, Branch, Issue, Label, Member, MergeRequest, Milestone, Project, Tag, TreeFile} from './types';
+
+export const logger = new Logger();
+
+/**
+ * Sleep for a number of milliseconds
+ *
+ * @param ms Number of milliseconds to wait
+ */
+export function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * API request options
+ */
+export interface ApiRequestOptions {
+  /**
+   * Data to be sent with the request
+   */
+  data?: any;
+
+  /**
+   * HTTP verb to use for the request
+   */
+  method?: 'DELETE' | 'GET' | 'POST' | 'PUT';
+}
+
+/**
+ * GitLab API get issues options
+ */
+export interface ApiGetIssuesOptions {
+  groupId?: number;
+  milestone?: 'Meeting' | 'Backlog' | 'No Milestone';
+  state?: 'opened' | 'closed';
+}
+
+/**
+ * GitLab API
+ */
+export class Api {
+  /**
+   * Private token
+   */
+  private readonly privateToken: string;
+
+  /**
+   * Root url
+   */
+  private readonly rootUrl: string;
+
+  /**
+   * Get project path from issue
+   *
+   * @param issue Issue to get project from
+   */
+  static getProjectPath(issue: any): string {
+    const issuePath = issue.web_url.replace('https://gitlab.tubit.tu-berlin.de/', '');
+
+    return issuePath.substring(0, issuePath.indexOf('/issues/'));
+  }
+
+  /**
+   * Instantiate new GitLab API
+   *
+   * @param rootUrl Root URL of the GitLab API
+   * @param privateToken Private token for the GitLab API
+   */
+  constructor(rootUrl: string, privateToken: string) {
+    this.rootUrl = rootUrl;
+    this.privateToken = privateToken;
+  }
+
+  /**
+   * Add member to a group or a project
+   *
+   * @param scope Scope of the ID
+   * @param id ID of the group or project
+   * @param userId ID of the user
+   * @param accessLevel Access level for the new member in the scope
+   */
+  public addMember(scope: 'groups' | 'projects',
+                   id: number,
+                   userId: number,
+                   accessLevel: AccessLevel): Promise<Member> {
+    return this.makeGitLabAPIRequest(
+      scope + '/' + id + '/members',
+      {
+        data: {
+          access_level: accessLevel,
+          user_id: userId,
+        },
+        method: 'POST',
+      },
+    );
+  }
+
+  /**
+   * Create an issue in GitLab
+   *
+   * @param projectId ID of the project to create the issue in
+   * @param title Title of the issue
+   * @param description Description of the issue (can contain slash commands)
+   */
+  public createIssue(projectId: number, title: string, description: string): Promise<Issue> {
+    return this.makeGitLabAPIRequest(
+      'projects/' + projectId + '/issues',
+      {
+        data: {
+          description: description,
+          title: title,
+        },
+        method: 'POST',
+      },
+    );
+  }
+
+  /**
+   * Create a new label
+   *
+   * @param projectId ID of the project to create the label in
+   * @param name Name of the label to create
+   * @param description Description of the label to create
+   * @param color Color of the label to create
+   */
+  public createLabel(projectId: number, name: string, description?: string, color?: string): Promise<Label> {
+    if (typeof color !== 'string' || !color.match(/^#[0-9a-fA-F]{3,6}$/)) {
+      color = '#000000';
+    }
+
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/labels',
+      {
+        data: {
+          color: color,
+          description: description,
+          name: name,
+        },
+        method: 'POST',
+      },
+    );
+  }
+
+  /**
+   * Create a milestone in a project
+   *
+   * @param projectId Project ID to create milestone in
+   * @param title Title of the milestone to create
+   */
+  public createMilestone(projectId: number, title: string): Promise<void> {
+    return this.makeGitLabAPIRequest('/projects/' + projectId + '/milestones?title=' + title, {
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Create a note/comment in an issue
+   *
+   * @param projectId Project ID, the issue belongs to
+   * @param issueIid IID of the issue to create the note in
+   * @param body Body of the note to create
+   */
+  public createNote(projectId: number, issueIid: number, body: string): Promise<void> {
+    return this.makeGitLabAPIRequest(`projects/${projectId}/issues/${issueIid}/notes`, {
+      data: {
+        body,
+      },
+      method: 'POST',
+    });
+  }
+
+  /**
+   * Delete a label
+   *
+   * @param projectId ID of the project to delete the label from
+   * @param name Name of the label to delete
+   */
+  public deleteLabel(projectId: number, name: string): Promise<void> {
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/labels',
+      {
+        data: {
+          name: name,
+        },
+        method: 'DELETE',
+      },
+    );
+  }
+
+  /**
+   * Delete a member from a group or a project
+   *
+   * @param scope Scope of the ID
+   * @param id ID of the group or project
+   * @param userId ID of the user
+   */
+  public deleteMember(scope: 'groups' | 'projects', id: number, userId: number): Promise<void> {
+    return this.makeGitLabAPIRequest(scope + '/' + id + '/members/' + userId, {method: 'DELETE'});
+  }
+
+  /**
+   * Edit an existing label
+   *
+   * @param projectId ID of the project to edit the label in
+   * @param name Name of the label to edit
+   * @param newValues New values for the label
+   */
+  public editLabel(projectId: number, name: string, newValues: Partial<Label>): Promise<Label> {
+    if (typeof newValues.color === 'string' && !newValues.color.match(/^#[0-9a-fA-F]{3,6}$/)) {
+      newValues.color = undefined;
+    }
+
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/labels',
+      {
+        data: {
+          color: newValues.color,
+          description: newValues.description,
+          name: name,
+          new_name: newValues.name,
+        },
+        method: 'POST',
+      },
+    );
+  }
+
+  /**
+   * Edit member in a group or a project
+   *
+   * @param scope Scope of the ID
+   * @param id ID of the group or project
+   * @param userId ID of the user
+   * @param accessLevel Access level for the member in the scope
+   */
+  public editMember(scope: 'groups' | 'projects',
+                    id: number,
+                    userId: number,
+                    accessLevel: AccessLevel): Promise<Member> {
+    return this.makeGitLabAPIRequest(
+      scope + '/' + id + '/members',
+      {
+        data: {
+          access_level: accessLevel,
+          user_id: userId,
+        },
+        method: 'PUT',
+      },
+    );
+  }
+
+  /**
+   * Get branches for a project
+   *
+   * @param projectId Project ID to get branches for
+   */
+  public getBranchesForProject(projectId: number): Promise<Branch[]> {
+    return this.makeGitLabAPIRequest('projects/' + projectId + '/repository/branches');
+  }
+
+  /**
+   * Get a file from GitLab
+   *
+   * @param projectId ID of the project the file belongs to
+   * @param filePath Path to the file - url encoded
+   * @param commitish Commitish of the file
+   */
+  public getFile(projectId: number, filePath: string, commitish: string): Promise<any> {
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/repository/files/' +
+      encodeURIComponent(filePath).replace('.', '%2E') + '/raw?ref=' + encodeURIComponent(commitish),
+    );
+  }
+
+  /**
+   * Get a list of files
+   *
+   * @param projectId ID of the project
+   */
+  public getFileList(projectId: number): Promise<TreeFile[]> {
+    return this.makeGitLabAPIRequest('projects/' + projectId + '/repository/tree');
+  }
+
+  /**
+   * Get issues
+   *
+   * @param options Options to get issues
+   */
+  public getIssues(options?: ApiGetIssuesOptions): Promise<Issue[]> {
+    // set 'Meeting' as default milestone
+    const _options: ApiGetIssuesOptions = {
+      ...{
+        milestone: 'Meeting',
+      },
+      ...options,
+    };
+
+    // start to build request url
+    let requestUrl = 'issues';
+
+    // request issues only for specific group, if group ID is set
+    if (typeof _options.groupId === 'number') {
+      requestUrl = 'groups/' + _options.groupId + '/' + requestUrl;
+    }
+
+    // add milestone to request url
+    requestUrl += '?milestone=' + _options.milestone;
+
+    // request issues only for specific state, if state is set
+    if (typeof _options.state === 'string' && ['opened', 'closed'].indexOf(_options.state) >= 0) {
+      requestUrl += '&state=' + _options.state;
+    }
+
+    return this.makeGitLabAPIRequest(requestUrl);
+  }
+
+  /**
+   * Get labels of a project
+   *
+   * @param projectId ID of the project to get the labels for
+   */
+  public getLabels(projectId: number): Promise<Label[]> {
+    return this.makeGitLabAPIRequest(
+      'projects/' + projectId + '/labels',
+    );
+  }
+
+  /**
+   * Get members of a group or a project
+   *
+   * @param scope Scope of the ID
+   * @param id ID of the group or project
+   */
+  public getMembers(scope: 'groups' | 'projects', id: number): Promise<Member[]> {
+    return this.makeGitLabAPIRequest(
+      scope + '/' + id + '/members',
+    );
+  }
+
+  /**
+   * Get merge requests for a project
+   *
+   * @param projectId Project ID to get merge requests for
+   */
+  public getMergeRequestsForProject(projectId: number): Promise<MergeRequest[]> {
+    return this.makeGitLabAPIRequest('projects/' + projectId + '/merge_requests?state=opened');
+  }
+
+  /**
+   * Get milestones for a project
+   *
+   * @param projectId Project ID to get milestones for
+   */
+  public getMilestonesForProject(projectId: number): Promise<Milestone[]> {
+    return this.makeGitLabAPIRequest('projects/' + projectId + '/milestones');
+  }
+
+  /**
+   * Get projects for a group
+   *
+   * @param groupId Group ID to get projects for
+   */
+  public getProjectsForGroup(groupId: number): Promise<Project[]> {
+    return this.makeGitLabAPIRequest('groups/' + groupId + '/projects');
+  }
+
+  /**
+   * Get tags of a project
+   *
+   * @param projectId ID of the project to get the tags for
+   */
+  public getTags(projectId: number): Promise<Tag[]> {
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/repository/tags',
+    );
+  }
+
+  /**
+   * Query a GitLab API URL
+   *
+   * @param url GitLab API URL to query
+   * @param _options HTTP method/verb
+   */
+  public async makeGitLabAPIRequest(url: string, _options?: ApiRequestOptions): Promise<any> {
+    url = url.replace(/^\/+/g, '');
+
+    const options: ApiRequestOptions = {
+      method: 'GET',
+      ..._options,
+    };
+
+    if (typeof options.method === 'string' && ['DELETE', 'GET', 'POST', 'PUT'].indexOf(options.method) === -1) {
+      options.method = 'GET';
+    }
+
+    let concatenator = '&';
+    if (url.indexOf('?') === -1) {
+      concatenator = '?';
+    }
+
+    let apiResult: any;
+    let totalPages = 1;
+    let currentPage = 0;
+
+    while (++currentPage <= totalPages) {
+      if (currentPage > 1) {
+        logger.info(`Automatically paging call to '${url}'... Getting page ${currentPage} of ${totalPages}.`);
+      }
+
+      let body;
+      let tries = 0;
+
+      while (typeof body === 'undefined' && tries++ < 5) {
+        try {
+          const requestUrl = url + concatenator + 'page=' + currentPage + '&per_page=100';
+
+          body = await request(this.rootUrl + requestUrl, {
+            form: typeof options.data !== 'undefined' ? options.data : undefined,
+            headers: {'PRIVATE-TOKEN': this.privateToken},
+            json: true,
+            method: options.method,
+            timeout: 60000,
+            transform: (bodyToTransform, response) => {
+              const xTotalPages = response.headers['x-total-pages'];
+
+              if (typeof xTotalPages === 'string') {
+                totalPages = parseInt(xTotalPages, 10);
+              }
+
+              return bodyToTransform;
+            },
+          });
+        } catch (error) {
+          if (error.error === 'GitLab is not responding') {
+            const seconds = 5;
+
+            logger.warn(`GitLab was not responding. Waiting ${seconds}s and retrying...`);
+
+            await sleep(seconds * 1000);
+
+            continue;
+          }
+
+          throw error;
+        }
+      }
+
+      if (options.method === 'DELETE') {
+        return;
+      }
+
+      if (Array.isArray(apiResult) && currentPage > 1) {
+        // add items to previously fetched items
+        apiResult = apiResult.concat(body);
+      } else {
+        // set (initial) result
+        apiResult = body;
+      }
+    }
+
+    return apiResult;
+  }
+
+  /**
+   * Protect a branch
+   *
+   * @param projectId ID of the project the branch belongs to
+   * @param branch Branch to protect
+   */
+  public protectBranch(projectId: number, branch: string): Promise<Branch> {
+    return this.makeGitLabAPIRequest(
+      '/projects/' + projectId + '/repository/branches/' + branch + '/protect' +
+      '?developers_can_push=false&developers_can_merge=false',
+      {
+        method: 'PUT',
+      },
+    );
+  }
+
+  /**
+   * Set assignee for an issue
+   *
+   * @param issue Issue to set milestone for
+   * @param userId ID of the milestone to set for the issue
+   */
+  public setAssigneeForIssue(issue: any, userId: number): Promise<Issue> {
+    return this.makeGitLabAPIRequest(
+      'projects/' + issue.project_id + '/issues/' + issue.iid + '?assignee_ids=' + userId,
+      {
+        method: 'PUT',
+      },
+    );
+  }
+
+  /**
+   * Set milestone for an issue
+   *
+   * @param issue Issue to set milestone for
+   * @param milestoneId ID of the milestone to set for the issue
+   */
+  public setMilestoneForIssue(issue: any, milestoneId: number): Promise<Issue> {
+    if (milestoneId === null) {
+      return this.makeGitLabAPIRequest(
+        'projects/' + issue.project_id + '/issues/' + issue.iid + '?milestone_id=',
+        {
+          method: 'PUT',
+        },
+      );
+    }
+
+    return this.makeGitLabAPIRequest(
+      'projects/' + issue.project_id + '/issues/' + issue.iid + '?milestone_id=' + milestoneId,
+      {
+        method: 'PUT',
+      },
+    );
+  }
+}

src/cli.ts

@@ -0,0 +1,65 @@
+/*
+ * Copyright (C) 2018 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import * as commander from 'commander';
+import {readFileSync} from 'fs';
+import {join} from 'path';
+import {Api, ApiRequestOptions, logger} from './api';
+
+const pkgJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json')).toString());
+
+commander
+  .version(pkgJson.version);
+
+commander
+  .option('-u, --url [url]', 'GitLab API URL', 'https://gitlab.com/api/v4/')
+  .option('-c, --call <call>', 'API call/sub url')
+  .option('-m, --method [method]', 'HTTP verb to use for the API call', 'GET')
+  .option('-d, --data [data]', 'JSON representation of data to send');
+
+commander
+  .parse(process.argv);
+
+if (typeof commander.call === 'undefined') {
+  commander.outputHelp();
+  process.exit(1);
+}
+
+if (typeof commander.token === 'undefined') {
+  if (typeof process.env.GITLAB_PRIVATE_TOKEN === 'undefined') {
+    logger.error('You have to supply ');
+  }
+
+  commander.token = process.env.GITLAB_PRIVATE_TOKEN;
+}
+
+const gitLabApi = new Api(commander.url, commander.token);
+
+const options: ApiRequestOptions = {};
+
+if (commander.method !== 'GET') {
+  options.method = commander.method;
+}
+
+if (typeof commander.data !== 'undefined') {
+  options.data = JSON.parse(commander.data);
+}
+
+gitLabApi.makeGitLabAPIRequest(commander.call, options).then((result) => {
+  logger.ok(result);
+  process.exit(1);
+}, (err) => {
+  logger.error(err);
+  process.exit(1);
+});

src/types.ts

@@ -0,0 +1,241 @@
+/*
+ * Copyright (C) 2018 StApps
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * GitLab label
+ */
+export interface Label {
+  color: string;
+  description?: string;
+  name: string;
+}
+
+/**
+ * GitLab commit
+ */
+export interface GitLabCommit {
+  author_email: string;
+  author_name: string;
+  authored_date: string;
+  committed_date: string;
+  committer_email: string;
+  committer_name: string;
+  id: string;
+  message: string;
+  parent_ids: string[];
+}
+
+/**
+ * GitLab tag
+ */
+export interface Tag {
+  commit: GitLabCommit;
+  message: string | null;
+  name: string;
+  release: null;
+}
+
+/**
+ * GitLab namespace
+ */
+export interface GitLabNamespace {
+  full_path: string;
+  id: number;
+  kind: string;
+  name: string;
+  path: string;
+}
+
+/**
+ * GitLab project
+ */
+export interface Project {
+  archived: boolean;
+  avatar_url: string;
+  container_registry_enabled: boolean;
+  created_at: string;
+  creator_id: number;
+  default_branch: string;
+  description: string;
+  forks_count: number;
+  http_url_to_repo: string;
+  id: number;
+  issues_enabled: boolean;
+  jobs_enabled: boolean;
+  last_activity_at: string;
+  lfs_enabled: boolean;
+  merge_requests_enabled: boolean;
+  name: string;
+  name_with_namespace: string;
+  namespace: GitLabNamespace;
+  only_allow_merge_if_all_discussions_are_resolved: boolean;
+  only_allow_merge_if_pipeline_succeeds: boolean;
+  open_issues_count: number;
+  path: string;
+  path_with_namespace: string;
+  public_jobs: boolean;
+  request_access_enabled: boolean;
+  shared_runners_enabled: boolean;
+  shared_with_groups: any[];
+  snippets_enabled: boolean;
+  ssh_url_to_repo: string;
+  star_count: number;
+  tag_list: string[];
+  visibility: string;
+  web_url: string;
+  wiki_enabled: boolean;
+}
+
+/**
+ * GitLab tree file
+ */
+export interface TreeFile {
+  id: string;
+  mode: string;
+  name: string;
+  path: string;
+  type: string;
+}
+
+/**
+ * A member of a group or a project
+ */
+export interface Member extends GitLabUser {
+  access_level: AccessLevel;
+  expires_at: string;
+}
+
+/**
+ * Available GitLab access levels
+ */
+export enum AccessLevel {
+  Guest = 10,
+  Reporter = 20,
+  Developer = 30,
+  Maintainer = 40,
+  Owner = 50,
+}
+
+/**
+ * A GitLab milestone
+ */
+export interface Milestone {
+  created_at: string;
+  description: string | null;
+  due_date: string;
+  id: number;
+  iid: number;
+  project_id: number;
+  start_date: string;
+  state: string;
+  title: string;
+  updated_at: string;
+}
+
+/**
+ * A GitLab branch
+ */
+export interface Branch {
+  commit: GitLabCommit;
+  developers_can_merge: boolean;
+  developers_can_push: boolean;
+  merged: boolean;
+  name: string;
+  protected: boolean;
+}
+
+/**
+ * A GitLab user
+ */
+export interface GitLabUser {
+  avatar_url: string;
+  id: number;
+  name: string;
+  state: string;
+  username: string;
+  web_url: string;
+}
+
+/**
+ * A GitLab issue
+ */
+export interface Issue extends GitLabThingWithTimeStats {
+  assignee: GitLabUser;
+  assignees: GitLabUser[];
+  author: GitLabUser;
+  closed_at: string | null;
+  confidential: boolean;
+  created_at: string;
+  description: string | null;
+  discussion_locked: boolean | null;
+  downvotes: number;
+  due_date: string | null;
+  id: number;
+  iid: number;
+  labels: string[];
+  milestone: Milestone | null;
+  project_id: number;
+  state: string;
+  title: string;
+  updated_at: string;
+  upvotes: number;
+  user_notes_count: number;
+  web_url: string;
+}
+
+/**
+ * A GitLab merge request
+ */
+export interface MergeRequest extends GitLabThingWithTimeStats {
+  assignee: GitLabUser;
+  author: GitLabUser;
+  created_at: string;
+  description: string | null;
+  discussion_locked: boolean | null;
+  downvotes: number;
+  force_remove_source_branch: boolean;
+  id: number;
+  iid: number;
+  labels: Label[];
+  merge_commit_sha: string;
+  merge_status: string;
+  merge_when_pipeline_succeeds: boolean;
+  milestone: Milestone;
+  project_id: number;
+  sha: string;
+  should_remove_source_branch: boolean;
+  source_branch: string;
+  source_project_id: number;
+  state: string;
+  target_branch: string;
+  target_project_id: number;
+  title: string;
+  updated_at: string;
+  upvotes: number;
+  user_notes_count: number;
+  web_url: string;
+  work_in_progress: boolean;
+}
+
+/**
+ * A GitLab thing with time stats
+ */
+export interface GitLabThingWithTimeStats {
+  time_stats: {
+    human_time_estimate: number | null;
+    human_total_time_spent: number | null;
+    time_estimate: number;
+    total_time_spent: number;
+  };
+}