@gscdump/devframe 0.0.0-stage → 5.7.1

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,18 @@
+import { DailyPoint, DateWindow, GscdumpContext, MetricTotals, PageStats, PageStatsInput, Period, QueryRow, SiteSummary } from "./shared/protocol.mjs";
+import { HostedSourceOptions } from "./sources/hosted.mjs";
+import { DevframeDefinition } from "devframe";
+export interface GscdumpDevframeOptions extends HostedSourceOptions {
+  /** The Site to read: a Site ID, a Site URL, or its host. Optional when the credential holds one Site. */
+  site?: string;
+  /** 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 HostedSourceOptions, type MetricTotals, type PageStats, type PageStatsInput, type Period, type QueryRow, type SiteSummary, createGscdumpDevframe as default };

package/dist/index.mjs

@@ -0,0 +1,53 @@
+import { description, homepage, name, version } from "./package.mjs";
+import { DEVFRAME_ID } from "./shared/protocol.mjs";
+import { createPageStatsReader } from "./reader.mjs";
+import { createRpcFunctions } from "./rpc.mjs";
+import { createHostedSource } from "./sources/hosted.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 source = createHostedSource(options, {
+				fetch: options.fetch ?? globalThis.fetch,
+				env,
+				readCliAuthentication: () => readCliAuthentication(env)
+			});
+			const reader = createPageStatsReader({ site: options.site }, source, 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.1";
+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.mjs

@@ -0,0 +1,215 @@
+import { hostOf } from "./source.mjs";
+import { matchSite } from "./account.mjs";
+import { addDays, dashboardPageUrl, pagePathOf, parseQueryRows, periodWindows, summariseDaily } from "./page-stats.mjs";
+import { PERIODS } from "./shared/protocol.mjs";
+import { periodToDateRange } from "@gscdump/sdk/period";
+const SITES_TTL_MS = 3e5;
+const STATS_TTL_MS = 3e5;
+const TOP_QUERIES = 25;
+function periodDays(period) {
+	return PERIODS.find((option) => option.value === period)?.days ?? 28;
+}
+function contextForPage(sites, pageUrl, preferredSiteId) {
+	const host = hostOf(pageUrl) ?? pageUrl;
+	const matches = sites.filter((site) => site.host === host);
+	if (matches.length === 0) return {
+		_tag: "NoSiteForPage",
+		host
+	};
+	const pick = matches.find((site) => site.siteId === preferredSiteId) ?? (matches.length === 1 ? matches[0] : void 0);
+	return pick ? {
+		_tag: "Ready",
+		site: pick,
+		sites: matches,
+		configured: false
+	} : {
+		_tag: "SiteRequired",
+		sites: matches,
+		target: host
+	};
+}
+function createPageStatsReader(options, source, now) {
+	let sitesCache = null;
+	const stats = /* @__PURE__ */ new Map();
+	function readSites() {
+		if (sitesCache && now() - sitesCache.at < SITES_TTL_MS) return sitesCache.value;
+		const value = source.sites();
+		sitesCache = {
+			at: now(),
+			value
+		};
+		value.then((result) => {
+			if (result._tag === "Blocked" && sitesCache?.value === value) sitesCache = null;
+		}, () => {
+			if (sitesCache?.value === value) sitesCache = null;
+		});
+		return value;
+	}
+	async function context(preferredSiteId, pageUrl) {
+		const read = await readSites();
+		if (read._tag === "Blocked") return read.context;
+		const sites = read.sites;
+		if (sites.length === 0) return { _tag: "NoSites" };
+		if (options.site) {
+			const match = matchSite(sites, options.site);
+			if (match._tag === "Found") return {
+				_tag: "Ready",
+				site: match.site,
+				sites,
+				configured: true
+			};
+			const picked = preferredSiteId ? sites.find((site) => site.siteId === preferredSiteId) : void 0;
+			return picked ? {
+				_tag: "Ready",
+				site: picked,
+				sites,
+				configured: false
+			} : {
+				_tag: "SiteRequired",
+				sites,
+				target: options.site
+			};
+		}
+		if (options.siteFromPage && pageUrl) return contextForPage(sites, pageUrl, preferredSiteId ?? null);
+		const preferred = preferredSiteId ? sites.find((site) => site.siteId === preferredSiteId) : void 0;
+		if (preferred) return {
+			_tag: "Ready",
+			site: preferred,
+			sites,
+			configured: false
+		};
+		const match = matchSite(sites, null);
+		return match._tag === "Found" ? {
+			_tag: "Ready",
+			site: match.site,
+			sites,
+			configured: false
+		} : {
+			_tag: "SiteRequired",
+			sites,
+			target: null
+		};
+	}
+	async function siteForPage(input) {
+		if (!options.siteFromPage) return context(input.siteId);
+		const read = await readSites();
+		if (read._tag === "Blocked") return read.context;
+		const chosen = input.siteId ? read.sites.find((site) => site.siteId === input.siteId) : void 0;
+		if (chosen) return {
+			_tag: "Ready",
+			site: chosen,
+			sites: read.sites,
+			configured: false
+		};
+		return /^https?:\/\//i.test(input.page) ? contextForPage(read.sites, input.page, null) : {
+			_tag: "SiteRequired",
+			sites: read.sites,
+			target: null
+		};
+	}
+	function firstFailure(daily, queries) {
+		if (daily._tag !== "Ok") return daily;
+		return queries._tag !== "Ok" ? queries : null;
+	}
+	async function readPage(site, path, period, windows, retried) {
+		const span = {
+			start: windows.previous?.start ?? windows.current.start,
+			end: windows.current.end
+		};
+		const [daily, queries] = await Promise.all([source.dailyRows(site.siteId, path, span), source.queryRows(site.siteId, path, windows.current, TOP_QUERIES)]);
+		const failure = firstFailure(daily, queries);
+		if (!failure && daily._tag === "Ok" && queries._tag === "Ok") return {
+			_tag: "Ok",
+			siteId: site.siteId,
+			path,
+			period,
+			window: windows.current,
+			previousWindow: windows.previous,
+			...summariseDaily(daily.rows, windows),
+			queries: parseQueryRows(queries.rows),
+			dashboardUrl: dashboardPageUrl(source.dashboardOrigin, site, path)
+		};
+		switch (failure?._tag) {
+			case "Refused": {
+				const refusal = failure.refusal;
+				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(site, path, period, shifted, true);
+				}
+				return refusal.reason === "record_not_ready" ? {
+					_tag: "NoData",
+					siteId: site.siteId,
+					message: "gscdump has not prepared this Site's record for reads yet. Try again in a few minutes."
+				} : {
+					_tag: "NoData",
+					siteId: site.siteId,
+					message: `The Site's record does not hold ${refusal.missingStart} to ${refusal.missingEnd} yet.`
+				};
+			}
+			case "RateLimited": return { _tag: "RateLimited" };
+			case "Unauthorized":
+				sitesCache = null;
+				return {
+					_tag: "SiteUnavailable",
+					context: failure.context
+				};
+			case "Failed": return {
+				_tag: "Failed",
+				message: failure.message,
+				requestId: failure.requestId
+			};
+			default: return {
+				_tag: "Failed",
+				message: "The read returned no rows and no error.",
+				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 siteForPage(input);
+		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 && now() - hit.at < STATS_TTL_MS) return hit.value;
+		const stableEnd = periodToDateRange(period, { now: new Date(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(site, path, period, windows, false);
+		stats.set(key, {
+			at: 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 { createPageStatsReader };

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, pageUrl) => reader.context(preferredSiteId ?? null, pageUrl ?? 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,106 @@
+export type Period = '7d' | '28d' | '3m';
+export interface SiteSummary {
+  siteId: string;
+  /** The Site as gscdump registered it, for example `example.com`. */
+  siteUrl: string;
+  /** The exact host the Site covers, for example `example.com`. A page on another host is not on this Site. */
+  host: 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 panel can read, decided once per panel boot and again when the
+ * page's host changes. 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: 'NoSiteForPage';
+  host: string;
+} | BlockedContext;
+/** A context that stops before any Site is chosen: no credential, no Sites, or no service. */
+export type BlockedContext = {
+  _tag: 'NoSites';
+} | {
+  _tag: 'CredentialMissing';
+} | {
+  _tag: 'CredentialRejected';
+  source: CredentialSource;
+} | {
+  _tag: 'SignedOut';
+  signInUrl: string;
+} | {
+  _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/source.d.mts

@@ -0,0 +1 @@
+import "./shared/protocol.mjs";

package/dist/source.mjs

@@ -0,0 +1,7 @@
+function hostOf(value) {
+	const text = value.trim();
+	if (text.startsWith("sc-domain:")) return text.slice(10).toLowerCase().replace(/\.$/, "") || null;
+	const url = URL.parse(/^[a-z][a-z\d+.-]*:\/\//i.test(text) ? text : `https://${text}`);
+	return url?.hostname ? url.hostname.toLowerCase() : null;
+}
+export { hostOf };

package/dist/sources/hosted.d.mts

@@ -0,0 +1,7 @@
+import "../source.mjs";
+export interface HostedSourceOptions {
+  /** 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;
+}