@gscdump/devframe 0.0.0-stage → 5.7.0

package/dist/credential.mjs

@@ -0,0 +1,59 @@
+import { z } from "zod";
+const DEFAULT_API_ROOT = "https://gscdump.com/api";
+const cliAuthenticationSchema = z.union([
+	z.object({
+		_tag: z.literal("Hosted"),
+		apiRoot: z.string().url(),
+		sessionId: z.string().min(1)
+	}),
+	z.object({
+		_tag: z.literal("Hosted"),
+		apiRoot: z.string().url(),
+		apiKey: z.string().min(1)
+	}),
+	z.object({ _tag: z.literal("Local") })
+]);
+function trimRoot(root) {
+	return root.replace(/\/+$/, "");
+}
+async function resolveCredential(input) {
+	const apiRoot = trimRoot(input.apiRoot ?? input.env.GSCDUMP_API_ROOT ?? DEFAULT_API_ROOT);
+	if (input.apiKey) return {
+		_tag: "ApiKey",
+		apiKey: input.apiKey,
+		apiRoot,
+		source: "option"
+	};
+	if (input.env.GSCDUMP_API_KEY) return {
+		_tag: "ApiKey",
+		apiKey: input.env.GSCDUMP_API_KEY,
+		apiRoot,
+		source: "env"
+	};
+	const saved = await input.readCliAuthentication();
+	if (saved == null) return null;
+	const parsed = cliAuthenticationSchema.safeParse(saved);
+	if (!parsed.success || parsed.data._tag === "Local") return null;
+	const root = trimRoot(parsed.data.apiRoot);
+	return "sessionId" in parsed.data ? {
+		_tag: "CliSession",
+		sessionId: parsed.data.sessionId,
+		apiRoot: root,
+		source: "cli-session"
+	} : {
+		_tag: "ApiKey",
+		apiKey: parsed.data.apiKey,
+		apiRoot: root,
+		source: "cli-session"
+	};
+}
+function bearerOf(credential) {
+	return credential._tag === "CliSession" ? credential.sessionId : credential.apiKey;
+}
+function cliHeadersOf(credential) {
+	return credential._tag === "CliSession" ? { "x-cli-session": credential.sessionId } : { "x-api-key": credential.apiKey };
+}
+function dashboardOrigin(apiRoot) {
+	return URL.parse(apiRoot)?.origin ?? "https://gscdump.com";
+}
+export { bearerOf, cliHeadersOf, dashboardOrigin, resolveCredential };

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { DailyPoint, DateWindow, GscdumpContext, MetricTotals, PageStats, PageStatsInput, Period, QueryRow, SiteSummary } from "./shared/protocol.mjs";
+import { GscdumpReaderOptions } from "./reader.mjs";
+import { DevframeDefinition } from "devframe";
+export interface GscdumpDevframeOptions extends GscdumpReaderOptions {
+  /** Override the request implementation, for proxies and tests. */
+  fetch?: typeof fetch;
+}
+/**
+ * The gscdump devframe: Search Console clicks, impressions, CTR, position, and
+ * top queries for the page in view, read from the gscdump Hosted record.
+ *
+ * Mount it in Vite DevTools with `@gscdump/devframe/vite`, or pass it to any
+ * devframe hub.
+ */
+export declare function createGscdumpDevframe(options?: GscdumpDevframeOptions): DevframeDefinition;
+export { type DailyPoint, type DateWindow, type GscdumpContext, type GscdumpReaderOptions, type MetricTotals, type PageStats, type PageStatsInput, type Period, type QueryRow, type SiteSummary, createGscdumpDevframe as default };

package/dist/index.mjs

