@jgengine/github 0.1.0

package/dist/server.js

@@ -0,0 +1,195 @@
+const USERNAME_PATTERN = /^[A-Za-z0-9-]{1,39}$/;
+const API = "https://api.github.com";
+const RESPONSE_HEADERS = {
+    "Content-Type": "application/json",
+    "Access-Control-Allow-Origin": "*",
+    "Cache-Control": "public, max-age=600",
+};
+/** Thrown by resolveContributions when the user does not exist (→ 404). */
+export class GitHubUserNotFoundError extends Error {
+}
+async function fetchViaGraphQL(user, token) {
+    const query = `
+    query ($login: String!) {
+      user(login: $login) {
+        login
+        name
+        avatarUrl
+        contributionsCollection {
+          contributionCalendar {
+            totalContributions
+            weeks { contributionDays { date contributionCount weekday } }
+          }
+        }
+      }
+    }
+  `;
+    const res = await fetch("https://api.github.com/graphql", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "User-Agent": "jgengine" },
+        body: JSON.stringify({ query, variables: { login: user } }),
+    });
+    if (!res.ok)
+        throw new Error(`GitHub GraphQL API responded with ${res.status}`);
+    const payload = (await res.json());
+    if (payload.errors?.length)
+        throw new Error(payload.errors.map((e) => e.message).join("; "));
+    if (!payload.data?.user)
+        throw new GitHubUserNotFoundError(user);
+    const { login, name, avatarUrl, contributionsCollection } = payload.data.user;
+    const calendar = contributionsCollection.contributionCalendar;
+    return {
+        source: "graphql",
+        profile: { login, name, avatarUrl },
+        total: calendar.totalContributions,
+        weeks: calendar.weeks.map((week) => ({
+            days: week.contributionDays.map((day) => ({ date: day.date, count: day.contributionCount, weekday: day.weekday })),
+        })),
+    };
+}
+function parseTooltipCounts(html) {
+    const counts = new Map();
+    const pattern = /<tool-tip[^>]*for="([^"]+)"[^>]*>([\s\S]*?)<\/tool-tip>/g;
+    let match;
+    while ((match = pattern.exec(html)) !== null) {
+        const [, id, text] = match;
+        const countMatch = text.match(/(\d+)\s+contributions?/i);
+        counts.set(id, /no contributions/i.test(text) ? 0 : countMatch ? Number(countMatch[1]) : 0);
+    }
+    return counts;
+}
+export function parseContributionsHtml(html) {
+    const tooltipCounts = parseTooltipCounts(html);
+    const days = [];
+    const cellPattern = /<td\b[^>]*\bdata-date="(\d{4}-\d{2}-\d{2})"[^>]*>/g;
+    let match;
+    while ((match = cellPattern.exec(html)) !== null) {
+        const [tag, date] = match;
+        const id = tag.match(/\bid="([^"]*)"/)?.[1];
+        const count = id !== undefined ? tooltipCounts.get(id) ?? 0 : 0;
+        days.push({ date: date, count, weekday: new Date(`${date}T00:00:00Z`).getUTCDay() });
+    }
+    return days;
+}
+async function fetchViaScrape(user) {
+    const res = await fetch(`https://github.com/users/${encodeURIComponent(user)}/contributions`, {
+        headers: { "User-Agent": "jgengine" },
+    });
+    if (res.status === 404)
+        throw new GitHubUserNotFoundError(user);
+    if (!res.ok)
+        throw new Error(`GitHub responded with ${res.status}`);
+    const days = parseContributionsHtml(await res.text());
+    if (days.length === 0) {
+        throw new Error(`Could not read '${user}'’s contribution calendar — GitHub may have blocked the request or changed its page markup.`);
+    }
+    const weeks = [];
+    for (let i = 0; i < days.length; i += 7)
+        weeks.push({ days: days.slice(i, i + 7) });
+    return {
+        source: "scrape",
+        profile: { login: user, name: null, avatarUrl: null },
+        total: days.reduce((sum, day) => sum + day.count, 0),
+        weeks,
+    };
+}
+/** Server-side: fetch a user's contribution calendar via GraphQL (with token) or HTML scrape. */
+export function resolveContributions(user, options = {}) {
+    return options.token ? fetchViaGraphQL(user, options.token) : fetchViaScrape(user);
+}
+/**
+ * Turnkey proxy handler — mount at any route in any Web-`Response` server (Nitro,
+ * workers, Deno). Reads `?user=`, validates, proxies GitHub, returns JSON + CORS.
+ */
+export function githubContributionsHandler(options = {}) {
+    return async (request) => {
+        const user = new URL(request.url).searchParams.get("user");
+        if (!user || !USERNAME_PATTERN.test(user)) {
+            return json({ error: "Query param 'user' must be a valid GitHub username." }, 400);
+        }
+        try {
+            return json(await resolveContributions(user, options));
+        }
+        catch (error) {
+            if (error instanceof GitHubUserNotFoundError)
+                return json({ error: `GitHub user '${user}' was not found.` }, 404);
+            return json({ error: error instanceof Error ? error.message : "Upstream failure" }, 502);
+        }
+    };
+}
+const PROXY_RESPONSE_HEADERS = {
+    "Content-Type": "application/json",
+    "Cache-Control": "private, no-store",
+};
+function proxyHeaders(token) {
+    const headers = { Accept: "application/vnd.github+json", "User-Agent": "jgengine" };
+    if (token !== undefined)
+        headers.Authorization = `Bearer ${token}`;
+    return headers;
+}
+async function passthrough(upstream) {
+    const headers = { ...PROXY_RESPONSE_HEADERS };
+    const link = upstream.headers.get("link");
+    if (link !== null)
+        headers.Link = link;
+    return new Response(await upstream.text(), { status: upstream.status, headers });
+}
+function proxyJson(body, status = 200) {
+    return new Response(JSON.stringify(body), { status, headers: PROXY_RESPONSE_HEADERS });
+}
+async function handleGraphQLOp(request, op, options) {
+    if (request.method !== "POST")
+        return proxyJson({ error: "GraphQL requires POST." }, 405);
+    const query = options.graphqlOperations?.[op];
+    if (query === undefined)
+        return proxyJson({ error: `GraphQL operation '${op}' is not allowed.` }, 403);
+    const doFetch = options.fetchImpl ?? fetch;
+    try {
+        const { variables } = (await request.json().catch(() => ({})));
+        const upstream = await doFetch(`${API}/graphql`, {
+            method: "POST",
+            headers: { ...proxyHeaders(options.token), "Content-Type": "application/json" },
+            body: JSON.stringify({ query, variables }),
+        });
+        return passthrough(upstream);
+    }
+    catch (error) {
+        return proxyJson({ error: error instanceof Error ? error.message : "Upstream failure" }, 502);
+    }
+}
+/**
+ * Named-operation GitHub proxy: forwards only the REST paths and GraphQL
+ * operations the caller explicitly allowlists, using the server-side token.
+ * Clients never supply raw GraphQL text or an unconstrained path — a bare
+ * mount with no `allowPath`/`graphqlOperations` forwards nothing at all.
+ */
+export function githubProxyHandler(options = {}) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const op = url.searchParams.get("op");
+        if (op !== null)
+            return handleGraphQLOp(request, op, options);
+        const path = url.searchParams.get("path");
+        if (path === null || !path.startsWith("/")) {
+            return proxyJson({ error: "Query param 'path' must be an absolute GitHub API path." }, 400);
+        }
+        if (path === "/graphql" || path.startsWith("/graphql?")) {
+            return proxyJson({ error: "Use '?op=<name>' for GraphQL, not '?path=/graphql'." }, 403);
+        }
+        if (!(options.allowPath?.(path) ?? false)) {
+            return proxyJson({ error: `Path '${path}' is not allowed.` }, 403);
+        }
+        if (request.method !== "GET")
+            return proxyJson({ error: "Only GET reads are proxied." }, 405);
+        const doFetch = options.fetchImpl ?? fetch;
+        try {
+            return await passthrough(await doFetch(`${API}${path}`, { headers: proxyHeaders(options.token) }));
+        }
+        catch (error) {
+            return proxyJson({ error: error instanceof Error ? error.message : "Upstream failure" }, 502);
+        }
+    };
+}
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), { status, headers: RESPONSE_HEADERS });
+}

