@power-seo/search-console 1.0.7 → 1.0.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +236 -237
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,76 +1,89 @@
|
|
|
1
|
-
# @power-seo/search-console
|
|
1
|
+
# @power-seo/search-console
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://www.npmjs.com/package/@power-seo/search-console)
|
|
5
|
-
[](../../LICENSE)
|
|
6
|
-
[](https://www.typescriptlang.org/)
|
|
7
|
-
[](#)
|
|
3
|
+
|
|
8
4
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
## Overview
|
|
12
|
-
|
|
13
|
-
**@power-seo/search-console** is a production-ready Google Search Console API client for TypeScript that helps you query search analytics, inspect URLs, and manage sitemaps — without writing OAuth2 token refresh boilerplate or pagination loops.
|
|
14
|
-
|
|
15
|
-
**What it does**
|
|
16
|
-
|
|
17
|
-
- ✅ **OAuth2 and service account auth** — `createTokenManager()` handles token refresh cycles and JWT signing automatically
|
|
18
|
-
- ✅ **Search analytics queries** — clicks, impressions, CTR, and position by query, page, country, device, date
|
|
19
|
-
- ✅ **Auto-paginated full fetch** — `querySearchAnalyticsAll()` transparently pages through the 25,000-row GSC API limit
|
|
20
|
-
- ✅ **URL inspection** — indexing verdict, last crawl time, canonical URL, mobile usability, rich result status
|
|
21
|
-
- ✅ **Sitemap management** — list, submit, and delete sitemaps from verified GSC properties
|
|
5
|
+
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.
|
|
22
6
|
|
|
23
|
-
|
|
7
|
+
[](https://www.npmjs.com/package/@power-seo/search-console)
|
|
8
|
+
[](https://www.npmjs.com/package/@power-seo/search-console)
|
|
9
|
+
[](https://socket.dev/npm/package/@power-seo/search-console)
|
|
10
|
+
[](https://github.com/CyberCraftBD/power-seo/actions)
|
|
11
|
+
[](https://opensource.org/licenses/MIT)
|
|
12
|
+
[](https://www.typescriptlang.org/)
|
|
13
|
+
[](https://bundlephobia.com/package/@power-seo/search-console)
|
|
24
14
|
|
|
25
|
-
-
|
|
26
|
-
- ❌ **Not a site verification tool** — requires a property already verified in Google Search Console
|
|
15
|
+
`@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.
|
|
27
16
|
|
|
28
|
-
**
|
|
29
|
-
|
|
30
|
-
- **SEO automation pipelines**, **CI/CD keyword tracking**, **SaaS analytics dashboards**, and **reporting scripts** using GSC data
|
|
17
|
+
> **Zero runtime dependencies** — pure TypeScript with native `fetch` and `crypto`; no googleapis package required.
|
|
31
18
|
|
|
32
19
|
---
|
|
33
20
|
|
|
34
|
-
## Why @power-seo/search-console
|
|
35
|
-
|
|
36
|
-
**The problem**
|
|
37
|
-
|
|
38
|
-
- **OAuth2 token refresh is complex** — access tokens expire every hour; service account JWT signing requires crypto operations
|
|
39
|
-
- **GSC returns only 25,000 rows per request** — sites with many queries need pagination loops that every team reimplements
|
|
40
|
-
- **URL inspection data is inaccessible without auth** — no simple way to check indexing status programmatically
|
|
21
|
+
## Why @power-seo/search-console?
|
|
41
22
|
|
|
42
|
-
|
|
23
|
+
| | Without | With |
|
|
24
|
+
| -------------------- | ------------------------------------------- | --------------------------------------------------------- |
|
|
25
|
+
| OAuth2 token refresh | ❌ 50+ lines of boilerplate per project | ✅ Auto-refresh via `createTokenManager()` |
|
|
26
|
+
| GSC data pagination | ❌ Manual rowOffset loops and array merging | ✅ `querySearchAnalyticsAll()` — one call, all rows |
|
|
27
|
+
| URL inspection | ❌ Manual GSC UI check only | ✅ Programmatic `inspectUrl()` in CI pipelines |
|
|
28
|
+
| Service accounts | ❌ Complex JWT signing setup | ✅ `createTokenManager({ type: 'service-account' })` |
|
|
29
|
+
| Type safety | ❌ Raw API responses typed as `any` | ✅ Fully typed request and response shapes |
|
|
30
|
+
| Sitemap management | ❌ Manual GSC UI operations | ✅ `submitSitemap()`, `listSitemaps()`, `deleteSitemap()` |
|
|
31
|
+
| Framework support | ❌ Tied to googleapis setup | ✅ Works in Next.js, Remix, Node.js, CI/CD |
|
|
43
32
|
|
|
44
|
-
|
|
45
|
-
- **Performance:** Auto-paginated `querySearchAnalyticsAll` eliminates boilerplate that slows down analytics pipelines
|
|
46
|
-
- **UX:** URL inspection in CI enables instant indexing health checks after deployments
|
|
33
|
+
|
|
47
34
|
|
|
48
35
|
---
|
|
49
36
|
|
|
50
|
-
##
|
|
37
|
+
## Features
|
|
51
38
|
|
|
52
39
|
- **OAuth2 authentication** — `createTokenManager({ type: 'oauth' })` handles token refresh automatically
|
|
53
|
-
- **Service account JWT authentication** — `createTokenManager({ type: 'service-account' })` signs JWTs for server-to-server access
|
|
40
|
+
- **Service account JWT authentication** — `createTokenManager({ type: 'service-account' })` signs JWTs for server-to-server access without user interaction
|
|
54
41
|
- **Low-level auth primitives** — `exchangeRefreshToken()` and `getServiceAccountToken()` for custom auth flows
|
|
55
|
-
- **Typed GSC client** — `createGSCClient(config)` returns a `GSCClient` scoped to a specific site URL
|
|
42
|
+
- **Typed GSC client** — `createGSCClient(config)` returns a `GSCClient` scoped to a specific verified site URL
|
|
56
43
|
- **Search analytics** — `querySearchAnalytics()` supports all 6 dimensions: `query`, `page`, `country`, `device`, `date`, `searchAppearance`
|
|
57
44
|
- **All search types** — `web`, `image`, `video`, and `news` search types
|
|
58
|
-
- **Auto-paginated full fetch** — `querySearchAnalyticsAll()` merges all pages into
|
|
45
|
+
- **Auto-paginated full fetch** — `querySearchAnalyticsAll()` merges all pages into one `SearchAnalyticsRow[]` array
|
|
59
46
|
- **URL inspection** — `inspectUrl()` returns verdict, indexing state, last crawl time, mobile usability, and rich result status
|
|
60
|
-
- **Direct URL inspection** — `inspectUrlDirect()` for the direct URL inspection endpoint
|
|
47
|
+
- **Direct URL inspection** — `inspectUrlDirect()` for the direct URL inspection API endpoint
|
|
61
48
|
- **Sitemap listing** — `listSitemaps()` with status, last download time, and error counts
|
|
62
49
|
- **Sitemap submission and deletion** — `submitSitemap()` and `deleteSitemap()`
|
|
63
50
|
- **Typed error handling** — `GSCApiError` class with `status`, `code`, and `message`
|
|
64
|
-
- **
|
|
51
|
+
- **Full TypeScript support** — complete type definitions for all request and response shapes
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Comparison
|
|
58
|
+
|
|
59
|
+
| Feature | google-auth-library | googleapis | custom fetch | @power-seo/search-console |
|
|
60
|
+
| ---------------------------------- | :-----------------: | :--------: | :----------: | :-----------------------: |
|
|
61
|
+
| OAuth2 token auto-refresh | ✅ | ✅ | ❌ | ✅ |
|
|
62
|
+
| Service account JWT signing | ✅ | ✅ | ❌ | ✅ |
|
|
63
|
+
| Auto-paginated analytics fetch | ❌ | ❌ | ❌ | ✅ |
|
|
64
|
+
| Typed GSC-specific response shapes | ❌ | ⚠️ | ❌ | ✅ |
|
|
65
|
+
| URL inspection support | ❌ | ⚠️ | ❌ | ✅ |
|
|
66
|
+
| Sitemap management | ❌ | ⚠️ | ❌ | ✅ |
|
|
67
|
+
| Zero runtime dependencies | ❌ | ❌ | ✅ | ✅ |
|
|
68
|
+
| TypeScript-first | ❌ | ⚠️ | ❌ | ✅ |
|
|
69
|
+
|
|
70
|
+
|
|
65
71
|
|
|
66
72
|
---
|
|
67
73
|
|
|
68
|
-
##
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npm install @power-seo/search-console
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
yarn add @power-seo/search-console
|
|
82
|
+
```
|
|
69
83
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
- **Faster delivery**: Connect to GSC in minutes; no OAuth2 library research required
|
|
84
|
+
```bash
|
|
85
|
+
pnpm add @power-seo/search-console
|
|
86
|
+
```
|
|
74
87
|
|
|
75
88
|
---
|
|
76
89
|
|
|
@@ -110,185 +123,133 @@ rows.forEach(({ keys, clicks, impressions, ctr, position }) => {
|
|
|
110
123
|
});
|
|
111
124
|
```
|
|
112
125
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
- A merged `SearchAnalyticsRow[]` array with all query-page combinations for the date range
|
|
116
|
-
- `clicks`, `impressions`, `ctr`, and `position` for each row
|
|
117
|
-
|
|
118
|
-
---
|
|
119
|
-
|
|
120
|
-
## Installation
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
npm i @power-seo/search-console
|
|
124
|
-
# or
|
|
125
|
-
yarn add @power-seo/search-console
|
|
126
|
-
# or
|
|
127
|
-
pnpm add @power-seo/search-console
|
|
128
|
-
# or
|
|
129
|
-
bun add @power-seo/search-console
|
|
130
|
-
```
|
|
126
|
+
|
|
131
127
|
|
|
132
128
|
---
|
|
133
129
|
|
|
134
|
-
##
|
|
130
|
+
## Usage
|
|
135
131
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
- ✅ Next.js (App Router / Pages Router) — use in API routes or server actions
|
|
139
|
-
- ✅ Remix — use in loader functions and server-side actions
|
|
140
|
-
- ✅ Node.js 18+ — pure TypeScript client with `fetch` API
|
|
141
|
-
- ✅ CI/CD pipelines — run as standalone Node scripts in GitHub Actions or similar
|
|
142
|
-
|
|
143
|
-
**Environment notes**
|
|
144
|
-
|
|
145
|
-
- **SSR/SSG:** Fully supported — all operations are server-side
|
|
146
|
-
- **Edge runtime:** Not supported (requires crypto for JWT signing)
|
|
147
|
-
- **Browser-only usage:** Not supported — exposes credentials; server-side only
|
|
148
|
-
|
|
149
|
-
---
|
|
132
|
+
### OAuth2 Authentication
|
|
150
133
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
- **Automated keyword ranking reports** — fetch all queries weekly and diff against previous week
|
|
154
|
-
- **Indexing health monitoring** — `inspectUrl` after deployments to verify new pages are indexed
|
|
155
|
-
- **Content gap analysis** — merge GSC data with `@power-seo/analytics` to find high-impression, low-click pages
|
|
156
|
-
- **Sitemap automation** — submit new sitemaps programmatically after content migrations
|
|
157
|
-
- **CI/CD SEO checks** — fail pipelines when key pages drop below position threshold
|
|
158
|
-
- **Multi-site SaaS dashboards** — aggregate GSC data across multiple client properties
|
|
159
|
-
- **Image and news search analytics** — query `image` and `news` search types separately
|
|
160
|
-
- **Country and device breakdowns** — segment click data by country or device for regional SEO
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## Example (Before / After)
|
|
134
|
+
```ts
|
|
135
|
+
import { createTokenManager } from '@power-seo/search-console';
|
|
165
136
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
137
|
+
const tokenManager = createTokenManager({
|
|
138
|
+
type: 'oauth',
|
|
139
|
+
clientId: process.env.GSC_CLIENT_ID!,
|
|
140
|
+
clientSecret: process.env.GSC_CLIENT_SECRET!,
|
|
141
|
+
refreshToken: process.env.GSC_REFRESH_TOKEN!,
|
|
142
|
+
});
|
|
171
143
|
|
|
172
|
-
|
|
173
|
-
- createTokenManager({ type: 'oauth', ... }) → tokens auto-refresh before every request
|
|
174
|
-
- querySearchAnalyticsAll(client, { dimensions: ['query'] }) → one call, complete dataset
|
|
175
|
-
- inspectUrl(client, url) → { verdict: 'PASS', lastCrawlTime: '...', mobileUsabilityResult: {...} }
|
|
144
|
+
const { accessToken } = await tokenManager.getAccessToken();
|
|
176
145
|
```
|
|
177
146
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
## Implementation Best Practices
|
|
181
|
-
|
|
182
|
-
- **Use service accounts for CI/CD** — service accounts don't expire and don't require user interaction
|
|
183
|
-
- **Cache `querySearchAnalyticsAll` results** — GSC data is delayed by ~2 days; daily fetches are sufficient
|
|
184
|
-
- **Use `sc-domain:` prefix for domain properties** — e.g. `sc-domain:example.com` for domain-level verification
|
|
185
|
-
- **Add service account email as GSC user** — Settings → Users and permissions → Add user
|
|
186
|
-
- **Handle `GSCApiError` status 429** — implement exponential backoff for rate-limited requests
|
|
187
|
-
|
|
188
|
-
---
|
|
147
|
+
### Service Account Authentication
|
|
189
148
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
**Where it runs**
|
|
193
|
-
|
|
194
|
-
- **Build-time**: Fetch GSC data for static site revalidation or build-time content ranking
|
|
195
|
-
- **Runtime**: Query analytics in serverless functions for real-time dashboard data
|
|
196
|
-
- **CI/CD**: Check indexing status and keyword positions in automated pipelines
|
|
149
|
+
```ts
|
|
150
|
+
import { createTokenManager } from '@power-seo/search-console';
|
|
197
151
|
|
|
198
|
-
|
|
152
|
+
const tokenManager = createTokenManager({
|
|
153
|
+
type: 'service-account',
|
|
154
|
+
clientEmail: process.env.GSC_SERVICE_ACCOUNT_EMAIL!,
|
|
155
|
+
privateKey: process.env.GSC_PRIVATE_KEY!,
|
|
156
|
+
scopes: ['https://www.googleapis.com/auth/webmasters.readonly'],
|
|
157
|
+
});
|
|
158
|
+
```
|
|
199
159
|
|
|
200
|
-
|
|
201
|
-
2. **Analysis**: Token manager handles auth; client sends typed requests to GSC API
|
|
202
|
-
3. **Output**: Typed `SearchAnalyticsRow[]`, `InspectionResult`, `SitemapListResponse`
|
|
203
|
-
4. **Action**: Feed into `@power-seo/analytics` for dashboards, or export as CSV/JSON reports
|
|
160
|
+
### Search Analytics Query
|
|
204
161
|
|
|
205
|
-
|
|
162
|
+
```ts
|
|
163
|
+
import { createGSCClient, querySearchAnalytics } from '@power-seo/search-console';
|
|
206
164
|
|
|
207
|
-
|
|
165
|
+
const client = createGSCClient({ siteUrl: 'https://example.com', tokenManager });
|
|
208
166
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
| Sitemap management | ❌ | ⚠️ | ❌ | ✅ |
|
|
167
|
+
const response = await querySearchAnalytics(client, {
|
|
168
|
+
startDate: '2026-01-01',
|
|
169
|
+
endDate: '2026-01-31',
|
|
170
|
+
dimensions: ['query', 'country'],
|
|
171
|
+
searchType: 'web',
|
|
172
|
+
rowLimit: 5000,
|
|
173
|
+
});
|
|
217
174
|
|
|
218
|
-
|
|
175
|
+
// response.rows → SearchAnalyticsRow[]
|
|
176
|
+
```
|
|
219
177
|
|
|
220
|
-
|
|
178
|
+
### Auto-Paginated Full Fetch
|
|
221
179
|
|
|
222
|
-
|
|
180
|
+
```ts
|
|
181
|
+
import { querySearchAnalyticsAll } from '@power-seo/search-console';
|
|
223
182
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
| [`@power-seo/content-analysis`](https://www.npmjs.com/package/@power-seo/content-analysis) | `npm i @power-seo/content-analysis` | Yoast-style SEO content scoring engine with React components |
|
|
231
|
-
| [`@power-seo/readability`](https://www.npmjs.com/package/@power-seo/readability) | `npm i @power-seo/readability` | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI |
|
|
232
|
-
| [`@power-seo/preview`](https://www.npmjs.com/package/@power-seo/preview) | `npm i @power-seo/preview` | SERP, Open Graph, and Twitter/X Card preview generators |
|
|
233
|
-
| [`@power-seo/sitemap`](https://www.npmjs.com/package/@power-seo/sitemap) | `npm i @power-seo/sitemap` | XML sitemap generation, streaming, index splitting, and validation |
|
|
234
|
-
| [`@power-seo/redirects`](https://www.npmjs.com/package/@power-seo/redirects) | `npm i @power-seo/redirects` | Redirect engine with Next.js, Remix, and Express adapters |
|
|
235
|
-
| [`@power-seo/links`](https://www.npmjs.com/package/@power-seo/links) | `npm i @power-seo/links` | Link graph analysis — orphan detection, suggestions, equity scoring |
|
|
236
|
-
| [`@power-seo/audit`](https://www.npmjs.com/package/@power-seo/audit) | `npm i @power-seo/audit` | Full SEO audit engine — meta, content, structure, performance rules |
|
|
237
|
-
| [`@power-seo/images`](https://www.npmjs.com/package/@power-seo/images) | `npm i @power-seo/images` | Image SEO — alt text, lazy loading, format analysis, image sitemaps |
|
|
238
|
-
| [`@power-seo/ai`](https://www.npmjs.com/package/@power-seo/ai) | `npm i @power-seo/ai` | LLM-agnostic AI prompt templates and parsers for SEO tasks |
|
|
239
|
-
| [`@power-seo/analytics`](https://www.npmjs.com/package/@power-seo/analytics) | `npm i @power-seo/analytics` | Merge GSC + audit data, trend analysis, ranking insights, dashboard |
|
|
240
|
-
| [`@power-seo/search-console`](https://www.npmjs.com/package/@power-seo/search-console) | `npm i @power-seo/search-console` | Google Search Console API — OAuth2, service account, URL inspection |
|
|
241
|
-
| [`@power-seo/integrations`](https://www.npmjs.com/package/@power-seo/integrations) | `npm i @power-seo/integrations` | Semrush and Ahrefs API clients with rate limiting and pagination |
|
|
242
|
-
| [`@power-seo/tracking`](https://www.npmjs.com/package/@power-seo/tracking) | `npm i @power-seo/tracking` | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |
|
|
183
|
+
// Fetches all rows automatically — handles the 25,000-row API limit
|
|
184
|
+
const allRows = await querySearchAnalyticsAll(client, {
|
|
185
|
+
startDate: '2026-01-01',
|
|
186
|
+
endDate: '2026-01-31',
|
|
187
|
+
dimensions: ['query'],
|
|
188
|
+
});
|
|
243
189
|
|
|
244
|
-
|
|
190
|
+
console.log(`Total rows: ${allRows.length}`);
|
|
191
|
+
```
|
|
245
192
|
|
|
246
|
-
|
|
247
|
-
| -------------------- | ---------------------- | --------------------------------------------------- |
|
|
248
|
-
| GSC search analytics | `googleapis` (verbose) | `@power-seo/search-console` — typed, auto-paginated |
|
|
249
|
-
| Analytics dashboards | Google Looker Studio | `@power-seo/analytics` — merge GSC + audit data |
|
|
250
|
-
| Sitemap submission | Manual GSC UI | `@power-seo/search-console` — `submitSitemap()` |
|
|
251
|
-
| SEO auditing | Third-party tools | `@power-seo/audit` — in-code, CI-friendly |
|
|
193
|
+
### URL Inspection
|
|
252
194
|
|
|
253
|
-
|
|
195
|
+
```ts
|
|
196
|
+
import { inspectUrl } from '@power-seo/search-console';
|
|
254
197
|
|
|
255
|
-
|
|
198
|
+
const result = await inspectUrl(client, 'https://example.com/blog/my-post');
|
|
256
199
|
|
|
257
|
-
|
|
200
|
+
console.log(result.verdict); // 'PASS' | 'FAIL' | 'NEUTRAL'
|
|
201
|
+
console.log(result.indexingState); // 'INDEXING_ALLOWED' | ...
|
|
202
|
+
console.log(result.lastCrawlTime); // ISO timestamp
|
|
203
|
+
console.log(result.mobileUsabilityResult.verdict); // 'PASS' | 'FAIL'
|
|
204
|
+
```
|
|
258
205
|
|
|
259
|
-
|
|
260
|
-
- **Aggregated dashboards**: Loop over multiple `siteUrl` values and merge analytics into a multi-site report
|
|
261
|
-
- **Scheduled data sync**: Run `querySearchAnalyticsAll` on a daily cron for all client properties
|
|
206
|
+
### Sitemap Management
|
|
262
207
|
|
|
263
|
-
|
|
208
|
+
```ts
|
|
209
|
+
import { listSitemaps, submitSitemap, deleteSitemap } from '@power-seo/search-console';
|
|
264
210
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
211
|
+
// List all submitted sitemaps
|
|
212
|
+
const sitemaps = await listSitemaps(client);
|
|
213
|
+
// sitemaps.sitemap → SitemapEntry[]
|
|
268
214
|
|
|
269
|
-
|
|
215
|
+
// Submit a new sitemap
|
|
216
|
+
await submitSitemap(client, 'https://example.com/sitemap.xml');
|
|
270
217
|
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
- Export results as **JSON** to Jira/Notion/Slack for content team review
|
|
218
|
+
// Delete an old sitemap
|
|
219
|
+
await deleteSitemap(client, 'https://example.com/old-sitemap.xml');
|
|
220
|
+
```
|
|
275
221
|
|
|
276
|
-
|
|
222
|
+
### CI/CD Keyword Position Check
|
|
277
223
|
|
|
278
|
-
|
|
224
|
+
```ts
|
|
225
|
+
import {
|
|
226
|
+
createTokenManager,
|
|
227
|
+
createGSCClient,
|
|
228
|
+
querySearchAnalyticsAll,
|
|
229
|
+
} from '@power-seo/search-console';
|
|
279
230
|
|
|
280
|
-
|
|
231
|
+
const tokenManager = createTokenManager({
|
|
232
|
+
type: 'service-account',
|
|
233
|
+
clientEmail: process.env.GSC_SERVICE_ACCOUNT_EMAIL!,
|
|
234
|
+
privateKey: process.env.GSC_PRIVATE_KEY!,
|
|
235
|
+
scopes: ['https://www.googleapis.com/auth/webmasters.readonly'],
|
|
236
|
+
});
|
|
281
237
|
|
|
282
|
-
|
|
283
|
-
- ✅ Fetch search analytics data with auto-pagination
|
|
284
|
-
- ✅ Inspect URL indexing status, mobile usability, and rich result status
|
|
285
|
-
- ✅ Submit, list, and delete sitemaps from verified GSC properties
|
|
238
|
+
const client = createGSCClient({ siteUrl: 'sc-domain:example.com', tokenManager });
|
|
286
239
|
|
|
287
|
-
|
|
240
|
+
const rows = await querySearchAnalyticsAll(client, {
|
|
241
|
+
startDate: '2026-01-24',
|
|
242
|
+
endDate: '2026-01-31',
|
|
243
|
+
dimensions: ['query', 'page'],
|
|
244
|
+
});
|
|
288
245
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
246
|
+
const dropped = rows.filter((r) => r.position > 20 && r.impressions > 100);
|
|
247
|
+
if (dropped.length > 0) {
|
|
248
|
+
console.error('Pages dropped below position 20:');
|
|
249
|
+
dropped.forEach((r) => console.error(' -', r.keys[1], `pos ${r.position.toFixed(1)}`));
|
|
250
|
+
process.exit(1);
|
|
251
|
+
}
|
|
252
|
+
```
|
|
292
253
|
|
|
293
254
|
---
|
|
294
255
|
|
|
@@ -304,7 +265,7 @@ All 17 packages are independently installable — use only what you need.
|
|
|
304
265
|
| `config.refreshToken` | `string` | OAuth2 refresh token (OAuth2 only) |
|
|
305
266
|
| `config.clientEmail` | `string` | Service account email (service account only) |
|
|
306
267
|
| `config.privateKey` | `string` | Service account private key PEM (service account only) |
|
|
307
|
-
| `config.scopes` | `string[]` | OAuth2 scopes
|
|
268
|
+
| `config.scopes` | `string[]` | OAuth2 scopes (service account only) |
|
|
308
269
|
|
|
309
270
|
Returns `TokenManager`: `{ getAccessToken(): Promise<TokenResult> }`.
|
|
310
271
|
|
|
@@ -313,7 +274,7 @@ Returns `TokenManager`: `{ getAccessToken(): Promise<TokenResult> }`.
|
|
|
313
274
|
| Parameter | Type | Description |
|
|
314
275
|
| --------------------- | -------------- | --------------------------------------------------------------------- |
|
|
315
276
|
| `config.siteUrl` | `string` | Verified GSC property URL (`sc-domain:` prefix for domain properties) |
|
|
316
|
-
| `config.tokenManager` | `TokenManager` | Token manager from `createTokenManager`
|
|
277
|
+
| `config.tokenManager` | `TokenManager` | Token manager from `createTokenManager()` |
|
|
317
278
|
|
|
318
279
|
Returns `GSCClient`.
|
|
319
280
|
|
|
@@ -330,7 +291,7 @@ Returns `GSCClient`.
|
|
|
330
291
|
|
|
331
292
|
### `querySearchAnalyticsAll(client, request)`
|
|
332
293
|
|
|
333
|
-
Same as `querySearchAnalytics` but `rowLimit` and `startRow` are managed automatically. Returns `Promise<SearchAnalyticsRow[]>`.
|
|
294
|
+
Same parameters as `querySearchAnalytics()` but `rowLimit` and `startRow` are managed automatically. Returns `Promise<SearchAnalyticsRow[]>`.
|
|
334
295
|
|
|
335
296
|
### `inspectUrl(client, url)` / `inspectUrlDirect(client, url)`
|
|
336
297
|
|
|
@@ -338,68 +299,106 @@ Returns `Promise<InspectionResult>`: `{ verdict, indexingState, lastCrawlTime, m
|
|
|
338
299
|
|
|
339
300
|
### `listSitemaps(client)` / `submitSitemap(client, url)` / `deleteSitemap(client, url)`
|
|
340
301
|
|
|
341
|
-
`listSitemaps` returns `Promise<SitemapListResponse>`. `submitSitemap` and `deleteSitemap` return `Promise<void>`.
|
|
302
|
+
`listSitemaps()` returns `Promise<SitemapListResponse>`. `submitSitemap()` and `deleteSitemap()` return `Promise<void>`.
|
|
342
303
|
|
|
343
304
|
### Types
|
|
344
305
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
```
|
|
306
|
+
| Type | Description |
|
|
307
|
+
| --------------------------- | ---------------------------------------------------------------------------- |
|
|
308
|
+
| `OAuthCredentials` | `{ clientId, clientSecret, refreshToken }` |
|
|
309
|
+
| `ServiceAccountCredentials` | `{ clientEmail, privateKey, scopes }` |
|
|
310
|
+
| `TokenResult` | `{ accessToken: string, expiresAt: number }` |
|
|
311
|
+
| `TokenManager` | `{ getAccessToken(): Promise<TokenResult> }` |
|
|
312
|
+
| `GSCClientConfig` | `{ siteUrl: string, tokenManager: TokenManager }` |
|
|
313
|
+
| `GSCClient` | Scoped API client instance |
|
|
314
|
+
| `SearchType` | `'web' \| 'image' \| 'video' \| 'news'` |
|
|
315
|
+
| `Dimension` | `'query' \| 'page' \| 'country' \| 'device' \| 'date' \| 'searchAppearance'` |
|
|
316
|
+
| `SearchAnalyticsRequest` | Request shape for `querySearchAnalytics()` |
|
|
317
|
+
| `SearchAnalyticsRow` | `{ keys: string[], clicks, impressions, ctr, position }` |
|
|
318
|
+
| `SearchAnalyticsResponse` | API response wrapper with `rows: SearchAnalyticsRow[]` |
|
|
319
|
+
| `InspectionResult` | URL inspection verdict, indexing state, and details |
|
|
320
|
+
| `SitemapEntry` | Single sitemap with status, lastDownloaded, errors |
|
|
321
|
+
| `SitemapListResponse` | `{ sitemap: SitemapEntry[] }` |
|
|
322
|
+
| `GSCApiError` | Error class with `status`, `code`, and `message` |
|
|
363
323
|
|
|
364
324
|
---
|
|
365
325
|
|
|
366
|
-
##
|
|
326
|
+
## Use Cases
|
|
367
327
|
|
|
368
|
-
-
|
|
369
|
-
-
|
|
370
|
-
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
328
|
+
- **Automated keyword ranking reports** — fetch all queries weekly and diff against the previous week
|
|
329
|
+
- **Indexing health monitoring** — `inspectUrl()` after deployments to verify new pages are indexed
|
|
330
|
+
- **Content gap analysis** — merge GSC data with `@power-seo/analytics` to find high-impression, low-click pages
|
|
331
|
+
- **Sitemap automation** — submit new sitemaps programmatically after content migrations
|
|
332
|
+
- **CI/CD SEO checks** — fail pipelines when key pages drop below a position threshold
|
|
333
|
+
- **Multi-site SaaS dashboards** — aggregate GSC data across multiple client properties with one `GSCClient` per site
|
|
334
|
+
- **Image and news search analytics** — query `image` and `news` search types separately
|
|
335
|
+
- **Country and device breakdowns** — segment click data by country or device for regional SEO analysis
|
|
374
336
|
|
|
375
|
-
|
|
337
|
+
---
|
|
376
338
|
|
|
377
|
-
|
|
378
|
-
- `npm publish --access public`
|
|
339
|
+
## Architecture Overview
|
|
379
340
|
|
|
380
|
-
|
|
341
|
+
- **Pure TypeScript** — no compiled binary, no native modules
|
|
342
|
+
- **Server-side only** — requires `crypto` for JWT signing; not edge or browser compatible
|
|
343
|
+
- **Zero runtime dependencies** — no googleapis package; uses native `fetch` and `crypto`
|
|
344
|
+
- **Auto-pagination** — `querySearchAnalyticsAll()` manages `rowOffset` and array merging transparently
|
|
345
|
+
- **Token caching** — access tokens are cached and reused until 5 minutes before expiry
|
|
346
|
+
- **Scoped clients** — each `GSCClient` is scoped to one verified GSC property via `siteUrl`
|
|
347
|
+
- **Typed errors** — `GSCApiError` carries HTTP status, error code, and message for reliable error handling
|
|
348
|
+
- **Dual ESM + CJS** — ships both formats via tsup for any bundler or `require()` usage
|
|
381
349
|
|
|
382
|
-
|
|
350
|
+
---
|
|
383
351
|
|
|
384
|
-
|
|
352
|
+
## Supply Chain Security
|
|
385
353
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
354
|
+
- No install scripts (`postinstall`, `preinstall`)
|
|
355
|
+
- No runtime network access outside of GSC API calls
|
|
356
|
+
- No `eval` or dynamic code execution
|
|
357
|
+
- npm provenance enabled — every release is signed via Sigstore through GitHub Actions
|
|
358
|
+
- CI-signed builds — all releases published via verified `github.com/CyberCraftBD/power-seo` workflow
|
|
359
|
+
- Safe for Node.js 18+ server environments
|
|
392
360
|
|
|
393
361
|
---
|
|
394
362
|
|
|
395
|
-
##
|
|
363
|
+
## The [@power-seo](https://www.npmjs.com/org/power-seo) Ecosystem
|
|
396
364
|
|
|
397
|
-
|
|
365
|
+
All 17 packages are independently installable — use only what you need.
|
|
366
|
+
|
|
367
|
+
| Package | Install | Description |
|
|
368
|
+
| ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------- |
|
|
369
|
+
| [`@power-seo/core`](https://www.npmjs.com/package/@power-seo/core) | `npm i @power-seo/core` | Framework-agnostic utilities, types, validators, and constants |
|
|
370
|
+
| [`@power-seo/react`](https://www.npmjs.com/package/@power-seo/react) | `npm i @power-seo/react` | React SEO components — meta, Open Graph, Twitter Card, breadcrumbs |
|
|
371
|
+
| [`@power-seo/meta`](https://www.npmjs.com/package/@power-seo/meta) | `npm i @power-seo/meta` | SSR meta helpers for Next.js App Router, Remix v2, and generic SSR |
|
|
372
|
+
| [`@power-seo/schema`](https://www.npmjs.com/package/@power-seo/schema) | `npm i @power-seo/schema` | Type-safe JSON-LD structured data — 23 builders + 21 React components |
|
|
373
|
+
| [`@power-seo/content-analysis`](https://www.npmjs.com/package/@power-seo/content-analysis) | `npm i @power-seo/content-analysis` | Yoast-style SEO content scoring engine with React components |
|
|
374
|
+
| [`@power-seo/readability`](https://www.npmjs.com/package/@power-seo/readability) | `npm i @power-seo/readability` | Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI |
|
|
375
|
+
| [`@power-seo/preview`](https://www.npmjs.com/package/@power-seo/preview) | `npm i @power-seo/preview` | SERP, Open Graph, and Twitter/X Card preview generators |
|
|
376
|
+
| [`@power-seo/sitemap`](https://www.npmjs.com/package/@power-seo/sitemap) | `npm i @power-seo/sitemap` | XML sitemap generation, streaming, index splitting, and validation |
|
|
377
|
+
| [`@power-seo/redirects`](https://www.npmjs.com/package/@power-seo/redirects) | `npm i @power-seo/redirects` | Redirect engine with Next.js, Remix, and Express adapters |
|
|
378
|
+
| [`@power-seo/links`](https://www.npmjs.com/package/@power-seo/links) | `npm i @power-seo/links` | Link graph analysis — orphan detection, suggestions, equity scoring |
|
|
379
|
+
| [`@power-seo/audit`](https://www.npmjs.com/package/@power-seo/audit) | `npm i @power-seo/audit` | Full SEO audit engine — meta, content, structure, performance rules |
|
|
380
|
+
| [`@power-seo/images`](https://www.npmjs.com/package/@power-seo/images) | `npm i @power-seo/images` | Image SEO — alt text, lazy loading, format analysis, image sitemaps |
|
|
381
|
+
| [`@power-seo/ai`](https://www.npmjs.com/package/@power-seo/ai) | `npm i @power-seo/ai` | LLM-agnostic AI prompt templates and parsers for SEO tasks |
|
|
382
|
+
| [`@power-seo/analytics`](https://www.npmjs.com/package/@power-seo/analytics) | `npm i @power-seo/analytics` | Merge GSC + audit data, trend analysis, ranking insights, dashboard |
|
|
383
|
+
| [`@power-seo/search-console`](https://www.npmjs.com/package/@power-seo/search-console) | `npm i @power-seo/search-console` | Google Search Console API — OAuth2, service account, URL inspection |
|
|
384
|
+
| [`@power-seo/integrations`](https://www.npmjs.com/package/@power-seo/integrations) | `npm i @power-seo/integrations` | Semrush and Ahrefs API clients with rate limiting and pagination |
|
|
385
|
+
| [`@power-seo/tracking`](https://www.npmjs.com/package/@power-seo/tracking) | `npm i @power-seo/tracking` | GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management |
|
|
398
386
|
|
|
399
387
|
---
|
|
400
388
|
|
|
401
389
|
## Keywords
|
|
402
390
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
391
|
+
seo · google-search-console · gsc · search-analytics · url-inspection · sitemap · oauth2 · service-account · typescript · nextjs · analytics · keyword-tracking · click-through-rate · impressions · ctr · position · auto-pagination · seo-automation · ci-cd · ranking-data
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
## About [CyberCraft Bangladesh](https://ccbd.dev)
|
|
396
|
+
|
|
397
|
+
**[CyberCraft Bangladesh](https://ccbd.dev)** 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.
|
|
398
|
+
|
|
399
|
+
[](https://ccbd.dev)
|
|
400
|
+
[](https://github.com/cybercraftbd)
|
|
401
|
+
[](https://www.npmjs.com/org/power-seo)
|
|
402
|
+
[](mailto:info@ccbd.dev)
|
|
403
|
+
|
|
404
|
+
© 2026 [CyberCraft Bangladesh](https://ccbd.dev) · Released under the [MIT License](../../LICENSE)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@power-seo/search-console",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.10",
|
|
4
4
|
"description": "Google Search Console API client with OAuth2/service account auth, rate limiting, and retry",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"dist"
|
|
19
19
|
],
|
|
20
20
|
"dependencies": {
|
|
21
|
-
"@power-seo/core": "1.0.
|
|
21
|
+
"@power-seo/core": "1.0.10"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
24
|
"rimraf": "^6.1.3",
|