@stats-forge/github-stats-forge-core 0.0.1

package/src/common/retryer.ts

@@ -0,0 +1,111 @@
+import type { CardConfig } from './config.js';
+import { CardError } from './error.js';
+import type { FetcherContext, HttpResponse } from './http.js';
+import { logger } from './log.js';
+
+/**
+ * Error-detection fields the retryer inspects to detect rate-limiting and credential failures.
+ * Every fetcher's payload is intersected with
+ * this, so the retryer can read `errors`/`message` regardless of the payload's own shape.
+ */
+interface ResponseErrors {
+  errors?: Array<{ type?: string; message?: string }>;
+  message?: string;
+}
+
+/**
+ * Returns a random integer from 0 (inclusive) to `max` (exclusive).
+ *
+ * The value is generated using `Math.random()` and uniformly distributed
+ * across the range.
+ *
+ * @param max The upper bound (exclusive). Must be a positive number.
+ *
+ * @returns A random integer `n` such that `0 <= n < max`.
+ */
+function getRandomInt(max: number): number {
+  return Math.floor(Math.random() * max);
+}
+
+/**
+ * A fetcher's response. `TData` is the shape of `response.data`,
+ * which is intersected with {@link ResponseErrors} so the retryer can inspect
+ * `errors`/`message`.
+ * Defaults to `unknown` (error fields only) for callers that don't care about the payload.
+ */
+type FetcherResponse<TData = unknown> = HttpResponse<TData & ResponseErrors>;
+
+type FetcherFunction<TData = unknown, TVariables = Record<string, unknown>> = (
+  variables: TVariables,
+  token: string,
+  context: FetcherContext,
+) => Promise<FetcherResponse<TData>>;
+
+/**
+ * Try to execute the fetcher function until it succeeds or the max number of retries is reached.
+ *
+ * @template TData Shape of `response.data` returned by the fetcher.
+ * @template TVariables Variables the fetcher accepts.
+ * @param fetcher The fetcher function.
+ * @param variables Object with arguments to pass to the fetcher function.
+ * @param config Deployment config supplying the PAT pool and the transport.
+ * @returns The response from the fetcher function.
+ */
+const retryer = async <TData = unknown, TVariables = Record<string, unknown>>(
+  fetcher: FetcherFunction<TData, TVariables>,
+  variables: TVariables,
+  config: CardConfig,
+): Promise<FetcherResponse<TData>> => {
+  const PATs = config.pats;
+
+  if (!PATs.length) {
+    throw new CardError('No GitHub API tokens found', { code: 'no_tokens' });
+  }
+  const startPAT = getRandomInt(PATs.length);
+
+  for (let retries = 0; retries < PATs.length; retries++) {
+    const currentPAT = PATs[(startPAT + retries) % PATs.length];
+    if (!currentPAT) {
+      continue;
+    }
+
+    // a non-2xx comes back as a response, so only a transport failure throws — and that is fatal
+    const response = await fetcher(variables, currentPAT.value, {
+      fetch: config.fetch,
+      retries,
+    });
+
+    // react on both type and message-based rate-limit signals.
+    // https://github.com/anuraghazra/github-readme-stats/issues/4425
+    const errors = response.data.errors;
+    const errorType = errors?.[0]?.type;
+    const errorMsg = errors?.[0]?.message ?? '';
+    const isRateLimited =
+      (!!errors && errorType === 'RATE_LIMITED') || /rate limit/i.test(errorMsg);
+
+    if (isRateLimited) {
+      logger.log(`${currentPAT.name} Failed due to rate limiting`);
+      continue;
+    }
+
+    // also checking for bad credentials if any tokens gets invalidated
+    const message = response.data.message;
+    const isBadCredential = message === 'Bad credentials';
+    const isAccountSuspended = message === 'Sorry. Your account was suspended.';
+
+    if (isBadCredential || isAccountSuspended) {
+      logger.log(`${currentPAT.name} Failed due to bad credentials`);
+      continue;
+    }
+
+    // anything else — including an HTTP error — is the caller's to interpret
+    return response;
+  }
+
+  throw new CardError('Downtime due to GitHub API rate limiting', {
+    code: 'rate_limited',
+  });
+};
+
+export { retryer };
+export type { FetcherResponse };

