CheckRun.ts

import {ChecksUpdateResponse, ChecksUpdateParamsOutput, ChecksCreateResponse, Response, ReposCompareCommitsResponse} from '@octokit/rest';
import {WebhookPayloadCheckRun, WebhookPayloadCheckSuite, WebhookPayloadPullRequest} from '@octokit/webhooks';

import {GitHubAPI} from 'probot/lib/github';
import {Context} from 'probot/lib/context';
import {Logger} from 'probot/lib';

export default class CheckRun {
  public context: Context;
  public github: GitHubAPI;
  public payload: WebhookPayloadCheckSuite | WebhookPayloadCheckRun | WebhookPayloadPullRequest;
  public logger: Logger;
  public action: string;

  public name: string;
  public id: number | undefined;

  /**
   * @param {String} name Name of the Check as it appears in the Checks UI. This name is used to
   *     reference Checks when re-running them.
   * @param {Context} event Probot event context
   */
  constructor(name: string, event: Context) {
    this.name = name;
    this.context = event;
    this.github = event.github;
    this.payload = event.payload;
    this.action = event.payload.action;
    this.logger = event.log;
  }

  /**
   * Helper getter to gather the common API options needed for most Check API queries. Tries its
   * best to figure out if there's a Pull Request attached to the payload and uses that as its
   * head sha for doing comparisons against.
   */
  get options() {
    const payloadData = (this.payload as WebhookPayloadCheckSuite).check_suite || (this.payload as WebhookPayloadCheckRun).check_run;
    const pr = (this.payload as WebhookPayloadPullRequest).pull_request;

    return {
      owner: this.payload.repository.owner.login,
      repo: this.payload.repository.name,
      head_sha: payloadData && payloadData.head_sha || pr && pr.head.sha,
      name: this.name,
    };
  }

  /**
   * Function called to createa a Check Run. When extending this Class, you have the option of 
   * instead returning false instead of calling this super function to prevent the Check from 
   * getting queued. This is useful for Checks that only start in specific situations as opposed
   * to on every Check webhook event.
   * 
   * https://developer.github.com/v3/checks/runs/#create-a-check-run
   */
  async start(): Promise<Response<ChecksCreateResponse>|false> {
    try {
      const resp: Response<ChecksCreateResponse> = await this.github.checks.create(Object.assign({
        status: 'queued' as 'queued',
      }, this.options));

      this.id = resp.data.id;
      return resp;
    } catch (e) {
      this.logger.warn(e);
      return false;
    }
  }

  /**
   * Updates the status of a previosly created CheckRun. By default, will set the status to "in_progress"
   * https://developer.github.com/v3/checks/runs/#update-a-check-run
   * 
   * @param {String} status The CheckRun's status in the Checks API.
   * @param {String} conclusion If the CheckRun has finished running, the final outcome of the run.
   *     Automatically sets the status to "completed" if set.
   * @param {ChecksUpdateParamsOutput} output Output options given to the Check API, usually 
   *     containing a "title", a "summary", and "text".
   * @param {String} details_url URL that contains more details about the run.
   */
  async update(
      status: 'queued' | 'in_progress' | 'completed' = 'in_progress',
      conclusion?: 'success' | 'failure' | 'neutral' | 'cancelled' | 'timed_out'
          | 'action_required',
      output?: ChecksUpdateParamsOutput,
      details_url?: string
  ): Promise<Response<ChecksUpdateResponse>> {
    return this.github.checks.update({
      ...this.options,
      check_run_id: this.id as number,
      status,
      conclusion,
      ...status === 'completed' && {completed_at: new Date().toISOString()},
      ...output && {output},
      details_url,
    });
  }

  /**
   * Convenience function that updates the status to completed as either "success" or "failure"
   * based on the success parameter.
   * 
   * @param {Boolean} success Whether or not the run passed or failed.
   * @param {ChecksUpdateParamsOutput} output Output options given to the Check API, usually
   *     containing a "title", a "summary", and "text".
   */
  async finish(success: boolean, output?: ChecksUpdateParamsOutput):
      Promise<Response<ChecksUpdateResponse>> {
    return this.github.checks.update({
      ...this.options,
      check_run_id: this.id as number,
      conclusion: success ? 'success' as 'success' : 'failure' as 'failure',
      completed_at: new Date().toISOString(),
      ...success ? {} : {output},
    });
  }

  /**
   * Convenience function that updates the status to "neutral". Neutral Check Runs are those that
   * neither approve nor block a PR.
   */
  async neutral(): Promise<Response<ChecksUpdateResponse>> {
    return this.github.checks.update({
      ...this.options,
      check_run_id: this.id as number,
      conclusion: 'neutral',
      completed_at: new Date().toISOString(),
    });
  }
}