pagesight 0.17.0 → 0.19.0

package/src/cli.ts

@@ -0,0 +1,217 @@
+import { renderAssessment } from "./assessment-text.js";
+import { renderOpportunities } from "./opportunities-text.js";
+import { parseArgs } from "node:util";
+import { defaultDates } from "./shared/dates.js";
+import { execute } from "./api/index.js";
+import { RequestError } from "./shared/http.js";
+
+export const help = `Pagesight — read-only site evidence
+
+pagesight                      Show CLI help
+pagesight mcp                  Start MCP explicitly
+pagesight discover --url https://example.com/ [--providers gsc,ga]
+pagesight doctor --config seo.config.json
+pagesight gsc sites
+pagesight gsc sitemaps --site sc-domain:example.com
+pagesight gsc inspect --site sc-domain:example.com --url https://example.com/
+pagesight gsc report --site sc-domain:example.com --request report.json [--max-pages 4]
+pagesight bing crawl-stats --site https://example.com/
+pagesight bing crawl-issues --site https://example.com/
+pagesight bing url-info --site https://example.com/ --url https://example.com/page
+pagesight bing link-counts --site https://example.com/ [--max-pages 4]
+pagesight bing url-links --site https://example.com/ --url https://example.com/page [--max-pages 4]
+pagesight bing sites
+pagesight bing queries --site https://example.com/
+pagesight bing pages --site https://example.com/
+pagesight bing traffic --site https://example.com/
+pagesight ga realtime --property 123456 --request realtime.json
+pagesight ga accounts
+pagesight ga property --property 123456
+pagesight ga key-events --property 123456
+pagesight ga report --property 123456 --request report.json [--max-pages 4]
+pagesight page --url https://example.com/
+pagesight speed psi --url https://example.com/ [--strategy mobile]
+pagesight speed crux --url https://example.com/ [--origin] [--form-factor PHONE]
+pagesight speed history --url https://example.com/ [--origin]
+pagesight snapshot --config seo.config.json [--start YYYY-MM-DD --end YYYY-MM-DD]
+pagesight assess --snapshot saved.json [--format text] [--max-rows 10]
+pagesight opportunities --snapshot saved.json [--min-impressions 20] [--max-clicks 2] [--max-rows 10] [--format text]
+pagesight compare --baseline before.json --current after.json [--max-rows 100]
+pagesight evidence import --request findings.json
+pagesight api --request operation.json
+pagesight serve [--port 6095]    Local HTTP API; requires PAGESIGHT_API_TOKEN
+
+Data commands emit JSON by default; assess --format text prints a readable summary. --json is accepted for clarity.
+--out FILE saves the same evidence locally. Exit: 0 success, 1 provider failure,
+2 invalid input, 3 partial evidence. Snapshot defaults to 28 days ending Pacific
+today minus 3 days; max-pages defaults to 4 (ad hoc reports: 1; maximum: 20).
+Credentials: GSC_* env, PAGESIGHT_GA_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS (GA), GOOGLE_API_KEY (speed), BING_WEBMASTER_API_KEY (Bing).
+Requests, property metadata, provider limits and errors are preserved in evidence.
+`;
+
+async function jsonFile(path: string | undefined, label: string): Promise<unknown> {
+  if (!path) throw new RequestError(`Missing --${label}`, null, "invalid_input");
+  try {
+    return await Bun.file(path).json();
+  } catch {
+    throw new RequestError(`Cannot read --${label} JSON file`, null, "invalid_input");
+  }
+}
+
+export async function runCli(args: string[]): Promise<number> {
+  try {
+    const { values, positionals } = parseArgs({
+      args,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        port: { type: "string" },
+        help: { type: "boolean", short: "h" },
+        json: { type: "boolean" },
+        config: { type: "string" },
+        request: { type: "string" },
+        site: { type: "string" },
+        property: { type: "string" },
+        url: { type: "string" },
+        out: { type: "string" },
+        start: { type: "string" },
+        end: { type: "string" },
+        "max-pages": { type: "string" },
+        strategy: { type: "string" },
+        "form-factor": { type: "string" },
+        origin: { type: "boolean" },
+        providers: { type: "string" },
+        snapshot: { type: "string" },
+        format: { type: "string" },
+        baseline: { type: "string" },
+        current: { type: "string" },
+        "max-rows": { type: "string" },
+        "min-impressions": { type: "string" },
+        "max-clicks": { type: "string" },
+      },
+    });
+    if (args.length === 0 || values.help || positionals[0] === "help") {
+      process.stdout.write(help);
+      return 0;
+    }
+    const [family, action] = positionals;
+    if (positionals.length > (["gsc", "ga", "bing", "speed", "evidence"].includes(family) ? 2 : 1))
+      throw new RequestError("Too many command arguments", null, "invalid_input");
+    const operation = ["gsc", "ga", "bing", "speed", "evidence"].includes(family)
+      ? `${family}.${action ?? ""}`
+      : family;
+    const flags: Record<string, string[]> = {
+      "evidence.import": ["request"],
+      assess: ["snapshot", "max-rows", "format"],
+      opportunities: ["snapshot", "max-rows", "format", "min-impressions", "max-clicks"],
+      discover: ["url", "providers"],
+      compare: ["baseline", "current", "max-rows"],
+      "bing.crawl-stats": ["site"],
+      "bing.crawl-issues": ["site"],
+      "bing.url-info": ["site", "url"],
+      "bing.link-counts": ["site", "max-pages"],
+      "bing.url-links": ["site", "url", "max-pages"],
+      "bing.sites": [],
+      "bing.queries": ["site"],
+      "bing.pages": ["site"],
+      "bing.traffic": ["site"],
+      "gsc.sites": [],
+      "gsc.sitemaps": ["site"],
+      "gsc.inspect": ["site", "url"],
+      "gsc.report": ["site", "request", "max-pages"],
+      "ga.realtime": ["property", "request"],
+      "ga.accounts": [],
+      "ga.property": ["property"],
+      "ga.key-events": ["property"],
+      "ga.report": ["property", "request", "max-pages"],
+      page: ["url"],
+      "speed.psi": ["url", "strategy"],
+      "speed.crux": ["url", "origin", "form-factor"],
+      "speed.history": ["url", "origin", "form-factor"],
+      doctor: ["config"],
+      snapshot: ["config", "start", "end", "max-pages"],
+      api: ["request"],
+      serve: ["port"],
+    };
+    const allowed = [...(flags[operation] ?? []), ...(operation === "serve" ? [] : ["out", "json"])];
+    for (const flag of Object.keys(values))
+      if (!allowed.includes(flag))
+        throw new RequestError(`--${flag} is not supported for ${operation}`, null, "invalid_input");
+    if (operation === "serve") {
+      const port = Number(values.port ?? 6095);
+      if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new RequestError("Invalid port", null, "invalid_input");
+      const { startHttpApi } = await import("./http.js");
+      const server = startHttpApi(process.env.PAGESIGHT_API_TOKEN ?? "", port);
+      process.stderr.write(`Pagesight API listening on ${server.url}v1/query\n`);
+      return 0;
+    }
+    if (values.format && !["json", "text"].includes(values.format))
+      throw new RequestError("Use --format json or text", null, "invalid_input");
+    if (values.json && values.format === "text")
+      throw new RequestError("--json and --format text conflict", null, "invalid_input");
+    let input: unknown;
+    if (operation === "api") input = await jsonFile(values.request, "request");
+    else if (operation === "evidence.import")
+      input = { operation, document: await jsonFile(values.request, "request") };
+    else if (operation === "opportunities")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        minImpressions: Number(values["min-impressions"] ?? 20),
+        maxClicks: Number(values["max-clicks"] ?? 2),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
+    else if (operation === "assess")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
+    else if (operation === "compare")
+      input = {
+        operation,
+        baseline: await jsonFile(values.baseline, "baseline"),
+        current: await jsonFile(values.current, "current"),
+        maxRows: Number(values["max-rows"] ?? 100),
+      };
+    else if (operation === "snapshot" || operation === "doctor") {
+      const config = await jsonFile(values.config, "config");
+      if (operation === "doctor") input = { operation, config };
+      else {
+        if (Boolean(values.start) !== Boolean(values.end))
+          throw new RequestError("Supply both --start and --end, or neither", null, "invalid_input");
+        const dates = values.start ? { startDate: values.start, endDate: values.end } : defaultDates();
+        input = { operation, config, ...dates, maxPages: Number(values["max-pages"] ?? 4) };
+      }
+    } else {
+      input = {
+        operation,
+        ...(values.site ? { site: values.site } : {}),
+        ...(values.property ? { property: values.property } : {}),
+        ...(values.url ? { url: values.url } : {}),
+        ...(values.request ? { request: await jsonFile(values.request, "request") } : {}),
+        ...(values["max-pages"] ? { maxPages: Number(values["max-pages"]) } : {}),
+        ...(values.strategy ? { strategy: values.strategy } : {}),
+        ...(values["form-factor"] ? { formFactor: values["form-factor"] } : {}),
+        ...(values.origin ? { origin: true } : {}),
+        ...(values.providers !== undefined ? { providers: values.providers.split(",") } : {}),
+      };
+    }
+    const result = await execute(input);
+    const output =
+      values.format === "text"
+        ? operation === "opportunities"
+          ? renderOpportunities(result)
+          : renderAssessment(result)
+        : `${JSON.stringify(result, null, 2)}\n`;
+    if (values.out) await Bun.write(values.out, output);
+    process.stdout.write(output);
+    return result.status === "ok" ? 0 : result.status === "partial" ? 3 : 1;
+  } catch (error) {
+    process.stderr.write(
+      `${JSON.stringify({ error: { code: error instanceof RequestError ? error.code : "invalid_input", message: error instanceof RequestError ? error.message : "Invalid command or request; use --help" } })}\n`,
+    );
+    return 2;
+  }
+}

