Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import { getGoogleAccessToken } from "@/server/features/google/googleOAuth";
import { getGoogleAccessMode } from "@/server/features/google/googleAccess";
import { getGatewayGoogleFetch } from "@/server/features/google/gatewayGoogle";
import { GSC_OAUTH_PROVIDER_ID } from "@/shared/gsc";
import { GscApiError, GscTokenError } from "./gscErrors";
export { GscApiError, GscTokenError } from "./gscErrors";
const GSC_API_BASE = "https://www.googleapis.com/webmasters/v3";
const GOOGLE_USERINFO_URL = "https://openidconnect.googleapis.com/v1/userinfo";
/** A GSC REST call returned a non-2xx status. `status` drives user-facing messaging. */
export type GscSite = {
siteUrl: string;
permissionLevel: string;
};
export type GscSearchAnalyticsRow = {
keys?: string[];
clicks: number;
impressions: number;
ctr: number;
position: number;
};
export type GscDimensionFilter = {
dimension: string;
operator: string;
expression: string;
};
export type GscSearchAnalyticsRequest = {
startDate: string;
endDate: string;
dimensions?: string[];
dimensionFilterGroups?: Array<{
groupType: "and" | "or";
filters: GscDimensionFilter[];
}>;
rowLimit?: number;
startRow?: number;
type?: string;
dataState?: string;
aggregationType?: string;
};
/** Subset of the URL Inspection API `inspectionResult` we surface. The wire
* shape is richer; extra fields are ignored. */
export type UrlInspectionResult = {
indexStatusResult?: {
verdict?: string;
coverageState?: string;
robotsTxtState?: string;
indexingState?: string;
lastCrawlTime?: string;
pageFetchState?: string;
googleCanonical?: string;
userCanonical?: string;
crawledAs?: string;
sitemap?: string[];
referringUrls?: string[];
};
mobileUsabilityResult?: { verdict?: string };
richResultsResult?: { verdict?: string };
inspectionResultLink?: string;
};
function messageForStatus(status: number, body: string): string {
if (status === 401 || status === 403) {
return "Search Console denied access to this property (no verified permission, or the connection was revoked).";
}
if (status === 429) {
return "Search Console rate limit reached. Retry shortly.";
}
if (status === 404) {
return "Search Console property not found. It may have been removed in Search Console.";
}
return `Search Console API error (${status}): ${body.slice(0, 300)}`;
}
/** Free Google Search Console client. Unlike the DataForSEO client it does NOT
* meter credits — GSC is first-party data with no per-call cost. Access tokens
* come from (and are auto-refreshed against) the connector's stored
* google-search-console grant. */
export function createGscClient(opts: {
userId: string;
gscAccountId?: string;
}) {
// One mint per client: a client lives for a single service call, and
// concurrent requests (inspectUrls fans out) must not race the refresh.
let tokenPromise: Promise<string> | undefined;
function getToken(): Promise<string> {
tokenPromise ??= getGoogleAccessToken({
providerId: GSC_OAUTH_PROVIDER_ID,
userId: opts.userId,
accountId: opts.gscAccountId,
}).catch((error: unknown) => {
tokenPromise = undefined;
throw new GscTokenError(
"Could not mint a Search Console access token (grant revoked or expired).",
error,
);
});
return tokenPromise;
}
/**
* The fetch and the headers that reach Google authenticated: behind the
* gateway, the gateway's fetch puts the member's token on the call
* (gatewayGoogle.ts); otherwise OpenSEO's own grant mints one.
*/
async function authenticated(): Promise<{
fetch: typeof fetch;
headers: Record<string, string>;
}> {
if ((await getGoogleAccessMode()) === "gateway") {
const gatewayFetch = await getGatewayGoogleFetch();
if (!gatewayFetch) {
throw new GscTokenError(
"Google isn't reachable through the Every App gateway here.",
);
}
return { fetch: gatewayFetch, headers: {} };
}
return {
fetch,
headers: { Authorization: `Bearer ${await getToken()}` },
};
}
async function request<T>(
url: string,
init?: { method?: string; body?: unknown },
): Promise<T> {
const { fetch: send, headers } = await authenticated();
const hasBody = init?.body !== undefined;
const response = await send(url, {
method: init?.method ?? "GET",
headers: {
...headers,
...(hasBody ? { "Content-Type": "application/json" } : {}),
},
body: hasBody ? JSON.stringify(init?.body) : undefined,
});
if (!response.ok) {
const body = await response.text().catch(() => "");
throw new GscApiError(
response.status,
messageForStatus(response.status, body),
body,
);
}
return (await response.json()) as T;
}
return {
async getUserInfoEmail(): Promise<string | null> {
const data = await request<{ email?: unknown }>(GOOGLE_USERINFO_URL);
return typeof data.email === "string" ? data.email : null;
},
/** Webmasters API `sites.list` — the verified properties on the grant. */
async listSites(): Promise<GscSite[]> {
const data = await request<{ siteEntry?: GscSite[] }>(
`${GSC_API_BASE}/sites`,
);
return data.siteEntry ?? [];
},
/** Webmasters API `searchAnalytics.query`. siteUrl is used verbatim. */
async querySearchAnalytics(
siteUrl: string,
body: GscSearchAnalyticsRequest,
): Promise<GscSearchAnalyticsRow[]> {
const data = await request<{ rows?: GscSearchAnalyticsRow[] }>(
`${GSC_API_BASE}/sites/${encodeURIComponent(siteUrl)}/searchAnalytics/query`,
{ method: "POST", body },
);
return data.rows ?? [];
},
/** URL Inspection API `urlInspection.index.inspect`. This lives on a
* different host than the Webmasters v3 base, so the full URL is passed to
* the request helper. Same `webmasters.readonly` scope. */
async inspectUrl(
siteUrl: string,
inspectionUrl: string,
languageCode?: string,
): Promise<UrlInspectionResult | null> {
const data = await request<{ inspectionResult?: UrlInspectionResult }>(
"https://searchconsole.googleapis.com/v1/urlInspection/index:inspect",
{
method: "POST",
body: {
siteUrl,
inspectionUrl,
...(languageCode ? { languageCode } : {}),
},
},
);
return data.inspectionResult ?? null;
},
};
}