package/src/fetchers/gist.ts

@@ -0,0 +1,82 @@
+import type { CardConfig } from '../common/config.js';
+import { CardError, GIST_NOT_FOUND } from '../common/error.js';
+import { createGraphQLFetcher } from '../common/http.js';
+import { retryer } from '../common/retryer.js';
+import { GistInfoDocument } from '../graphql/generated/gist.js';
+import type { GistFileInfoFragment } from '../graphql/generated/gist.js';
+
+import type { GistData } from './types.js';
+
+const fetcher = createGraphQLFetcher(GistInfoDocument, 'token');
+
+/**
+ * This function calculates the primary language of a gist by files size.
+ *
+ * @param files Files.
+ * @returns Primary language, or `null` when no file has a language.
+ */
+const calculatePrimaryLanguage = (files: Array<GistFileInfoFragment>): string | null => {
+  const languages: Record<string, number> = {};
+
+  for (const file of files) {
+    if (file.language) {
+      languages[file.language.name] = (languages[file.language.name] ?? 0) + (file.size ?? 0);
+    }
+  }
+
+  let primaryLanguage: string | null = null;
+  let maxSize = -1;
+  for (const [language, size] of Object.entries(languages)) {
+    if (size > maxSize) {
+      maxSize = size;
+      primaryLanguage = language;
+    }
+  }
+
+  return primaryLanguage;
+};
+
+/**
+ * Fetch GitHub gist information by given username and ID.
+ *
+ * @param props Fetcher props.
+ * @param props.id GitHub gist ID.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns Gist data.
+ */
+const fetchGist = async (
+  { id }: { id: string | undefined },
+  config: CardConfig,
+): Promise<GistData> => {
+  if (!id) {
+    throw CardError.missingParam(['id'], '/api/gist?id=GIST_ID');
+  }
+  const res = await retryer(fetcher, { gistName: id }, config);
+  if (res.data.errors) {
+    throw new CardError(res.data.errors[0]?.message ?? 'Could not fetch gist.', {
+      code: 'upstream',
+    });
+  }
+  const gist = res.data.data.viewer.gist;
+  if (!gist) {
+    throw new CardError('Gist not found', {
+      code: 'not_found',
+      secondaryMessage: GIST_NOT_FOUND,
+    });
+  }
+  const firstFile = gist.files?.[0];
+  if (!firstFile?.name) {
+    // A gist with nothing to render will not gain a file on a retry.
+    throw new CardError('Gist has no files', { code: 'not_found' });
+  }
+  return {
+    name: firstFile.name,
+    nameWithOwner: `${gist.owner?.login ?? ''}/${firstFile.name}`,
+    description: gist.description,
+    language: calculatePrimaryLanguage(gist.files?.filter((file) => !!file) ?? []),
+    starsCount: gist.stargazerCount,
+    forksCount: gist.forks.totalCount,
+  };
+};
+
+export { fetchGist };

package/src/fetchers/index.ts

@@ -0,0 +1,25 @@
+export { fetchGist } from './gist.js';
+export { fetchRepo } from './repo.js';
+export { fetchRepoUserStats, fetchStats } from './stats.js';
+export { fetchTopLanguages } from './top-languages.js';
+export { fetchWakatimeStats } from './wakatime.js';
+
+export type {
+  GistData,
+  Lang,
+  RepoUserStats,
+  RepositoryData,
+  StatsData,
+  TopLangData,
+  WakaTimeData,
+  WakaTimeLang,
+} from './types.js';
+
+// every fetcher takes a config, so this entry carries it rather than sending a
+// consumer back to the package root for it.
+export { CardConfig } from '../common/config.js';
+export type { CardConfigInit, PersonalAccessToken } from '../common/config.js';
+export type { FetchLike } from '../common/http.js';
+export { retryer } from '../common/retryer.js';
+export { CardError } from '../common/error.js';
+export type { ErrorCode } from '../common/error.js';

package/src/fetchers/repo.ts

