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

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@stats-forge/github-stats-forge-core",
+  "version": "0.0.1",
+  "description": "Dynamically generate stats for your GitHub readme",
+  "keywords": [
+    "card-generator",
+    "cards",
+    "github-stats",
+    "github-stats-forge",
+    "readme-stats",
+    "stats-forge"
+  ],
+  "homepage": "https://github.com/stats-forge/github-stats-forge",
+  "bugs": {
+    "url": "https://github.com/stats-forge/github-stats-forge/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Anurag Hazra",
+    "url": "https://github.com/anuraghazra/"
+  },
+  "contributors": [
+    {
+      "name": "Rick Staa",
+      "url": "https://github.com/rickstaa"
+    },
+    {
+      "name": "Alexandr Garbuzov",
+      "url": "https://github.com/qwerty541"
+    },
+    {
+      "name": "Abhijit Gupta",
+      "url": "https://github.com/avgupta456"
+    },
+    {
+      "name": "Marco Pasqualetti",
+      "url": "https://github.com/marcalexiei"
+    },
+    {
+      "name": "martin-mfg",
+      "url": "https://github.com/martin-mfg"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stats-forge/github-stats-forge.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "build",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./build/index.js",
+  "exports": {
+    ".": {
+      "@stats/source": "./src/index.ts",
+      "default": "./build/index.js"
+    },
+    "./api": {
+      "@stats/source": "./src/api/index.ts",
+      "default": "./build/api/index.js"
+    },
+    "./cards": {
+      "@stats/source": "./src/cards/index.ts",
+      "default": "./build/cards/index.js"
+    },
+    "./fetchers": {
+      "@stats/source": "./src/fetchers/index.ts",
+      "default": "./build/fetchers/index.js"
+    },
+    "./themes": {
+      "@stats/source": "./src/themes/index.ts",
+      "default": "./build/themes/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "emoji-name-map": "^2.0.3",
+    "github-username-regex": "^1.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@graphql-codegen/core": "6.2.0",
+    "@graphql-codegen/typescript": "6.1.0",
+    "@graphql-codegen/typescript-operations": "6.1.2",
+    "@octokit/graphql-schema": "15.26.1",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.9.1",
+    "@uppercod/css-to-object": "1.1.1",
+    "graphql": "16.11.0",
+    "js-yaml": "5.2.1",
+    "jsdom": "29.1.1",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest",
+    "test:update:snapshot": "vitest -u",
+    "test:e2e": "vitest --config vitest.config.e2e.ts",
+    "bench": "vitest bench --run --config vitest.config.bench.ts",
+    "lint": "eslint",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "generate-graphql-types": "node scripts/generate-graphql-types",
+    "check-graphql-types": "node scripts/generate-graphql-types --check",
+    "generate-language-colors": "node scripts/generate-language-colors"
+  }
+}

package/src/_emoji-name-map.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `emoji-name-map` ships no type definitions and exposes no `exports` map, so it
+ * cannot be resolved under `nodenext`. Declare the minimal surface used here.
+ */
+declare module 'emoji-name-map' {
+  const emojiNameMap: {
+    get(name: string): string | undefined;
+  };
+  export default emojiNameMap;
+}

package/src/_github-username-regex.d.ts

@@ -0,0 +1,4 @@
+declare module 'github-username-regex' {
+  const githubUsernameRegex: RegExp;
+  export default githubUsernameRegex;
+}

package/src/api/api-result.ts

@@ -0,0 +1,69 @@
+import type { ColorParams } from '../common/color.js';
+import type { ErrorCode } from '../common/error.js';
+import { CardError } from '../common/error.js';
+import { renderError } from '../common/render.js';
+
+/**
+ * Why a card could not be rendered, in a form a host can act on.
+ * The same failure is also drawn onto the result's `content`,
+ * so a host never has to read the SVG to find out what happened.
+ */
+export interface ApiError {
+  /** Why it failed. */
+  code: ErrorCode;
+  /** First line of the error card. */
+  message: string;
+  /** Second line of the error card, when the code has more to say. */
+  secondaryMessage: string | undefined;
+  /**
+   * The first param at fault, when the failure names one.
+   * `missing_param` names every missing param in `message`, and not every
+   * `invalid_param` comes from a single param, so this can be absent.
+   */
+  param: string | undefined;
+}
+
+/** What every api handler returns: a rendered card, or a rendered error. */
+export type ApiResult =
+  | { status: 'success'; content: string }
+  | {
+      status: 'error';
+      /** Whether repeating the request could produce a different answer. */
+      retryable: boolean;
+      error: ApiError;
+      /** The error, drawn as a card. */
+      content: string;
+    };
+
+/**
+ * Turns anything a handler threw into the one shape it answers with.
+ *
+ * @param err The failure.
+ *        Anything that is not a `CardError` is treated as upstream's.
+ * @param renderOptions Colors the error card is drawn with;
+ *        omitted when it was a color that was rejected.
+ * @returns The rendered error.
+ */
+export const errorResult = (err: unknown, renderOptions?: ColorParams): ApiResult => {
+  const error = CardError.from(err);
+
+  return {
+    status: 'error',
+    retryable: error.retryable,
+    error: {
+      code: error.code,
+      message: error.message,
+      secondaryMessage: error.secondaryMessage,
+      param: error.param,
+    },
+    content: renderError({
+      message: error.message,
+      secondaryMessage: error.secondaryMessage,
+      renderOptions: {
+        ...renderOptions,
+        // A missing param is the caller's to fix, so the card links its docs instead.
+        show_repo_link: error.code !== 'missing_param',
+      },
+    }),
+  };
+};

package/src/api/gist.ts

@@ -0,0 +1,66 @@
+import * as z from 'zod/mini';
+
+import { renderGistCard } from '../cards/gist.js';
+import type { CardConfig } from '../common/config.js';
+import { fetchGist } from '../fetchers/gist.js';
+
+import type { ApiResult } from './api-result.js';
+import { errorResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+import { booleanParam, numberParam, parseColorParams, parseParams, safeParam } from './params.js';
+
+/** What the gist endpoint accepts, on top of the shared color params. */
+const gistQuery = z.object({
+  id: safeParam,
+  border_radius: numberParam,
+  show_owner: booleanParam,
+  browser_rendering: booleanParam,
+  hide_border: booleanParam,
+});
+
+/** The query this endpoint accepts, checked against the schema above. */
+type GistApiQuery = ApiQuery<typeof gistQuery>;
+
+/**
+ * Render the gist card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.id GitHub gist ID.
+ * @param query.border_radius Card border radius.
+ * @param query.show_owner Whether to show the gist owner.
+ * @param query.browser_rendering Whether the browser wraps the description text.
+ * @param query.hide_border Whether to hide the card border.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+export const gist = async (query: GistApiQuery, config: CardConfig): Promise<ApiResult> => {
+  let colors;
+  try {
+    colors = parseColorParams(query);
+  } catch (err) {
+    // A rejected color cannot be used to draw its own error card.
+    return errorResult(err);
+  }
+
+  try {
+    const { id, border_radius, show_owner, browser_rendering, hide_border } = parseParams(
+      gistQuery,
+      query,
+    );
+
+    const gistData = await fetchGist({ id }, config);
+
+    return {
+      status: 'success',
+      content: renderGistCard(gistData, {
+        ...colors,
+        border_radius,
+        show_owner,
+        browser_rendering,
+        hide_border,
+      }),
+    };
+  } catch (err) {
+    return errorResult(err, colors);
+  }
+};

package/src/api/index.ts

@@ -0,0 +1,16 @@
+export { gist } from './gist.js';
+export { pin } from './pin.js';
+export { stats } from './stats.js';
+export { topLangs } from './top-langs.js';
+export { wakatime } from './wakatime.js';
+
+export type { ApiError, ApiResult } from './api-result.js';
+
+// every handler but `wakatime` needs the PAT pool, and that one still needs the transport.
+export { CardConfig } from '../common/config.js';
+export type { CardConfigInit, PersonalAccessToken } from '../common/config.js';
+export type { FetchLike } from '../common/http.js';
+export type { ErrorCode } from '../common/error.js';
+
+export { themes } from '../themes/index.js';
+export type { ThemeName } from '../themes/index.js';

package/src/api/params.ts

@@ -0,0 +1,221 @@
+import * as z from 'zod/mini';
+
+import type { ColorParams } from '../common/color.js';
+import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.js';
+import { CardError } from '../common/error.js';
+import { parseArray, parseBoolean } from '../common/ops.js';
+import { isLocaleAvailable } from '../translations.js';
+
+/**
+ * @file The api layer is the trust boundary:
+ * a query string arrives as strings, and each endpoint declares what it accepts as a schema over them.
+ * Parsing happens here once;
+ * the render functions are handed typed values and keep their own defaults.
+ *
+ * `zod/mini` rather than `zod`:
+ * this package ships to the browser, and the functional API tree-shakes down to the checks used below.
+ */
+
+/** Every param arrives as a string, or not at all. */
+const rawParam = z.optional(z.string());
+
+/** Characters a username, repository, owner or gist id may contain. */
+const SAFE_PATTERN = /^[-\w/.,]+$/;
+
+/** What a check rejected a param for. */
+type Rejection = 'number' | 'year' | 'unsafe' | 'locale' | 'enum' | 'color';
+
+/**
+ * Every rejection the api can put on an error card, in one place.
+ * The param comes from the issue's own path, so no schema repeats its own name.
+ */
+const REJECTION_MESSAGES: Record<Rejection, (param: string) => string> = {
+  number: (param) => `Invalid number input for parameter "${param}"`,
+  year: (param) => `Invalid number input for parameter "${param}"`,
+  unsafe: (param) => `Parameter "${param}" contains unsafe characters`,
+  locale: () => 'Locale not found',
+  enum: (param) => `Incorrect ${param} input`,
+  color: (param) => `Invalid color input for parameter "${param}"`,
+};
+
+/**
+ * A check that words its own rejection:
+ * the message is built from the kind and the param's path rather than passed in.
+ *
+ * @param kind What the check rejects the param for.
+ * @param passes Whether a value is acceptable.
+ * @returns The check, ready for `.check()`.
+ */
+const rejects = (kind: Rejection, passes: (value: string) => boolean) =>
+  z.refine((value: unknown) => typeof value !== 'string' || passes(value), {
+    error: (issue) => REJECTION_MESSAGES[kind](String(issue.path?.[0] ?? '')),
+  });
+
+/**
+ * `?x=true` / `?x=false`.
+ * Anything else is `undefined`, which leaves the card's own default in place.
+ */
+const booleanParam = z.pipe(
+  rawParam,
+  // Narrowed: `parseBoolean` also takes booleans, which a query string cannot hold.
+  z.transform((value: string | undefined) => parseBoolean(value)),
+);
+
+/** Comma-separated values, empty when the param is absent. */
+const listParam = z.pipe(rawParam, z.transform(parseArray));
+
+/**
+ * A number the card cannot fall back from, so a malformed one is rejected here:
+ * a render-time guard would throw into the generic catch and read as a temporary error.
+ *
+ * `parseFloat`, matching the coercion `Card` performs internally, so `?border_radius=10px` still renders `rx="10"`.
+ * Yields the parsed number, or `undefined` when the param is absent.
+ */
+const numberParam: z.ZodMiniType<number | undefined, string | undefined> = z.pipe(
+  rawParam.check(rejects('number', (value) => Number.isFinite(parseFloat(value)))),
+  z.transform((value) => (value === undefined ? undefined : parseFloat(value))),
+);
+
+/**
+ * A number the card already falls back from — widths, counts, line heights:
+ * `NaN` reaches the renderer, which answers it with its own default.
+ */
+const looseIntParam = z.pipe(
+  rawParam,
+  z.transform((value) => (value === undefined ? undefined : parseInt(value, 10))),
+);
+
+/**
+ * A four-digit year.
+ * Anything else builds a `DateTime` GitHub rejects, so it is a permanent error here rather than a failed request later.
+ * Yields the year, or `undefined` when the param is absent.
+ */
+const yearParam: z.ZodMiniType<number | undefined, string | undefined> = z.pipe(
+  rawParam.check(rejects('year', (value) => /^\d{4}$/.test(value))),
+  z.transform((value) => (value === undefined ? undefined : Number(value))),
+);
+
+/**
+ * An id the fetchers put in a URL.
+ * Rejected before any request is made, and yielded unchanged otherwise.
+ */
+const safeParam: z.ZodMiniType<string | undefined, string | undefined> = rawParam.check(
+  rejects('unsafe', (value) => !value || SAFE_PATTERN.test(value)),
+);
+
+/**
+ * A comma-separated list of ids, checked before it is split.
+ * The safe pattern allows the commas, so one check covers the whole list.
+ * Yields the split values, empty when the param is absent.
+ */
+const safeListParam: z.ZodMiniType<Array<string>, string | undefined> = z.pipe(
+  safeParam,
+  z.transform(parseArray),
+);
+
+/**
+ * A locale the cards have translations for.
+ * One wording for every endpoint:
+ * the message names the param, as the number and color rejections do.
+ */
+const localeParam = z.pipe(
+  rawParam.check(rejects('locale', (value) => !value || isLocaleAvailable(value))),
+  z.transform((value) => value?.toLowerCase()),
+);
+
+/**
+ * A param the card only renders as one of a fixed set of values.
+ *
+ * @param values The accepted values, as the card that renders them declares them.
+ * @returns Schema yielding one of `values`, or `undefined` when absent.
+ */
+const enumParam = <const T extends ReadonlyArray<string>>(
+  values: T,
+): z.ZodMiniType<T[number] | undefined, string | undefined> =>
+  rawParam.check(rejects('enum', (value) => (values as ReadonlyArray<string>).includes(value)));
+
+/**
+ * Every color param an endpoint accepts, validated and picked in one pass.
+ *
+ * Theme params are `rawParam`:
+ * they name a theme, and an unknown name falls back to the default rather than being an error.
+ */
+const colorParamsSchema = z.object(
+  Object.fromEntries(
+    COLOR_PARAM_KEYS.map((key) => [
+      key,
+      THEME_PARAM_KEYS.includes(key)
+        ? rawParam
+        : rawParam.check(rejects('color', isValidColorInput)),
+    ]),
+  ),
+);
+
+/**
+ * The query an endpoint accepts, derived from its own schema.
+ * Every param is optional and every value a string, which is all a query string can carry;
+ * naming it lets a consumer typecheck the object it builds.
+ */
+type ApiQuery<TSchema extends z.ZodMiniType> = Partial<z.input<TSchema>> & ColorParams;
+
+/**
+ * Turns a rejection back into the error the api answers with.
+ * Every rejection is the query's fault, so they share one code
+ * and differ only in the message the check already worded.
+ *
+ * @param error What the schema rejected.
+ * @returns The failure, ready to render.
+ */
+const toCardError = (error: z.core.$ZodError): CardError => {
+  const issue = error.issues[0];
+  return CardError.invalidParam(String(issue?.path[0] ?? ''), issue?.message ?? 'Invalid input');
+};
+
+/**
+ * Runs a query through an endpoint's schema.
+ *
+ * Only the first rejection is reported:
+ * the error card has room for one line.
+ *
+ * @param schema The endpoint's schema.
+ * @param query Raw query params.
+ * @returns The parsed params.
+ * @throws {CardError} When the schema rejects a param.
+ */
+const parseParams = <TSchema extends z.ZodMiniType>(
+  schema: TSchema,
+  query: unknown,
+): z.output<TSchema> => {
+  const result = z.safeParse(schema, query);
+  if (!result.success) {
+    throw toCardError(result.error);
+  }
+  return result.data;
+};
+
+/**
+ * The color params, validated.
+ * Split from the endpoint's own schema because a rejected color cannot then be used to render its own error card.
+ *
+ * @param query Raw query params.
+ * @returns The color params.
+ * @throws {CardError} When a param does not hold a color or a gradient.
+ */
+const parseColorParams = (query: unknown): ColorParams => parseParams(colorParamsSchema, query);
+
+export type { ApiQuery };
+
+export {
+  booleanParam,
+  enumParam,
+  listParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  parseColorParams,
+  parseParams,
+  rawParam,
+  safeListParam,
+  safeParam,
+  yearParam,
+};

package/src/api/pin.ts

@@ -0,0 +1,126 @@
+import * as z from 'zod/mini';
+
+import { renderRepoCard } from '../cards/repo.js';
+import type { CardConfig } from '../common/config.js';
+import { fetchRepo } from '../fetchers/repo.js';
+
+import type { ApiResult } from './api-result.js';
+import { errorResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+import {
+  booleanParam,
+  listParam,
+  localeParam,
+  looseIntParam,
+  numberParam,
+  parseColorParams,
+  parseParams,
+  rawParam,
+  safeParam,
+} from './params.js';
+
+/** What the pin endpoint accepts, on top of the shared color params. */
+const pinQuery = z.object({
+  username: safeParam,
+  repo: safeParam,
+  hide_border: booleanParam,
+  card_width: looseIntParam,
+  show_owner: booleanParam,
+  browser_rendering: booleanParam,
+  show: listParam,
+  show_icons: booleanParam,
+  number_format: rawParam,
+  text_bold: booleanParam,
+  line_height: rawParam,
+  locale: localeParam,
+  border_radius: numberParam,
+  description_lines_count: looseIntParam,
+});
+
+/** The query this endpoint accepts, checked against the schema above. */
+type PinApiQuery = ApiQuery<typeof pinQuery>;
+
+/**
+ * Render the repository card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.username GitHub username the repository belongs to.
+ * @param query.repo Repository name.
+ * @param query.hide_border Whether to hide the card border.
+ * @param query.card_width Card width.
+ * @param query.show_owner Whether to show the repository owner.
+ * @param query.browser_rendering Whether the browser wraps the description text.
+ * @param query.show Comma-separated extra stats to show.
+ * @param query.show_icons Whether to show the stat icons.
+ * @param query.number_format How numbers are abbreviated.
+ * @param query.text_bold Whether the stat values are bold.
+ * @param query.line_height Line height between the stats.
+ * @param query.locale Language the card is rendered in.
+ * @param query.border_radius Card border radius.
+ * @param query.description_lines_count Lines the description is wrapped to.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+export const pin = async (query: PinApiQuery, config: CardConfig): Promise<ApiResult> => {
+  let colors;
+  try {
+    colors = parseColorParams(query);
+  } catch (err) {
+    // A rejected color cannot be used to draw its own error card.
+    return errorResult(err);
+  }
+
+  try {
+    const {
+      username,
+      repo,
+      hide_border,
+      card_width,
+      show_owner,
+      browser_rendering,
+      show,
+      show_icons,
+      number_format,
+      text_bold,
+      line_height,
+      locale,
+      border_radius,
+      description_lines_count,
+    } = parseParams(pinQuery, query);
+
+    const repoData = await fetchRepo(
+      {
+        username,
+        reponame: repo,
+        include_prs_authored: show.includes('prs_authored'),
+        include_prs_commented: show.includes('prs_commented'),
+        include_prs_reviewed: show.includes('prs_reviewed'),
+        include_issues_authored: show.includes('issues_authored'),
+        include_issues_commented: show.includes('issues_commented'),
+      },
+      config,
+    );
+
+    return {
+      status: 'success',
+      content: renderRepoCard(repoData, {
+        ...colors,
+        hide_border,
+        border_radius,
+        card_width_input: card_width,
+        show_owner,
+        browser_rendering,
+        show,
+        show_icons,
+        number_format,
+        text_bold,
+        line_height,
+        username,
+        locale,
+        description_lines_count,
+      }),
+    };
+  } catch (err) {
+    return errorResult(err, colors);
+  }
+};