@power-seo/search-console

Typed Google Search Console API client for TypeScript — OAuth2 and service account auth, auto-paginated search analytics, URL inspection, and sitemap management with zero boilerplate.

@power-seo/search-console is a production-ready Google Search Console API client for TypeScript. Provide OAuth2 credentials or a service account key — get back fully typed search analytics rows, URL inspection verdicts, and sitemap management operations. The token manager handles refresh cycles and JWT signing automatically. querySearchAnalyticsAll() transparently pages through the 25,000-row GSC API limit, merging all results into a single array. Use it in Next.js API routes, Remix loaders, Node.js scripts, and CI/CD pipelines. All operations are server-side only — service account credentials must never be exposed to the browser.

Zero runtime dependencies — pure TypeScript with native fetch and crypto; no googleapis package required.

Why @power-seo/search-console?

Features

• OAuth2 authentication — createTokenManager({ type: 'oauth' }) handles token refresh automatically
• Service account JWT authentication — createTokenManager({ type: 'service-account' }) signs JWTs for server-to-server access without user interaction
• Low-level auth primitives — exchangeRefreshToken() and getServiceAccountToken() for custom auth flows
• Typed GSC client — createGSCClient(config) returns a GSCClient scoped to a specific verified site URL
• Search analytics — querySearchAnalytics() supports all 6 dimensions: query, page, country, device, date, searchAppearance
• All search types — web, image, video, and news search types
• Auto-paginated full fetch — querySearchAnalyticsAll() merges all pages into one SearchAnalyticsRow[] array
• URL inspection — inspectUrl() returns verdict, indexing state, last crawl time, mobile usability, and rich result status
• Direct URL inspection — inspectUrlDirect() for the direct URL inspection API endpoint
• Sitemap listing — listSitemaps() with status, last download time, and error counts
• Sitemap submission and deletion — submitSitemap() and deleteSitemap()
• Typed error handling — GSCApiError class with status, code, and message
• Full TypeScript support — complete type definitions for all request and response shapes

Comparison

Installation

npm install @power-seo/search-console

yarn add @power-seo/search-console

pnpm add @power-seo/search-console

Quick Start

import {
  createTokenManager,
  createGSCClient,
  querySearchAnalyticsAll,
} from '@power-seo/search-console';

// 1. Create a token manager (OAuth2)
import { exchangeRefreshToken } from '@power-seo/search-console';

const tokenManager = createTokenManager(() =>
  exchangeRefreshToken({
    clientId: process.env.GSC_CLIENT_ID!,
    clientSecret: process.env.GSC_CLIENT_SECRET!,
    refreshToken: process.env.GSC_REFRESH_TOKEN!,
  }),
);

// 2. Create a client scoped to your site
const client = createGSCClient({
  siteUrl: 'https://example.com',
  auth: tokenManager,
});

// 3. Fetch all search analytics data (auto-paginated)
const rows = await querySearchAnalyticsAll(client, {
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  dimensions: ['query', 'page'],
});

rows.forEach(({ keys, clicks, impressions, ctr, position }) => {
  console.log(`Query: "${keys[0]}", Page: ${keys[1]}`);
  console.log(`  ${clicks} clicks, ${impressions} impressions, pos ${position.toFixed(1)}`);
});

Usage

OAuth2 Authentication

import { createTokenManager, exchangeRefreshToken } from '@power-seo/search-console';

const tokenManager = createTokenManager(() =>
  exchangeRefreshToken({
    clientId: process.env.GSC_CLIENT_ID!,
    clientSecret: process.env.GSC_CLIENT_SECRET!,
    refreshToken: process.env.GSC_REFRESH_TOKEN!,
  }),
);

const accessToken = await tokenManager.getToken();

Service Account Authentication

import { createTokenManager, getServiceAccountToken } from '@power-seo/search-console';
import { subtle } from 'node:crypto';

// Parse service account JSON and create signing function
const serviceAccount = JSON.parse(process.env.GSC_SERVICE_ACCOUNT_JSON!);

async function signJwt(payload: Record<string, unknown>): Promise<string> {
  // Implement JWT signing using node:crypto or your preferred library
  // Returns signed JWT assertion string
}

const tokenManager = createTokenManager(() =>
  getServiceAccountToken({
    clientEmail: serviceAccount.client_email,
    privateKeyId: serviceAccount.private_key_id,
    signJwt,
  }),
);

Search Analytics Query

import { createGSCClient, querySearchAnalytics } from '@power-seo/search-console';

const client = createGSCClient({ siteUrl: 'https://example.com', tokenManager });

const response = await querySearchAnalytics(client, {
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  dimensions: ['query', 'country'],
  searchType: 'web',
  rowLimit: 5000,
});

