@power-seo/search-console 1.0.11 → 1.0.12
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 +82 -58
- package/package.json +9 -3
package/README.md
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
# @power-seo/search-console
|
|
2
2
|
|
|
3
|
-
|
|
4
4
|
|
|
5
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.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/@power-seo/search-console)
|
|
8
8
|
[](https://www.npmjs.com/package/@power-seo/search-console)
|
|
9
9
|
[](https://socket.dev/npm/package/@power-seo/search-console)
|
|
10
|
-
[](https://github.com/CyberCraftBD/power-seo/actions)
|
|
11
10
|
[](https://opensource.org/licenses/MIT)
|
|
12
11
|
[](https://www.typescriptlang.org/)
|
|
13
12
|
[](https://bundlephobia.com/package/@power-seo/search-console)
|
|
@@ -30,7 +29,13 @@ Typed Google Search Console API client for TypeScript — OAuth2 and service acc
|
|
|
30
29
|
| Sitemap management | ❌ Manual GSC UI operations | ✅ `submitSitemap()`, `listSitemaps()`, `deleteSitemap()` |
|
|
31
30
|
| Framework support | ❌ Tied to googleapis setup | ✅ Works in Next.js, Remix, Node.js, CI/CD |
|
|
32
31
|
|
|
33
|
-
|
|
33
|
+
|
|
34
|
+
<p align="left">
|
|
35
|
+
<a href="https://www.buymeacoffee.com/ccbd.dev" target="_blank">
|
|
36
|
+
<img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=ccbd.dev&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff" />
|
|
37
|
+
</a>
|
|
38
|
+
</p>
|
|
34
39
|
|
|
35
40
|
---
|
|
36
41
|
|
|
@@ -50,7 +55,7 @@ Typed Google Search Console API client for TypeScript — OAuth2 and service acc
|
|
|
50
55
|
- **Typed error handling** — `GSCApiError` class with `status`, `code`, and `message`
|
|
51
56
|
- **Full TypeScript support** — complete type definitions for all request and response shapes
|
|
52
57
|
|
|
53
|
-
|
|
54
59
|
|
|
55
60
|
---
|
|
56
61
|
|
|
@@ -67,7 +72,7 @@ Typed Google Search Console API client for TypeScript — OAuth2 and service acc
|
|
|
67
72
|
| Zero runtime dependencies | ❌ | ❌ | ✅ | ✅ |
|
|
68
73
|
| TypeScript-first | ❌ | ⚠️ | ❌ | ✅ |
|
|
69
74
|
|
|
70
|
-
|
|
71
76
|
|
|
72
77
|
---
|
|
73
78
|
|
|
@@ -97,17 +102,20 @@ import {
|
|
|
97
102
|
} from '@power-seo/search-console';
|
|
98
103
|
|
|
99
104
|
// 1. Create a token manager (OAuth2)
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
import { exchangeRefreshToken } from '@power-seo/search-console';
|
|
106
|
+
|
|
107
|
+
const tokenManager = createTokenManager(() =>
|
|
108
|
+
exchangeRefreshToken({
|
|
109
|
+
clientId: process.env.GSC_CLIENT_ID!,
|
|
110
|
+
clientSecret: process.env.GSC_CLIENT_SECRET!,
|
|
111
|
+
refreshToken: process.env.GSC_REFRESH_TOKEN!,
|
|
112
|
+
}),
|
|
113
|
+
);
|
|
106
114
|
|
|
107
115
|
// 2. Create a client scoped to your site
|
|
108
116
|
const client = createGSCClient({
|
|
109
117
|
siteUrl: 'https://example.com',
|
|
110
|
-
tokenManager,
|
|
118
|
+
auth: tokenManager,
|
|
111
119
|
});
|
|
112
120
|
|
|
113
121
|
// 3. Fetch all search analytics data (auto-paginated)
|
|
@@ -123,7 +131,7 @@ rows.forEach(({ keys, clicks, impressions, ctr, position }) => {
|
|
|
123
131
|
});
|
|
124
132
|
```
|
|
125
133
|
|
|
126
|
-
|
|
127
135
|
|
|
128
136
|
---
|
|
129
137
|
|
|
@@ -132,29 +140,40 @@ rows.forEach(({ keys, clicks, impressions, ctr, position }) => {
|
|
|
132
140
|
### OAuth2 Authentication
|
|
133
141
|
|
|
134
142
|
```ts
|
|
135
|
-
import { createTokenManager } from '@power-seo/search-console';
|
|
143
|
+
import { createTokenManager, exchangeRefreshToken } from '@power-seo/search-console';
|
|
136
144
|
|
|
137
|
-
const tokenManager = createTokenManager(
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
})
|
|
145
|
+
const tokenManager = createTokenManager(() =>
|
|
146
|
+
exchangeRefreshToken({
|
|
147
|
+
clientId: process.env.GSC_CLIENT_ID!,
|
|
148
|
+
clientSecret: process.env.GSC_CLIENT_SECRET!,
|
|
149
|
+
refreshToken: process.env.GSC_REFRESH_TOKEN!,
|
|
150
|
+
}),
|
|
151
|
+
);
|
|
143
152
|
|
|
144
|
-
const
|
|
153
|
+
const accessToken = await tokenManager.getToken();
|
|
145
154
|
```
|
|
146
155
|
|
|
147
156
|
### Service Account Authentication
|
|
148
157
|
|
|
149
158
|
```ts
|
|
150
|
-
import { createTokenManager } from '@power-seo/search-console';
|
|
159
|
+
import { createTokenManager, getServiceAccountToken } from '@power-seo/search-console';
|
|
160
|
+
import { subtle } from 'node:crypto';
|
|
151
161
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
162
|
+
// Parse service account JSON and create signing function
|
|
163
|
+
const serviceAccount = JSON.parse(process.env.GSC_SERVICE_ACCOUNT_JSON!);
|
|
164
|
+
|
|
165
|
+
async function signJwt(payload: Record<string, unknown>): Promise<string> {
|
|
166
|
+
// Implement JWT signing using node:crypto or your preferred library
|
|
167
|
+
// Returns signed JWT assertion string
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
const tokenManager = createTokenManager(() =>
|
|
171
|
+
getServiceAccountToken({
|
|
172
|
+
clientEmail: serviceAccount.client_email,
|
|
173
|
+
privateKeyId: serviceAccount.private_key_id,
|
|
174
|
+
signJwt,
|
|
175
|
+
}),
|
|
176
|
+
);
|
|
158
177
|
```
|
|
159
178
|
|
|
160
179
|
### Search Analytics Query
|
|
@@ -226,14 +245,26 @@ import {
|
|
|
226
245
|
createTokenManager,
|
|
227
246
|
createGSCClient,
|
|
228
247
|
querySearchAnalyticsAll,
|
|
248
|
+
getServiceAccountToken,
|
|
229
249
|
} from '@power-seo/search-console';
|
|
250
|
+
import { subtle } from 'node:crypto';
|
|
230
251
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
252
|
+
// Parse service account JSON from environment
|
|
253
|
+
const serviceAccount = JSON.parse(process.env.GSC_SERVICE_ACCOUNT_JSON!);
|
|
254
|
+
|
|
255
|
+
async function signJwt(payload: Record<string, unknown>): Promise<string> {
|
|
256
|
+
// Sign JWT assertion using node:crypto
|
|
257
|
+
// Implementation depends on your preferred JWT signing library
|
|
258
|
+
throw new Error('Implement JWT signing');
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
const tokenManager = createTokenManager(() =>
|
|
262
|
+
getServiceAccountToken({
|
|
263
|
+
clientEmail: serviceAccount.client_email,
|
|
264
|
+
privateKeyId: serviceAccount.private_key_id,
|
|
265
|
+
signJwt,
|
|
266
|
+
}),
|
|
267
|
+
);
|
|
237
268
|
|
|
238
269
|
const client = createGSCClient({ siteUrl: 'sc-domain:example.com', tokenManager });
|
|
239
270
|
|
|
@@ -255,26 +286,23 @@ if (dropped.length > 0) {
|
|
|
255
286
|
|
|
256
287
|
## API Reference
|
|
257
288
|
|
|
258
|
-
### `createTokenManager(
|
|
289
|
+
### `createTokenManager(fetchToken)`
|
|
259
290
|
|
|
260
|
-
| Parameter
|
|
261
|
-
|
|
|
262
|
-
| `
|
|
263
|
-
| `config.clientId` | `string` | Google OAuth2 client ID (OAuth2 only) |
|
|
264
|
-
| `config.clientSecret` | `string` | Google OAuth2 client secret (OAuth2 only) |
|
|
265
|
-
| `config.refreshToken` | `string` | OAuth2 refresh token (OAuth2 only) |
|
|
266
|
-
| `config.clientEmail` | `string` | Service account email (service account only) |
|
|
267
|
-
| `config.privateKey` | `string` | Service account private key PEM (service account only) |
|
|
268
|
-
| `config.scopes` | `string[]` | OAuth2 scopes (service account only) |
|
|
291
|
+
| Parameter | Type | Description |
|
|
292
|
+
| ------------ | ---------------------------- | ---------------------------------- |
|
|
293
|
+
| `fetchToken` | `() => Promise<TokenResult>` | Function that returns token result |
|
|
269
294
|
|
|
270
|
-
Returns `TokenManager`: `{
|
|
295
|
+
Returns `TokenManager`: `{ getToken(): Promise<string>; invalidate(): void }`. Token caching and refresh is handled automatically.
|
|
271
296
|
|
|
272
297
|
### `createGSCClient(config)`
|
|
273
298
|
|
|
274
|
-
| Parameter
|
|
275
|
-
|
|
|
276
|
-
| `config.siteUrl`
|
|
277
|
-
| `config.
|
|
299
|
+
| Parameter | Type | Description |
|
|
300
|
+
| --------------------------- | -------------- | --------------------------------------------------------------------- |
|
|
301
|
+
| `config.siteUrl` | `string` | Verified GSC property URL (`sc-domain:` prefix for domain properties) |
|
|
302
|
+
| `config.auth` | `TokenManager` | Token manager from `createTokenManager()` |
|
|
303
|
+
| `config.rateLimitPerMinute` | `number` | Rate limit (default: 1200) |
|
|
304
|
+
| `config.maxRetries` | `number` | Max retries for failed requests (default: 3) |
|
|
305
|
+
| `config.baseUrl` | `string` | Base URL for GSC API (default: official Google endpoint) |
|
|
278
306
|
|
|
279
307
|
Returns `GSCClient`.
|
|
280
308
|
|
|
@@ -285,9 +313,12 @@ Returns `GSCClient`.
|
|
|
285
313
|
| `request.startDate` | `string` | required | `YYYY-MM-DD` |
|
|
286
314
|
| `request.endDate` | `string` | required | `YYYY-MM-DD` |
|
|
287
315
|
| `request.dimensions` | `Dimension[]` | `[]` | `'query'`, `'page'`, `'country'`, `'device'`, `'date'`, `'searchAppearance'` |
|
|
288
|
-
| `request.searchType` | `SearchType` | `'web'` | `'web'`, `'image'`, `'video'`, `'news'`
|
|
316
|
+
| `request.searchType` | `SearchType` | `'web'` | `'web'`, `'image'`, `'video'`, `'news'`, `'discover'`, `'googleNews'` |
|
|
289
317
|
| `request.rowLimit` | `number` | `1000` | Rows per request (max 25,000) |
|
|
318
|
+
| `request.startRow` | `number` | `0` | Row offset for pagination |
|
|
290
319
|
| `request.dimensionFilterGroups` | `object[]` | `[]` | Filter groups to narrow results |
|
|
320
|
+
| `request.aggregationType` | `string` | `'auto'` | Aggregation method: `'auto'`, `'byPage'`, `'byProperty'` |
|
|
321
|
+
| `request.dataState` | `string` | `'all'` | Include all or final data: `'all'`, `'final'` |
|
|
291
322
|
|
|
292
323
|
### `querySearchAnalyticsAll(client, request)`
|
|
293
324
|
|
|
@@ -308,7 +339,7 @@ Returns `Promise<InspectionResult>`: `{ verdict, indexingState, lastCrawlTime, m
|
|
|
308
339
|
| `OAuthCredentials` | `{ clientId, clientSecret, refreshToken }` |
|
|
309
340
|
| `ServiceAccountCredentials` | `{ clientEmail, privateKey, scopes }` |
|
|
310
341
|
| `TokenResult` | `{ accessToken: string, expiresAt: number }` |
|
|
311
|
-
| `TokenManager` | `{
|
|
342
|
+
| `TokenManager` | `{ getToken(): Promise<string>, invalidate(): void }` |
|
|
312
343
|
| `GSCClientConfig` | `{ siteUrl: string, tokenManager: TokenManager }` |
|
|
313
344
|
| `GSCClient` | Scoped API client instance |
|
|
314
345
|
| `SearchType` | `'web' \| 'image' \| 'video' \| 'news'` |
|
|
@@ -354,7 +385,6 @@ Returns `Promise<InspectionResult>`: `{ verdict, indexingState, lastCrawlTime, m
|
|
|
354
385
|
- No install scripts (`postinstall`, `preinstall`)
|
|
355
386
|
- No runtime network access outside of GSC API calls
|
|
356
387
|
- No `eval` or dynamic code execution
|
|
357
|
-
- npm provenance enabled — every release is signed via Sigstore through GitHub Actions
|
|
358
388
|
- CI-signed builds — all releases published via verified `github.com/CyberCraftBD/power-seo` workflow
|
|
359
389
|
- Safe for Node.js 18+ server environments
|
|
360
390
|
|
|
@@ -386,12 +416,6 @@ All 17 packages are independently installable — use only what you need.
|
|
|
386
416
|
|
|
387
417
|
---
|
|
388
418
|
|
|
389
|
-
## Keywords
|
|
390
|
-
|
|
391
|
-
seo · google search console · gsc · search analytics · url inspection · sitemap submission · oauth2 · service account · keyword tracking · click through rate · impressions · position tracking · auto pagination · seo automation · ci cd · ranking data · search performance · nextjs · typescript · api
|
|
392
|
-
|
|
393
|
-
---
|
|
394
|
-
|
|
395
419
|
## About [CyberCraft Bangladesh](https://ccbd.dev)
|
|
396
420
|
|
|
397
421
|
**[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.
|
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.12",
|
|
4
4
|
"description": "Google Search Console API client with OAuth2/service account auth, rate limiting, and retry",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"seo",
|
|
@@ -37,10 +37,16 @@
|
|
|
37
37
|
"module": "./dist/index.js",
|
|
38
38
|
"types": "./dist/index.d.ts",
|
|
39
39
|
"files": [
|
|
40
|
-
"dist"
|
|
40
|
+
"dist",
|
|
41
|
+
"LICENSE"
|
|
41
42
|
],
|
|
43
|
+
"engines": {
|
|
44
|
+
"node": ">=18.0.0",
|
|
45
|
+
"npm": ">=9.0.0",
|
|
46
|
+
"pnpm": ">=8.0.0"
|
|
47
|
+
},
|
|
42
48
|
"dependencies": {
|
|
43
|
-
"@power-seo/core": "1.0.
|
|
49
|
+
"@power-seo/core": "1.0.12"
|
|
44
50
|
},
|
|
45
51
|
"devDependencies": {
|
|
46
52
|
"rimraf": "^6.1.3",
|