githubApiGet.ts

// githubApi.ts

import fetch from "node-fetch";
import jp from "jsonpath";
import { GITHUB_API_BASE_URL, GITHUB_PROJECT_TOPICS } from "./consts.js";

// const isProd = false; // import.meta.env.PROD; // false;

/**
 * Returns the github project info - reduce with pathExpression constants.
 *
 * @remarks
 * This method is part of the {@link githubApiGet | github-api-get}.
 *
 * @param {string} loginName - The github login name
 * @param {string} projectName - The github project name
 * @param {string} pathExpression - The path expression to reduce the project info
 * @param {boolean} infoLog - true Logs group and info into the console
 * @param {boolean} isProd - true Calls fetch to github api, false returns mock data with same structure
 * @returns {Promise<unknown>} The github topics of a project
 */
export async function githubApiGetProject(
  loginName: string,
  projectName: string,
  pathExpression: string,
  infoLog: boolean,
  isProd: boolean,
): Promise<unknown> {
  if (infoLog) {
    console.group("githubApiGetProject");
  }
  if (loginName && projectName) {
    if (infoLog) {
      console.info("githubApi.ts githubApiGetProject(): loginName: " + loginName);
      console.info("githubApi.ts githubApiGetProject(): projectName: " + projectName);
    }
    if (infoLog) {
      console.groupEnd();
    }
    // https://www.npmjs.com/package/jsonpath MIT License
    return Promise.resolve(jp.query(await returnData(loginName, projectName, infoLog, isProd), pathExpression));
  } else {
    if (infoLog) {
      console.groupEnd();
    }
    return Promise.resolve({} as Array<string>);
  }
}

/**
 * Returns the github login info - reduce with pathExpression constants.
 *
 * @remarks
 * This method is part of the {@link githubApiGet | github-api-get}.
 *
 * @param {string} loginName - The github login name
 * @param {string} pathExpression - The path expression to reduce the login info
 * @param {boolean} infoLog - true Logs group and info into the console
 * @param {boolean} isProd - true Calls fetch to github api, false returns mock data with same structure
 * @returns {Promise<unknown>} The github login info
 */
export async function githubApiGetLogin(
  loginName: string,
  pathExpression: string,
  infoLog: boolean,
  isProd: boolean,
): Promise<unknown> {
  if (infoLog) {
    console.group("githubApiGetLogin");
  }
  if (loginName) {
    if (infoLog) {
      console.info("githubApi.ts githubApiGetLogin(): loginName: " + loginName);
    }
    if (infoLog) {
      console.groupEnd();
    }
    // https://www.npmjs.com/package/jsonpath MIT License
    return Promise.resolve(jp.query(await returnData(loginName, "", infoLog, isProd), pathExpression));
  } else {
    if (infoLog) {
      console.groupEnd();
    }
    return Promise.resolve({});
  }
}

/**
 * Returns the github topics of a project.
 *
 * @deprecated
 * use githubApiGetProject() with pathExpression constant GITHUB_PROJECT_TOPICS
 *
 * @remarks
 * This method is part of the {@link githubApiGet | github-api-get}.
 *
 * @param {string} loginName - The github login name
 * @param {string} projectName - The github project name
 * @param {boolean} infoLog - true Logs group and info into the console
 * @param {boolean} isProd - true Calls fetch to github api, false returns mock data with same structure
 * @returns {Promise<string[]>} The github topics of a project
 */