package/src/http.ts

@@ -0,0 +1,39 @@
+import { timingSafeEqual } from "node:crypto";
+import { execute } from "./api/index.js";
+import { RequestError } from "./shared/http.js";
+
+export function startHttpApi(token: string, port = 6095) {
+  if (token.length < 24)
+    throw new RequestError("Set PAGESIGHT_API_TOKEN to at least 24 characters", null, "invalid_input");
+  return Bun.serve({
+    hostname: "127.0.0.1",
+    port,
+    maxRequestBodySize: 32_000_000,
+    idleTimeout: 255,
+    async fetch(request) {
+      const authorization = Buffer.from(request.headers.get("authorization") ?? "");
+      const expected = Buffer.from(`Bearer ${token}`);
+      if (authorization.length !== expected.length || !timingSafeEqual(authorization, expected))
+        return Response.json({ error: { code: "unauthenticated" } }, { status: 401 });
+      if (request.method !== "POST" || new URL(request.url).pathname !== "/v1/query")
+        return Response.json({ error: { code: "not_found" } }, { status: 404 });
+      try {
+        const result = await execute(await request.json());
+        return Response.json(result, {
+          status: result.status === "error" ? 502 : 200,
+          headers: { "Cache-Control": "no-store" },
+        });
+      } catch (error) {
+        return Response.json(
+          {
+            error: {
+              code: error instanceof RequestError ? error.code : "invalid_input",
+              message: error instanceof RequestError ? error.message : "Invalid JSON operation",
+            },
+          },
+          { status: 400 },
+        );
+      }
+    },
+  });
+}