package/dist/source.d.ts

@@ -0,0 +1,17 @@
+import { type DayCell } from "./calendar.js";
+import type { ContributionsWire, GitHubProfile } from "./wire.js";
+export type { ContributionsWire, GitHubProfile } from "./wire.js";
+export interface ContributionData {
+    cells: DayCell[];
+    profile: GitHubProfile | null;
+    source: "graphql" | "scrape";
+}
+export declare const DEFAULT_ENDPOINT = "/api/github-contributions";
+/** Flatten the proxy's week/day wire into positioned, leveled, labeled cells.
+ * @internal
+ */
+export declare function wireToCells(wire: ContributionsWire): DayCell[];
+/** Browser client: fetch a user's contributions through the proxy endpoint.
+ * @internal
+ */
+export declare function contributions(user: string, endpoint?: string): Promise<ContributionData>;

package/dist/source.js

@@ -0,0 +1,33 @@
+import { labelFromISO, levelForCount } from "./calendar.js";
+export const DEFAULT_ENDPOINT = "/api/github-contributions";
+/** Flatten the proxy's week/day wire into positioned, leveled, labeled cells.
+ * @internal
+ */
+export function wireToCells(wire) {
+    const cells = [];
+    wire.weeks.forEach((week, week_index) => {
+        for (const day of week.days) {
+            cells.push({
+                index: cells.length,
+                week: week_index,
+                weekday: day.weekday,
+                count: day.count,
+                level: levelForCount(day.count),
+                label: labelFromISO(day.date),
+            });
+        }
+    });
+    return cells;
+}
+/** Browser client: fetch a user's contributions through the proxy endpoint.
+ * @internal
+ */
+export async function contributions(user, endpoint = DEFAULT_ENDPOINT) {
+    const response = await fetch(`${endpoint}?user=${encodeURIComponent(user)}`);
+    if (!response.ok) {
+        const body = (await response.json().catch(() => ({})));
+        throw new Error(body.error ?? `Lookup failed (${response.status})`);
+    }
+    const wire = (await response.json());
+    return { cells: wireToCells(wire), profile: wire.profile, source: wire.source };
+}

package/dist/wire.d.ts

@@ -0,0 +1,18 @@
+/** The normalized JSON the proxy handler returns and the client consumes. */
+export interface GitHubProfile {
+    login: string;
+    name: string | null;
+    avatarUrl: string | null;
+}
+export interface ContributionsWire {
+    source: "graphql" | "scrape";
+    profile: GitHubProfile | null;
+    total: number;
+    weeks: {
+        days: {
+            date: string;
+            count: number;
+            weekday: number;
+        }[];
+    }[];
+}

package/dist/wire.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jgengine/github",
+  "version": "0.1.0",
+  "description": "GitHub data source for JGengine: contribution calendar fetch (GraphQL + HTML-scrape) with a server proxy handler, plus a browser client and contribution analytics.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Noisemaker111/jgengine.git",
+    "directory": "packages/github"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsgo --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}