@@ -0,0 +1,52 @@
+import { description, homepage, name, version } from "./package.mjs";
+import { DEVFRAME_ID } from "./shared/protocol.mjs";
+import { createGscdumpReader } from "./reader.mjs";
+import { createRpcFunctions } from "./rpc.mjs";
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { defineDevframe } from "devframe";
+function packageDir() {
+	return dirname(createRequire(import.meta.url).resolve(`${name}/package.json`));
+}
+async function readCliAuthentication(env) {
+	const dir = env.GSCDUMP_CONFIG_DIR ?? join(homedir(), ".config", "gscdump");
+	const body = await readFile(join(dir, "authentication.json"), "utf8").catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	});
+	return body === null ? null : JSON.parse(body);
+}
+function createGscdumpDevframe(options = {}) {
+	const dir = packageDir();
+	return defineDevframe({
+		id: DEVFRAME_ID,
+		name: "Search Console",
+		version,
+		packageName: name,
+		importMetaUrl: import.meta.url,
+		homepage,
+		description,
+		icon: "ph:chart-line-up-duotone",
+		clientAssets: join(dir, "dist/client"),
+		dock: {
+			category: "web",
+			clientScript: { importFrom: join(dir, "dist/client-script/index.mjs") }
+		},
+		capabilities: { build: false },
+		setup(ctx) {
+			const env = process.env;
+			const reader = createGscdumpReader(options, {
+				fetch: options.fetch ?? globalThis.fetch,
+				env,
+				readCliAuthentication: () => readCliAuthentication(env),
+				now: Date.now
+			});
+			const scoped = ctx.scope(DEVFRAME_ID);
+			for (const fn of createRpcFunctions(reader)) scoped.rpc.register(fn);
+		}
+	});
+}
+export { createGscdumpDevframe, createGscdumpDevframe as default };

package/dist/package.mjs

@@ -0,0 +1,5 @@
+var name = "@gscdump/devframe";
+var version = "5.7.0";
+var description = "Search Console clicks, impressions, and queries for the page you are developing, in Vite DevTools and any devframe hub.";
+var homepage = "https://github.com/harlan-zw/gscdump/tree/main/packages/devframe#readme";
+export { description, homepage, name, version };

package/dist/page-stats.mjs

@@ -0,0 +1,114 @@
+const DAY_MS = 864e5;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function addDays(date, days) {
+	return new Date(Date.parse(`${date}T00:00:00Z`) + days * DAY_MS).toISOString().slice(0, 10);
+}
+function pagePathOf(input) {
+	const text = input.trim();
+	if (!text) return null;
+	if (/^[a-z][a-z\d+.-]*:\/\//i.test(text)) {
+		const url = URL.parse(text);
+		return url ? `${url.pathname}${url.search}` : null;
+	}
+	const path = text.split("#")[0];
+	return path.startsWith("/") ? path : `/${path}`;
+}
+function periodWindows(days, site) {
+	const { oldestDate, newestDate } = site;
+	if (!newestDate || !ISO_DATE.test(newestDate)) return null;
+	const oldest = oldestDate && ISO_DATE.test(oldestDate) ? oldestDate : null;
+	const start = addDays(newestDate, -(days - 1));
+	const current = {
+		start: oldest && start < oldest ? oldest : start,
+		end: newestDate
+	};
+	const previousEnd = addDays(start, -1);
+	const previousStart = addDays(previousEnd, -(days - 1));
+	return {
+		current,
+		previous: oldest && previousStart < oldest ? null : {
+			start: previousStart,
+			end: previousEnd
+		}
+	};
+}
+function num(value) {
+	const n = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(n) ? n : 0;
+}
+function finish(sum) {
+	return {
+		clicks: sum.clicks,
+		impressions: sum.impressions,
+		ctr: sum.impressions > 0 ? sum.clicks / sum.impressions : 0,
+		position: sum.impressions > 0 ? sum.positionWeight / sum.impressions : null
+	};
+}
+function accumulate(sum, row) {
+	const impressions = num(row.impressions);
+	sum.clicks += num(row.clicks);
+	sum.impressions += impressions;
+	sum.positionWeight += num(row.position) * impressions;
+}
+function inWindow(date, window) {
+	return date >= window.start && date <= window.end;
+}
+function fillDays(window, byDate) {
+	const days = [];
+	for (let date = window.start; date <= window.end; date = addDays(date, 1)) days.push(byDate.get(date) ?? {
+		date,
+		clicks: 0,
+		impressions: 0,
+		ctr: 0,
+		position: null
+	});
+	return days;
+}
+function summariseDaily(rows, windows) {
+	const current = {
+		clicks: 0,
+		impressions: 0,
+		positionWeight: 0
+	};
+	const previous = {
+		clicks: 0,
+		impressions: 0,
+		positionWeight: 0
+	};
+	const byDate = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const date = String(row.date ?? "");
+		const target = inWindow(date, windows.current) ? current : windows.previous && inWindow(date, windows.previous) ? previous : null;
+		if (!target) continue;
+		accumulate(target, row);
+		const day = {
+			clicks: 0,
+			impressions: 0,
+			positionWeight: 0
+		};
+		accumulate(day, row);
+		byDate.set(date, {
+			date,
+			...finish(day)
+		});
+	}
+	return {
+		totals: finish(current),
+		previousTotals: windows.previous ? finish(previous) : null,
+		daily: fillDays(windows.current, byDate),
+		previousDaily: windows.previous ? fillDays(windows.previous, byDate) : null
+	};
+}
+function parseQueryRows(rows) {
+	return rows.filter((row) => typeof row.query === "string" && row.query.length > 0).map((row) => ({
+		query: String(row.query),
+		clicks: num(row.clicks),
+		impressions: num(row.impressions),
+		ctr: num(row.ctr),
+		position: row.position == null ? null : num(row.position)
+	})).sort((a, b) => b.clicks - a.clicks || b.impressions - a.impressions);
+}
+function dashboardPageUrl(origin, site, path) {
+	return `${origin}/app/sites/${encodeURIComponent(site.siteUrl)}/search-console/pages/${encodeURIComponent(path)}?siteId=${encodeURIComponent(site.siteId)}`;
+}
+export { addDays, dashboardPageUrl, pagePathOf, parseQueryRows, periodWindows, summariseDaily };