@@ -0,0 +1,140 @@
+import type { CardConfig } from '../common/config.js';
+import { CardError, REPO_NOT_FOUND } from '../common/error.js';
+import { createGraphQLFetcher } from '../common/http.js';
+import { retryer } from '../common/retryer.js';
+import { GetRepoDocument } from '../graphql/generated/repo.js';
+
+import { fetchRepoUserStats } from './stats.js';
+import type { RepositoryData } from './types.js';
+
+const fetcher = createGraphQLFetcher(GetRepoDocument, 'token');
+
+const urlExample = '/api/pin?username=USERNAME&repo=REPO_NAME';
+
+/**
+ * Fetch repository data.
+ *
+ * @param props Fetcher props.
+ * @param props.username GitHub username.
+ * @param props.reponame GitHub repository name.
+ * @param props.include_prs_authored Include count of PRs authored.
+ * @param props.include_prs_commented Include count of PRs commented.
+ * @param props.include_prs_reviewed Include count of PRs reviewed.
+ * @param props.include_issues_authored Include count of issues authored.
+ * @param props.include_issues_commented Include count of issues commented.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns Repository data.
+ */
+const fetchRepo = async (
+  {
+    username,
+    reponame,
+    include_prs_authored = false,
+    include_prs_commented = false,
+    include_prs_reviewed = false,
+    include_issues_authored = false,
+    include_issues_commented = false,
+  }: {
+    username: string | undefined;
+    reponame: string | undefined;
+    include_prs_authored?: boolean | undefined;
+    include_prs_commented?: boolean | undefined;
+    include_prs_reviewed?: boolean | undefined;
+    include_issues_authored?: boolean | undefined;
+    include_issues_commented?: boolean | undefined;
+  },
+  config: CardConfig,
+): Promise<RepositoryData> => {
+  let owner = username;
+  if (reponame && reponame.includes('/')) {
+    const [parsedOwner, parsedRepo] = reponame.split('/');
+    owner = parsedOwner ?? '';
+    reponame = parsedRepo ?? '';
+  }
+
+  if (owner && !username) {
+    username = owner;
+  }
+  if (username && !owner) {
+    owner = username;
+  }
+  if (!username && !reponame) {
+    throw CardError.missingParam(['username', 'repo'], urlExample);
+  }
+  if (!username) {
+    throw CardError.missingParam(['username'], urlExample);
+  }
+  if (!reponame) {
+    throw CardError.missingParam(['repo'], urlExample);
+  }
+
+  // the guards above leave `username` set, and `owner` mirrors it when `repo` carried none
+  const repoOwner = owner ?? username;
+
+  const res = await retryer(fetcher, { login: repoOwner, repo: reponame }, config);
+
+  const data = res.data.data;
+
+  if (!data.user && !data.organization) {
+    throw new CardError('Not found', {
+      code: 'not_found',
+      secondaryMessage: REPO_NOT_FOUND,
+    });
+  }
+
+  if (data.organization === null && data.user) {
+    const repository = data.user.repository;
+    if (!repository || repository.isPrivate) {
+      throw new CardError('User Repository Not found', {
+        code: 'not_found',
+        secondaryMessage: REPO_NOT_FOUND,
+      });
+    }
+    const repoUserStats = await fetchRepoUserStats(
+      {
+        username,
+        repo: [`${repoOwner}/${reponame}`],
+        include_prs_authored,
+        include_prs_commented,
+        include_prs_reviewed,
+        include_issues_authored,
+        include_issues_commented,
+      },
+      config,
+    );
+    return {
+      ...repoUserStats,
+      ...repository,
+    };
+  }
+
+  if (data.user === null && data.organization) {
+    const repository = data.organization.repository;
+    if (!repository || repository.isPrivate) {
+      throw new CardError('Organization Repository Not found', {
+        code: 'not_found',
+        secondaryMessage: REPO_NOT_FOUND,
+      });
+    }
+    const repoUserStats = await fetchRepoUserStats(
+      {
+        username,
+        repo: [`${repoOwner}/${reponame}`],
+        include_prs_authored,
+        include_prs_commented,
+        include_prs_reviewed,
+        include_issues_authored,
+        include_issues_commented,
+      },
+      config,
+    );
+    return {
+      ...repoUserStats,
+      ...repository,
+    };
+  }
+
+  throw new CardError('Unexpected behavior', { code: 'upstream' });
+};
+
+export { fetchRepo };