// response.rows → SearchAnalyticsRow[]

Auto-Paginated Full Fetch

import { querySearchAnalyticsAll } from '@power-seo/search-console';

// Fetches all rows automatically — handles the 25,000-row API limit
const allRows = await querySearchAnalyticsAll(client, {
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  dimensions: ['query'],
});

console.log(`Total rows: ${allRows.length}`);

URL Inspection

import { inspectUrl } from '@power-seo/search-console';

const result = await inspectUrl(client, 'https://example.com/blog/my-post');

console.log(result.verdict); // 'PASS' | 'FAIL' | 'NEUTRAL'
console.log(result.indexingState); // 'INDEXING_ALLOWED' | ...
console.log(result.lastCrawlTime); // ISO timestamp
console.log(result.mobileUsabilityResult.verdict); // 'PASS' | 'FAIL'

Sitemap Management

import { listSitemaps, submitSitemap, deleteSitemap } from '@power-seo/search-console';

// List all submitted sitemaps
const sitemaps = await listSitemaps(client);
// sitemaps.sitemap → SitemapEntry[]

// Submit a new sitemap
await submitSitemap(client, 'https://example.com/sitemap.xml');

// Delete an old sitemap
await deleteSitemap(client, 'https://example.com/old-sitemap.xml');

CI/CD Keyword Position Check

import {
  createTokenManager,
  createGSCClient,
  querySearchAnalyticsAll,
  getServiceAccountToken,
} from '@power-seo/search-console';
import { subtle } from 'node:crypto';

// Parse service account JSON from environment
const serviceAccount = JSON.parse(process.env.GSC_SERVICE_ACCOUNT_JSON!);

async function signJwt(payload: Record<string, unknown>): Promise<string> {
  // Sign JWT assertion using node:crypto
  // Implementation depends on your preferred JWT signing library
  throw new Error('Implement JWT signing');
}

const tokenManager = createTokenManager(() =>
  getServiceAccountToken({
    clientEmail: serviceAccount.client_email,
    privateKeyId: serviceAccount.private_key_id,
    signJwt,
  }),
);

const client = createGSCClient({ siteUrl: 'sc-domain:example.com', tokenManager });

const rows = await querySearchAnalyticsAll(client, {
  startDate: '2026-01-24',
  endDate: '2026-01-31',
  dimensions: ['query', 'page'],
});

const dropped = rows.filter((r) => r.position > 20 && r.impressions > 100);
if (dropped.length > 0) {
  console.error('Pages dropped below position 20:');
  dropped.forEach((r) => console.error(' -', r.keys[1], `pos ${r.position.toFixed(1)}`));
  process.exit(1);
}

API Reference

createTokenManager(fetchToken)

Returns TokenManager: { getToken(): Promise<string>; invalidate(): void }. Token caching and refresh is handled automatically.

createGSCClient(config)

Returns GSCClient.

querySearchAnalytics(client, request)

querySearchAnalyticsAll(client, request)

Same parameters as querySearchAnalytics() but rowLimit and startRow are managed automatically. Returns Promise<SearchAnalyticsRow[]>.

inspectUrl(client, url) / inspectUrlDirect(client, url)

Returns Promise<InspectionResult>: { verdict, indexingState, lastCrawlTime, mobileUsabilityResult, richResultsResult, ... }.

listSitemaps(client) / submitSitemap(client, url) / deleteSitemap(client, url)

listSitemaps() returns Promise<SitemapListResponse>. submitSitemap() and deleteSitemap() return Promise<void>.

Types

Use Cases

• Automated keyword ranking reports — fetch all queries weekly and diff against the previous week
• Indexing health monitoring — inspectUrl() after deployments to verify new pages are indexed
• Content gap analysis — merge GSC data with @power-seo/analytics to find high-impression, low-click pages
• Sitemap automation — submit new sitemaps programmatically after content migrations
• CI/CD SEO checks — fail pipelines when key pages drop below a position threshold
• Multi-site SaaS dashboards — aggregate GSC data across multiple client properties with one GSCClient per site
• Image and news search analytics — query image and news search types separately
• Country and device breakdowns — segment click data by country or device for regional SEO analysis

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Server-side only — requires crypto for JWT signing; not edge or browser compatible
• Zero runtime dependencies — no googleapis package; uses native fetch and crypto
• Auto-pagination — querySearchAnalyticsAll() manages rowOffset and array merging transparently
• Token caching — access tokens are cached and reused until 5 minutes before expiry
• Scoped clients — each GSCClient is scoped to one verified GSC property via siteUrl
• Typed errors — GSCApiError carries HTTP status, error code, and message for reliable error handling
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access outside of GSC API calls
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for Node.js 18+ server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License