package/dist/reader.d.mts

@@ -0,0 +1,9 @@
+import "./shared/protocol.mjs";
+export interface GscdumpReaderOptions {
+  /** The Site to read: a Site ID, a Site URL, or its host. Optional when the credential holds one Site. */
+  site?: string;
+  /** A gscdump user API key. Defaults to `GSCDUMP_API_KEY`, then the CLI's Hosted login. */
+  apiKey?: string;
+  /** Defaults to `GSCDUMP_API_ROOT`, then `https://gscdump.com/api`. */
+  apiRoot?: string;
+}

package/dist/reader.mjs

@@ -0,0 +1,238 @@
+import { bearerOf, dashboardOrigin, resolveCredential } from "./credential.mjs";
+import { matchSite, readAccount } from "./account.mjs";
+import { addDays, dashboardPageUrl, pagePathOf, parseQueryRows, periodWindows, summariseDaily } from "./page-stats.mjs";
+import { PERIODS } from "./shared/protocol.mjs";
+import { parseRecordReadRefusal } from "@gscdump/contracts";
+import { periodToDateRange } from "@gscdump/sdk/period";
+import { createGscdumpV1Client, isGscdumpV1Error } from "@gscdump/sdk/v1";
+const ACCOUNT_TTL_MS = 3e5;
+const STATS_TTL_MS = 3e5;
+const TOP_QUERIES = 25;
+function rowsBody(dimension, path, window) {
+	return {
+		dimensions: [dimension],
+		filter: { _filters: [{
+			dimension: "date",
+			operator: "between",
+			expression: window.start,
+			expression2: window.end
+		}, {
+			dimension: "page",
+			operator: "equals",
+			expression: path
+		}] },
+		orderBy: dimension === "date" ? {
+			column: "date",
+			dir: "asc"
+		} : {
+			column: "clicks",
+			dir: "desc"
+		},
+		rowLimit: dimension === "date" ? 400 : TOP_QUERIES
+	};
+}
+function periodDays(period) {
+	return PERIODS.find((option) => option.value === period)?.days ?? 28;
+}
+function createGscdumpReader(options, deps) {
+	let session = null;
+	const stats = /* @__PURE__ */ new Map();
+	async function loadSession() {
+		const credential = await resolveCredential({
+			apiKey: options.apiKey,
+			apiRoot: options.apiRoot,
+			env: deps.env,
+			readCliAuthentication: deps.readCliAuthentication
+		});
+		if (!credential) return {
+			_tag: "Blocked",
+			context: { _tag: "CredentialMissing" }
+		};
+		const account = await readAccount(credential, deps.fetch);
+		if (account._tag === "Rejected") return {
+			_tag: "Blocked",
+			context: {
+				_tag: "CredentialRejected",
+				source: credential.source
+			}
+		};
+		if (account._tag === "Unavailable") return {
+			_tag: "Blocked",
+			context: {
+				_tag: "Unavailable",
+				message: account.message
+			}
+		};
+		if (account.sites.length === 0) return {
+			_tag: "Blocked",
+			context: { _tag: "NoSites" }
+		};
+		return {
+			_tag: "Ready",
+			credential,
+			client: createGscdumpV1Client({
+				apiRoot: credential.apiRoot,
+				credential: bearerOf(credential),
+				fetch: deps.fetch
+			}),
+			sites: account.sites
+		};
+	}
+	function currentSession() {
+		if (session && deps.now() - session.at < ACCOUNT_TTL_MS) return session.value;
+		const value = loadSession();
+		session = {
+			at: deps.now(),
+			value
+		};
+		value.then((result) => {
+			if (result._tag === "Blocked" && session?.value === value) session = null;
+		}, () => {
+			if (session?.value === value) session = null;
+		});
+		return value;
+	}
+	async function context(preferredSiteId) {
+		const current = await currentSession();
+		if (current._tag === "Blocked") return current.context;
+		if (options.site) {
+			const match = matchSite(current.sites, options.site);
+			return match._tag === "Found" ? {
+				_tag: "Ready",
+				site: match.site,
+				sites: current.sites,
+				configured: true
+			} : {
+				_tag: "SiteRequired",
+				sites: current.sites,
+				target: options.site
+			};
+		}
+		const preferred = preferredSiteId ? current.sites.find((site) => site.siteId === preferredSiteId) : void 0;
+		if (preferred) return {
+			_tag: "Ready",
+			site: preferred,
+			sites: current.sites,
+			configured: false
+		};
+		const match = matchSite(current.sites, null);
+		return match._tag === "Found" ? {
+			_tag: "Ready",
+			site: match.site,
+			sites: current.sites,
+			configured: false
+		} : {
+			_tag: "SiteRequired",
+			sites: current.sites,
+			target: null
+		};
+	}
+	async function readRows(client, siteId, body) {
+		return (await client.queryAnalyticsRows({
+			params: { siteId },
+			body
+		})).data.rows;
+	}
+	async function readPage(current, site, path, period, windows, retried) {
+		const span = {
+			start: windows.previous?.start ?? windows.current.start,
+			end: windows.current.end
+		};
+		const result = await Promise.all([readRows(current.client, site.siteId, rowsBody("date", path, span)), readRows(current.client, site.siteId, rowsBody("query", path, windows.current))]).catch((error) => error);
+		if (Array.isArray(result)) {
+			const [daily, queries] = result;
+			return {
+				_tag: "Ok",
+				siteId: site.siteId,
+				path,
+				period,
+				window: windows.current,
+				previousWindow: windows.previous,
+				...summariseDaily(daily, windows),
+				queries: parseQueryRows(queries),
+				dashboardUrl: dashboardPageUrl(dashboardOrigin(current.credential.apiRoot), site, path)
+			};
+		}
+		if (!isGscdumpV1Error(result)) throw result;
+		const refusal = parseRecordReadRefusal(result.details);
+		if (refusal?.reason === "range_not_synced" && !retried && refusal.missingStart > windows.current.start) {
+			const shifted = periodWindows(periodDays(period), {
+				oldestDate: site.oldestDate,
+				newestDate: addDays(refusal.missingStart, -1)
+			});
+			if (shifted) return readPage(current, site, path, period, shifted, true);
+		}
+		if (refusal?.reason === "record_not_ready") return {
+			_tag: "NoData",
+			siteId: site.siteId,
+			message: "gscdump has not prepared this Site's record for reads yet. Try again in a few minutes."
+		};
+		if (refusal?.reason === "range_not_synced") return {
+			_tag: "NoData",
+			siteId: site.siteId,
+			message: `The Site's record does not hold ${refusal.missingStart} to ${refusal.missingEnd} yet.`
+		};
+		if (result.code === "rate_limited") return { _tag: "RateLimited" };
+		if (result.status === 401 || result.status === 403) return {
+			_tag: "SiteUnavailable",
+			context: {
+				_tag: "CredentialRejected",
+				source: current.credential.source
+			}
+		};
+		return {
+			_tag: "Failed",
+			message: result.message,
+			requestId: result.requestId ?? null
+		};
+	}
+	async function pageStats(input) {
+		const path = pagePathOf(input.page);
+		if (!path) return {
+			_tag: "InvalidPage",
+			page: input.page
+		};
+		const period = input.period ?? "28d";
+		const resolved = await context(input.siteId);
+		if (resolved._tag !== "Ready") return {
+			_tag: "SiteUnavailable",
+			context: resolved
+		};
+		const site = resolved.site;
+		const key = `${site.siteId}|${period}|${path}`;
+		const hit = stats.get(key);
+		if (hit && deps.now() - hit.at < STATS_TTL_MS) return hit.value;
+		const current = await currentSession();
+		if (current._tag !== "Ready") return {
+			_tag: "SiteUnavailable",
+			context: current.context
+		};
+		const stableEnd = periodToDateRange(period, { now: new Date(deps.now()) }).end;
+		const newestDate = site.newestDate && site.newestDate > stableEnd ? stableEnd : site.newestDate;
+		const windows = periodWindows(periodDays(period), {
+			oldestDate: site.oldestDate,
+			newestDate
+		});
+		if (!windows) return {
+			_tag: "NoData",
+			siteId: site.siteId,
+			message: "The Site's record holds no days yet. gscdump is still syncing it."
+		};
+		const value = readPage(current, site, path, period, windows, false);
+		stats.set(key, {
+			at: deps.now(),
+			value
+		});
+		value.then((result) => {
+			if (result._tag !== "Ok" && stats.get(key)?.value === value) stats.delete(key);
+		}, () => {
+			if (stats.get(key)?.value === value) stats.delete(key);
+		});
+		return value;
+	}
+	return {
+		context,
+		pageStats
+	};
+}
+export { createGscdumpReader };