package/src/index.ts

@@ -1,26 +1,9 @@
 #!/usr/bin/env bun
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerAiTool } from "./tools/ai.js";
-import { registerAuditTool } from "./tools/audit.js";
-import { registerPageTool } from "./tools/page.js";
-import { registerSearchTool } from "./tools/search.js";
-import { registerSetupTool } from "./tools/setup.js";
-import { registerSpeedTool } from "./tools/speed.js";
-
-const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-
-const server = new McpServer({
-  name: "pagesight",
-  version: pkg.version,
-});
-
-registerAiTool(server);
-registerAuditTool(server);
-registerPageTool(server);
-registerSearchTool(server);
-registerSetupTool(server);
-registerSpeedTool(server);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+if (Bun.argv.length === 3 && Bun.argv[2] === "mcp") {
+  await import("./mcp.js");
+} else {
+  const { runCli } = await import("./cli.js");
+  process.exitCode = await runCli(Bun.argv.slice(2));
+}
+
+export {};

package/src/mcp-server.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAiTool } from "./tools/ai.js";
+import { registerAuditTool } from "./tools/audit.js";
+import { registerObserveTool } from "./tools/observe.js";
+import { registerPageTool } from "./tools/page/tool.js";
+import { registerSearchTool } from "./tools/search/tool.js";
+import { registerSetupTool } from "./tools/setup.js";
+import { registerSpeedTool } from "./tools/speed/tool.js";
+
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+
+export function createMcpServer() {
+  const server = new McpServer({
+    name: "pagesight",
+    version: pkg.version,
+  });
+
+  registerObserveTool(server);
+  registerAiTool(server);
+  registerAuditTool(server);
+  registerPageTool(server);
+  registerSearchTool(server);
+  registerSetupTool(server);
+  registerSpeedTool(server);
+
+  return server;
+}