export async function getGithubTopics(
  loginName: string,
  projectName: string,
  infoLog: boolean,
  isProd: boolean,
): Promise<string[]> {
  if (infoLog) {
    console.group("getGithubTopics");
  }
  if (loginName && projectName) {
    if (infoLog) {
      console.info("githubApi.ts: loginName: " + loginName);
      console.info("githubApi.ts: projectName: " + projectName);
    }
    if (infoLog) {
      console.groupEnd();
    }
    let githubProjectTopics = await githubApiGetProject(loginName, projectName, GITHUB_PROJECT_TOPICS, infoLog, isProd);
    if (isStringArray(githubProjectTopics)) {
      return Promise.resolve(githubProjectTopics as string[]);
    } else {
      return Promise.resolve(["getGithubTopics_Error_in_Implementation_of_GithubApiGetProject"] as Array<string>);
    }
  } else {
    if (infoLog) {
      console.groupEnd();
    }
    return Promise.resolve([] as Array<string>);
  }
}

/**
 * is String Array.
 *
 * @param {string} value - A value
 * @returns {boolean} true if the value is a String Array, else false
 *
 */
function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((element) => typeof element === "string");
}

/**
 * Returns the github project object / json of a project if with projectName, return the github login of a user object / json of a login of a user.
 *
 * @param {string} loginName - The github login name
 * @param {string} projectName - The github project name - not empty for project info, empty for login of a user info
 * @param {boolean} infoLog - true Logs group and info into the console
 * @param {boolean} isProd - true Calls fetch to github api, false returns mock data with same structure
 * @returns {Promise<any>} The github the project object / json of a project
 */
async function returnData(loginName: string, projectName: string, infoLog: boolean, isProd: boolean) {
  if (isProd) {
    if (projectName !== "") {
      // get from github project api
      const GITHUB_API_PROJECT_URL = GITHUB_API_BASE_URL + "repos/" + loginName + "/";

      const response = await fetch(GITHUB_API_PROJECT_URL + projectName);
      if (!response.ok) {
        if (infoLog) {
          console.info(
            "API rate limit exceeded for nnn.nnn.nnn.nnn. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
          );
          console.info("https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting");
        }
        // Github has a Rate Limit
        // in this case Status is 403 Forbidden
        // and return this Message Object / Json:
        // {
        //   message: "API rate limit exceeded for nnn.nnn.nnn.nnn. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
        //   documentation_url: 'https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting'
        // }
      }
      return await response.json();
    } else {
      // get from github login of a user api
      const GITHUB_API_LOGIN_URL = GITHUB_API_BASE_URL + "users/" + loginName;

      const response = await fetch(GITHUB_API_LOGIN_URL);
      if (!response.ok) {
        if (infoLog) {
          console.info(
            "API rate limit exceeded for nnn.nnn.nnn.nnn. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
          );
          console.info("https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting");
        }
        // Github has a Rate Limit
        // in this case Status is 403 Forbidden
        // and return this Message Object / Json:
        // {
        //   message: "API rate limit exceeded for nnn.nnn.nnn.nnn. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
        //   documentation_url: 'https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting'
        // }
      }
      return await response.json();
    }
  } else {
    // return mock data
    if (projectName !== "") {
      // return mockdata of a project
      // based on
      // 01-01-vanilla-HTML5-starter-page.json
      return Promise.resolve({
        name: "01-01-vanilla-HTML5-starter-page",
        owner: {
          login: "roebi",
        },
        html_url: "https://github.com/roebi/01-01-vanilla-HTML5-starter-page",
        description: "vanilla HTML 5 starter page - Have you ever heard of this HTML 5 tags ?",
        url: "https://api.github.com/repos/roebi/01-01-vanilla-HTML5-starter-page",
        homepage: "https://roebi.github.io/01-01-vanilla-HTML5-starter-page/",
        license: {
          key: "unlicense",
        },
        topics: [" mockdata!", "html5", "html5-template", "roebi", "starter"],
      });
    } else {
      // return mockdata of a login of a user
      // based on
      // roebi.json
      return Promise.resolve({
        login: "roebi",
        avatar_url: "https://avatars.githubusercontent.com/u/3611826?v=4",
        url: "https://api.github.com/users/roebi",
        html_url: "https://github.com/roebi",
        location: "Switzerland",
        bio: "...",
      });
    }
  }
}