package/dist/rpc.mjs

@@ -0,0 +1,31 @@
+import { defineRpcFunction } from "devframe";
+import { z } from "zod";
+const pageStatsArgs = z.object({
+	page: z.string().min(1).describe("A path such as `/blog/post`, or a full URL of a page on the Site."),
+	period: z.enum([
+		"7d",
+		"28d",
+		"3m"
+	]).optional().describe("The window to read. Defaults to `28d`."),
+	siteId: z.string().optional().describe("The Site ID. Defaults to the Site the devtool reads.")
+});
+const pageStatsResult = z.custom();
+function createRpcFunctions(reader) {
+	return [defineRpcFunction({
+		name: "get-context",
+		type: "query",
+		jsonSerializable: true,
+		handler: (preferredSiteId) => reader.context(preferredSiteId ?? null)
+	}), defineRpcFunction({
+		name: "get-page-stats",
+		type: "query",
+		args: [pageStatsArgs],
+		returns: pageStatsResult,
+		agent: {
+			title: "Search Console page stats",
+			description: "Read Google Search Console clicks, impressions, CTR, average position, the daily series, and the top queries for one page of the Site, from the gscdump Hosted record. Call it to check how a page performs in Google search before or after you change it."
+		},
+		handler: (input) => reader.pageStats(input)
+	})];
+}
+export { createRpcFunctions };