package/src/mcp.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./mcp-server.js";
+
+await createMcpServer().connect(new StdioServerTransport());

package/src/opportunities-text.ts

@@ -0,0 +1,61 @@
+import type { Evidence } from "./api/evidence.js";
+
+const text = (value: unknown) =>
+  JSON.stringify(value).replace(
+    /[\u007f-\u009f\u2028\u2029]/gu,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+export function renderOpportunities(result: Evidence): string {
+  const out = result.pages[0]?.response as
+    | {
+        site: string;
+        policy: unknown;
+        observedSearchRows: number | null;
+        unusableSearchRows: number;
+        qualifyingObservedRows: number | null;
+        omittedCandidates: number;
+        requestedDates: unknown;
+        snapshotSha256: string;
+        limitations: string[];
+        unassociatedOrganic: unknown[];
+        candidates: Array<{
+          url: string;
+          reason: string;
+          search: unknown;
+          organic: unknown;
+          technical: unknown;
+          unknowns: string[];
+          nextChecks: string[];
+          suggestedRequests: unknown[];
+        }>;
+      }
+    | undefined;
+  if (!out) return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [
+    `Pagesight opportunities: ${text(out.site)} (${result.status})`,
+    `Period: ${text(out.requestedDates)}; supplied snapshot, not reverified.`,
+    `Snapshot hash: ${out.snapshotSha256}`,
+    `Selection policy: ${text(out.policy)}`,
+    `Observed search rows: ${text(out.observedSearchRows)}; unusable: ${out.unusableSearchRows}; qualifying: ${text(out.qualifyingObservedRows)}; omitted candidates: ${out.omittedCandidates}`,
+  ];
+  for (const candidate of out.candidates)
+    lines.push(
+      "",
+      text(candidate.url),
+      `Why: ${text(candidate.reason)}`,
+      `Search: ${text(candidate.search)}`,
+      `Organic associations: ${text(candidate.organic)}`,
+      `Technical evidence: ${text(candidate.technical)}`,
+      ...candidate.unknowns.map((u) => `Unknown: ${text(u)}`),
+      ...candidate.nextChecks.map((n) => `Next check: ${text(n)}`),
+      ...candidate.suggestedRequests.map((request) => `Suggested API request: ${text(request)}`),
+    );
+  lines.push(
+    "",
+    ...out.unassociatedOrganic.map(
+      (table) => `Organic evidence not associated with displayed candidates: ${text(table)}`,
+    ),
+  );
+  lines.push("", ...out.limitations.map((l) => `Limit: ${text(l)}`));
+  return `${lines.join("\n")}\n`;
+}

package/src/providers/bing.ts

@@ -0,0 +1,48 @@
+import { RequestError, requestJson } from "../shared/http.js";
+
+export const bingMethods = {
+  "crawl-stats": "GetCrawlStats",
+  "crawl-issues": "GetCrawlIssues",
+  "url-info": "GetUrlInfo",
+  "link-counts": "GetLinkCounts",
+  "url-links": "GetUrlLinks",
+  sites: "GetUserSites",
+  queries: "GetQueryStats",
+  pages: "GetPageStats",
+  traffic: "GetRankAndTrafficStats",
+} as const;
+export type BingAction = keyof typeof bingMethods;
+
+export async function bingFetch(
+  action: BingAction,
+  site?: string,
+  parameters: Record<string, string> = {},
+): Promise<Record<string, unknown> & { d: unknown }> {
+  const key = process.env.BING_WEBMASTER_API_KEY;
+  if (!key) throw new RequestError("Set BING_WEBMASTER_API_KEY", null, "not_configured");
+  const url = new URL(`https://ssl.bing.com/webmaster/api.svc/json/${bingMethods[action]}`);
+  url.searchParams.set("apikey", key);
+  if (site !== undefined) url.searchParams.set("siteUrl", site);
+  for (const [name, value] of Object.entries(parameters)) url.searchParams.set(name, value);
+  const response = await requestJson<unknown>(url.href, { redirect: "error" });
+  if (response && typeof response === "object" && "ErrorCode" in response && Number.isSafeInteger(response.ErrorCode))
+    throw new RequestError("Bing returned an API fault", null, `bing_fault_${String(response.ErrorCode)}`);
+  if (!response || typeof response !== "object" || !("d" in response))
+    throw new RequestError("Bing returned an unexpected response envelope", null, "invalid_response");
+  const d = response.d;
+  const object = d !== null && typeof d === "object" && !Array.isArray(d);
+  let valid: boolean;
+  if (action === "url-info") valid = object && "Url" in d && typeof d.Url === "string";
+  else if (action === "link-counts" || action === "url-links") {
+    const rows = action === "link-counts" ? "Links" : "Details";
+    valid =
+      object &&
+      rows in d &&
+      Array.isArray(d[rows as keyof typeof d]) &&
+      "TotalPages" in d &&
+      Number.isSafeInteger(d.TotalPages) &&
+      Number(d.TotalPages) >= 0;
+  } else valid = Array.isArray(d);
+  if (!valid) throw new RequestError("Bing returned an unexpected response envelope", null, "invalid_response");
+  return response as Record<string, unknown> & { d: unknown };
+}

package/src/{lib → providers}/crux.ts

@@ -1,8 +1,10 @@
+import { RequestError, requestJson } from "../shared/http.js";
+
 const CRUX_API = "https://chromeuxreport.googleapis.com/v1/records";
 
 function getApiKey(): string {
   const key = process.env.GOOGLE_API_KEY;
-  if (!key) throw new Error("GOOGLE_API_KEY is required for CrUX API.");
+  if (!key) throw new RequestError("GOOGLE_API_KEY is required for CrUX API", null, "not_configured");
   return key;
 }
 
@@ -91,18 +93,11 @@ async function cruxFetch<T>(
     body.collectionPeriodCount = options.collectionPeriodCount;
   }
 
-  const res = await fetch(`${CRUX_API}:${endpoint}?key=${key}`, {
+  return requestJson<T>(`${CRUX_API}:${endpoint}?key=${key}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
   });
-
-  if (!res.ok) {
-    const err = await res.text();
-    throw new Error(`CrUX API error (${res.status}): ${err}`);
-  }
-
-  return res.json() as Promise<T>;
 }
 
 // --- CrUX Daily API ---

package/src/providers/ga.ts

@@ -0,0 +1,114 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getOAuthToken, getServiceAccountToken } from "./google-tokens.js";
+import { RequestError, requestJson } from "../shared/http.js";
+
+const SCOPE = "https://www.googleapis.com/auth/analytics.readonly";
+let cached: { path: string; token: string; expiresAt: number } | undefined;
+let pending: Promise<string> | undefined;
+
+export function gaCredentialPath(): string {
+  return (
+    process.env.PAGESIGHT_GA_CREDENTIALS ||
+    process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+    join(homedir(), ".config/gcloud/application_default_credentials.json")
+  );
+}
+
+export async function gaAccessToken(): Promise<string> {
+  const path = gaCredentialPath();
+  if (cached?.path === path && cached.expiresAt > Date.now()) return cached.token;
+  if (pending) return pending;
+  pending = (async () => {
+    if (!(await Bun.file(path).exists()))
+      throw new RequestError(
+        "Set PAGESIGHT_GA_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIALS to a Google credential JSON file",
+        null,
+        "not_configured",
+      );
+    let key: { type?: string; client_id?: string; client_secret?: string; refresh_token?: string };
+    try {
+      key = await Bun.file(path).json();
+      if (!key || typeof key !== "object") throw new Error();
+    } catch {
+      throw new RequestError("Cannot parse configured GA credential JSON", null, "invalid_credentials");
+    }
+    let token: string;
+    if (key.type === "service_account") token = await getServiceAccountToken(path, SCOPE);
+    else if (
+      key.type === "authorized_user" &&
+      typeof key.client_id === "string" &&
+      key.client_id &&
+      typeof key.client_secret === "string" &&
+      key.client_secret &&
+      typeof key.refresh_token === "string" &&
+      key.refresh_token
+    ) {
+      token = await getOAuthToken(key.client_id, key.client_secret, key.refresh_token);
+    } else
+      throw new RequestError(
+        "Supported GA credentials: service_account or authorized_user ADC",
+        null,
+        "unsupported_credentials",
+      );
+    cached = { path, token, expiresAt: Date.now() + 3_000_000 };
+    return token;
+  })();
+  try {
+    return await pending;
+  } finally {
+    pending = undefined;
+  }
+}
+
+export async function gaFetch<T>(path: string, body?: unknown, admin = false): Promise<T> {
+  const token = await gaAccessToken();
+  const base = admin ? "https://analyticsadmin.googleapis.com/v1beta/" : "https://analyticsdata.googleapis.com/v1beta/";
+  try {
+    return await requestJson<T>(base + path, {
+      method: body ? "POST" : "GET",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (error) {
+    if (error instanceof RequestError && error.status === 401) cached = undefined;
+    throw error;
+  }
+}
+
+export function normalizeGaProperty(id: string): string {
+  const number = id.replace(/^properties\//, "");
+  if (!/^\d+$/.test(number)) throw new RequestError("GA property must be a numeric ID", null, "invalid_input");
+  return `properties/${number}`;
+}
+
+export interface GaReport {
+  rows?: Array<{ dimensionValues?: Array<{ value?: string }>; metricValues?: Array<{ value?: string }> }>;
+  rowCount?: number;
+  metadata?: {
+    timeZone?: string;
+    dataLossFromOtherRow?: boolean;
+    subjectToThresholding?: boolean;
+    samplingMetadatas?: unknown[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export async function gaCredentialInfo() {
+  const source = process.env.PAGESIGHT_GA_CREDENTIALS
+    ? "PAGESIGHT_GA_CREDENTIALS"
+    : process.env.GOOGLE_APPLICATION_CREDENTIALS
+      ? "GOOGLE_APPLICATION_CREDENTIALS"
+      : "gcloud_adc";
+  try {
+    const key = await Bun.file(gaCredentialPath()).json();
+    return {
+      source,
+      type: typeof key.type === "string" ? key.type : null,
+      clientEmail: typeof key.client_email === "string" ? key.client_email : null,
+    };
+  } catch {
+    return { source, type: null, clientEmail: null };
+  }
+}

package/src/providers/google-tokens.ts

@@ -0,0 +1,86 @@
+import { RequestError, requestJson } from "../shared/http.js";
+
+export const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+  token_type: string;
+}
+
+export async function getServiceAccountToken(keyPath: string, scope: string): Promise<string> {
+  const keyFile = JSON.parse(await Bun.file(keyPath).text());
+  if (!keyFile.client_email || !keyFile.private_key) {
+    throw new Error("Service account key file missing client_email or private_key");
+  }
+  const now = Math.floor(Date.now() / 1000);
+
+  const header = toBase64Url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = toBase64Url(
+    JSON.stringify({
+      iss: keyFile.client_email,
+      scope,
+      aud: TOKEN_URL,
+      iat: now,
+      exp: now + 3600,
+    }),
+  );
+
+  const signingInput = `${header}.${payload}`;
+  const key = await crypto.subtle.importKey(
+    "pkcs8",
+    pemToBuffer(keyFile.private_key),
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(signingInput));
+  const jwt = `${signingInput}.${bufferToBase64Url(signature)}`;
+
+  const data = await requestJson<TokenResponse>(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: jwt }),
+  });
+  if (!data.access_token) throw new RequestError("Token exchange returned no access token", null, "invalid_response");
+  return data.access_token;
+}
+
+function pemToBuffer(pem: string): ArrayBuffer {
+  const b64 = pem
+    .replace(/-----BEGIN PRIVATE KEY-----/g, "")
+    .replace(/-----END PRIVATE KEY-----/g, "")
+    .replace(/\s/g, "");
+  const binary = atob(b64);
+  const buf = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) buf[i] = binary.charCodeAt(i);
+  return buf.buffer;
+}
+
+function toBase64Url(input: string): string {
+  return btoa(input).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function bufferToBase64Url(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return toBase64Url(binary);
+}
+
+// --- OAuth Refresh Token Auth ---
+
+export async function getOAuthToken(clientId: string, clientSecret: string, refreshToken: string): Promise<string> {
+  const data = await requestJson<TokenResponse>(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+    }),
+  });
+  if (!data.access_token) throw new RequestError("Token refresh returned no access token", null, "invalid_response");
+  return data.access_token;
+}