package/dist/shared/protocol.d.mts

@@ -0,0 +1,96 @@
+export type Period = '7d' | '28d' | '3m';
+export interface SiteSummary {
+  siteId: string;
+  /** The Site as gscdump registered it, for example `example.com`. */
+  siteUrl: string;
+  /** The first day the Hosted record holds, `YYYY-MM-DD`. */
+  oldestDate: string | null;
+  /** The last day the Hosted record holds, `YYYY-MM-DD`. */
+  newestDate: string | null;
+}
+/**
+ * What the node side can read, decided once per panel boot. Each tag names
+ * the next step the panel shows.
+ */
+export type GscdumpContext = {
+  _tag: 'Ready';
+  site: SiteSummary;
+  sites: SiteSummary[];
+  configured: boolean;
+} | {
+  _tag: 'SiteRequired';
+  sites: SiteSummary[];
+  target: string | null;
+} | {
+  _tag: 'NoSites';
+} | {
+  _tag: 'CredentialMissing';
+} | {
+  _tag: 'CredentialRejected';
+  source: CredentialSource;
+} | {
+  _tag: 'Unavailable';
+  message: string;
+};
+export type CredentialSource = 'option' | 'env' | 'cli-session';
+export interface MetricTotals {
+  clicks: number;
+  impressions: number;
+  ctr: number;
+  /** Impression-weighted average position. `null` when the page had no impressions. */
+  position: number | null;
+}
+export interface DailyPoint extends MetricTotals {
+  date: string;
+}
+export interface QueryRow extends MetricTotals {
+  query: string;
+}
+export interface DateWindow {
+  start: string;
+  end: string;
+}
+export interface PageStatsInput {
+  /** A path such as `/blog/post`, or a full URL. Search Console stores pages by path. */
+  page: string;
+  period?: Period;
+  /** Defaults to the Site the context resolved. */
+  siteId?: string;
+}
+export type PageStats = {
+  _tag: 'Ok';
+  siteId: string;
+  path: string;
+  period: Period;
+  window: DateWindow;
+  /** `null` when the Hosted record does not hold the preceding window. */
+  previousWindow: DateWindow | null;
+  totals: MetricTotals;
+  previousTotals: MetricTotals | null;
+  /** One point per day of `window`, ascending. Days without data are zero. */
+  daily: DailyPoint[];
+  /** One point per day of `previousWindow`, ascending. */
+  previousDaily: DailyPoint[] | null;
+  /** The queries that earned the page impressions, most clicks first. */
+  queries: QueryRow[];
+  /** The page in the gscdump.com dashboard. */
+  dashboardUrl: string;
+} | {
+  _tag: 'InvalidPage';
+  page: string;
+} | {
+  _tag: 'SiteUnavailable';
+  context: Exclude<GscdumpContext, {
+    _tag: 'Ready';
+  }>;
+} | {
+  _tag: 'NoData';
+  siteId: string;
+  message: string;
+} | {
+  _tag: 'RateLimited';
+} | {
+  _tag: 'Failed';
+  message: string;
+  requestId: string | null;
+};

package/dist/shared/protocol.mjs

@@ -0,0 +1,19 @@
+const DEVFRAME_ID = "gscdump";
+const PERIODS = [
+	{
+		value: "7d",
+		label: "Last 7 days",
+		days: 7
+	},
+	{
+		value: "28d",
+		label: "Last 28 days",
+		days: 28
+	},
+	{
+		value: "3m",
+		label: "Last 3 months",
+		days: 90
+	}
+];
+export { DEVFRAME_ID, PERIODS };

package/dist/vite.d.mts

@@ -0,0 +1,17 @@
+import { GscdumpDevframeOptions } from "./index.mjs";
+import { createPluginFromDevframe } from "@vitejs/devtools-kit/node";
+/**
+ * The gscdump devframe as a Vite plugin. Vite DevTools mounts it as a dock.
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { gscdump } from '@gscdump/devframe/vite'
+ *
+ * export default defineConfig({
+ *   devtools: true,
+ *   plugins: [gscdump({ site: 'example.com' })],
+ * })
+ * ```
+ */
+export declare function gscdump(options?: GscdumpDevframeOptions): ReturnType<typeof createPluginFromDevframe>;
+export { gscdump as default };

package/dist/vite.mjs

@@ -0,0 +1,6 @@
+import { createGscdumpDevframe } from "./index.mjs";
+import { createPluginFromDevframe } from "@vitejs/devtools-kit/node";
+function gscdump(options = {}) {
+	return createPluginFromDevframe(createGscdumpDevframe(options));
+}
+export { gscdump as default, gscdump };