gscdump 0.0.1 → 0.1.1
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 +151 -0
- package/dist/index.d.mts +227 -249
- package/dist/index.mjs +351 -400
- package/dist/query/index.d.mts +155 -0
- package/dist/query/index.mjs +1841 -0
- package/package.json +16 -7
package/dist/index.d.mts
CHANGED
|
@@ -3,34 +3,6 @@ import { $Fetch, FetchOptions } from "ofetch";
|
|
|
3
3
|
import { indexing_v3 } from "@googleapis/indexing/v3";
|
|
4
4
|
import { searchconsole_v1 } from "@googleapis/searchconsole/v1";
|
|
5
5
|
|
|
6
|
-
//#region src/analysis/types.d.ts
|
|
7
|
-
/**
|
|
8
|
-
* Shared types for pure analysis functions.
|
|
9
|
-
* These types describe the inputs and outputs of analysis functions
|
|
10
|
-
* that operate on data, independent of how it was fetched.
|
|
11
|
-
*/
|
|
12
|
-
type SortOrder = 'asc' | 'desc';
|
|
13
|
-
/** Base search metrics present on all data rows */
|
|
14
|
-
interface BaseMetrics {
|
|
15
|
-
clicks: number;
|
|
16
|
-
impressions: number;
|
|
17
|
-
ctr: number;
|
|
18
|
-
position: number;
|
|
19
|
-
}
|
|
20
|
-
/** Row with both query and page dimensions */
|
|
21
|
-
interface QueryPageRow extends BaseMetrics {
|
|
22
|
-
query: string;
|
|
23
|
-
page: string;
|
|
24
|
-
}
|
|
25
|
-
/** Date-keyed metrics for time series analysis */
|
|
26
|
-
interface DateMetrics extends BaseMetrics {
|
|
27
|
-
date: string;
|
|
28
|
-
}
|
|
29
|
-
/** Coerce nullable number to number, defaulting to 0 */
|
|
30
|
-
declare function num(value: number | null | undefined): number;
|
|
31
|
-
/** Create a generic sorter for any metric type */
|
|
32
|
-
declare function createSorter<T, M extends string>(getValue: (item: T, metric: M) => number, defaultMetric: M, defaultOrder?: SortOrder): (items: T[], sortBy?: M, sortOrder?: SortOrder) => T[];
|
|
33
|
-
//#endregion
|
|
34
6
|
//#region src/core/types.d.ts
|
|
35
7
|
type ApiSite = searchconsole_v1.Schema$WmxSite;
|
|
36
8
|
type ApiSitemap = searchconsole_v1.Schema$WmxSitemap;
|
|
@@ -208,99 +180,127 @@ interface FetchKeywordResult {
|
|
|
208
180
|
pages: PageRow[];
|
|
209
181
|
}
|
|
210
182
|
//#endregion
|
|
211
|
-
//#region src/analysis/
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
/** Maximum position (inclusive). Default: 20 */
|
|
217
|
-
maxPosition?: number;
|
|
218
|
-
/** Minimum impressions. Default: 100 */
|
|
183
|
+
//#region src/analysis/brand.d.ts
|
|
184
|
+
interface BrandSegmentationOptions {
|
|
185
|
+
/** Brand terms to match against keywords (case-insensitive) */
|
|
186
|
+
brandTerms: string[];
|
|
187
|
+
/** Minimum impressions for a keyword to be included. Default: 10 */
|
|
219
188
|
minImpressions?: number;
|
|
220
|
-
/** Maximum CTR (queries with low CTR have more potential). Default: 0.05 (5%) */
|
|
221
|
-
maxCtr?: number;
|
|
222
|
-
/** Sort metric. Default: potentialClicks */
|
|
223
|
-
sortBy?: StrikingDistanceSortMetric;
|
|
224
|
-
/** Sort order. Default: desc */
|
|
225
|
-
sortOrder?: SortOrder;
|
|
226
189
|
}
|
|
227
|
-
interface
|
|
228
|
-
|
|
229
|
-
|
|
190
|
+
interface BrandSummary {
|
|
191
|
+
brandClicks: number;
|
|
192
|
+
nonBrandClicks: number;
|
|
193
|
+
brandShare: number;
|
|
194
|
+
brandImpressions: number;
|
|
195
|
+
nonBrandImpressions: number;
|
|
196
|
+
}
|
|
197
|
+
interface BrandSegmentationResult {
|
|
198
|
+
brand: KeywordData[];
|
|
199
|
+
nonBrand: KeywordData[];
|
|
200
|
+
summary: BrandSummary;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Segments keywords into brand and non-brand based on provided brand terms.
|
|
204
|
+
* Simple string matching - keyword contains any brand term (case-insensitive).
|
|
205
|
+
*/
|
|
206
|
+
declare function analyzeBrandSegmentation(keywords: KeywordData[], options: BrandSegmentationOptions): BrandSegmentationResult;
|
|
207
|
+
//#endregion
|
|
208
|
+
//#region src/analysis/types.d.ts
|
|
209
|
+
/**
|
|
210
|
+
* Shared types for pure analysis functions.
|
|
211
|
+
* These types describe the inputs and outputs of analysis functions
|
|
212
|
+
* that operate on data, independent of how it was fetched.
|
|
213
|
+
*/
|
|
214
|
+
type SortOrder = 'asc' | 'desc';
|
|
215
|
+
/** Base search metrics present on all data rows */
|
|
216
|
+
interface BaseMetrics {
|
|
230
217
|
clicks: number;
|
|
231
218
|
impressions: number;
|
|
232
219
|
ctr: number;
|
|
233
220
|
position: number;
|
|
234
|
-
/** Estimated clicks if position improved to top 3 */
|
|
235
|
-
potentialClicks: number;
|
|
236
221
|
}
|
|
237
|
-
/**
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
declare function analyzeStrikingDistance(keywords: KeywordData[], options?: StrikingDistanceOptions): StrikingDistanceResult[];
|
|
242
|
-
//#endregion
|
|
243
|
-
//#region src/analysis/opportunity.d.ts
|
|
244
|
-
type OpportunitySortMetric = 'opportunityScore' | 'potentialClicks' | 'impressions' | 'position';
|
|
245
|
-
interface OpportunityWeights {
|
|
246
|
-
position?: number;
|
|
247
|
-
impressions?: number;
|
|
248
|
-
ctrGap?: number;
|
|
222
|
+
/** Row with both query and page dimensions */
|
|
223
|
+
interface QueryPageRow extends BaseMetrics {
|
|
224
|
+
query: string;
|
|
225
|
+
page: string;
|
|
249
226
|
}
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
/** Custom weights for score factors. Default: all 1 */
|
|
254
|
-
weights?: OpportunityWeights;
|
|
255
|
-
/** Sort metric. Default: opportunityScore */
|
|
256
|
-
sortBy?: OpportunitySortMetric;
|
|
227
|
+
/** Date-keyed metrics for time series analysis */
|
|
228
|
+
interface DateMetrics extends BaseMetrics {
|
|
229
|
+
date: string;
|
|
257
230
|
}
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
231
|
+
/** Coerce nullable number to number, defaulting to 0 */
|
|
232
|
+
declare function num(value: number | null | undefined): number;
|
|
233
|
+
/** Create a generic sorter for any metric type */
|
|
234
|
+
declare function createSorter<T, M extends string>(getValue: (item: T, metric: M) => number, defaultMetric: M, defaultOrder?: SortOrder): (items: T[], sortBy?: M, sortOrder?: SortOrder) => T[];
|
|
235
|
+
//#endregion
|
|
236
|
+
//#region src/analysis/cannibalization.d.ts
|
|
237
|
+
type CannibalizationSortMetric = 'clicks' | 'impressions' | 'positionSpread' | 'pageCount';
|
|
238
|
+
interface CannibalizationOptions {
|
|
239
|
+
/** Minimum impressions for a query to be considered. Default: 10 */
|
|
240
|
+
minImpressions?: number;
|
|
241
|
+
/** Maximum position spread to flag as cannibalization. Default: 10 */
|
|
242
|
+
maxPositionSpread?: number;
|
|
243
|
+
/** Minimum number of pages ranking for same query. Default: 2 */
|
|
244
|
+
minPages?: number;
|
|
245
|
+
/** Sort metric. Default: clicks */
|
|
246
|
+
sortBy?: CannibalizationSortMetric;
|
|
247
|
+
/** Sort order. Default: desc */
|
|
248
|
+
sortOrder?: SortOrder;
|
|
262
249
|
}
|
|
263
|
-
interface
|
|
264
|
-
|
|
265
|
-
page: string | null;
|
|
250
|
+
interface CannibalizationPage {
|
|
251
|
+
page: string;
|
|
266
252
|
clicks: number;
|
|
267
253
|
impressions: number;
|
|
268
254
|
ctr: number;
|
|
269
255
|
position: number;
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
256
|
+
}
|
|
257
|
+
interface CannibalizationResult {
|
|
258
|
+
query: string;
|
|
259
|
+
pages: CannibalizationPage[];
|
|
260
|
+
totalClicks: number;
|
|
261
|
+
totalImpressions: number;
|
|
262
|
+
positionSpread: number;
|
|
273
263
|
}
|
|
274
264
|
/**
|
|
275
|
-
*
|
|
276
|
-
*
|
|
265
|
+
* Detects keyword cannibalization - queries ranking for multiple pages.
|
|
266
|
+
* Returns queries where multiple pages compete for the same search term.
|
|
267
|
+
*
|
|
268
|
+
* @param rows Query+page data rows
|
|
269
|
+
* @param options Filtering and sorting options
|
|
277
270
|
*/
|
|
278
|
-
declare function
|
|
271
|
+
declare function analyzeCannibalization(rows: QueryPageRow[], options?: CannibalizationOptions): CannibalizationResult[];
|
|
279
272
|
//#endregion
|
|
280
|
-
//#region src/analysis/
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
273
|
+
//#region src/analysis/clustering.d.ts
|
|
274
|
+
type ClusterType = 'prefix' | 'intent' | 'both';
|
|
275
|
+
interface ClusteringOptions {
|
|
276
|
+
/** Minimum keywords for a cluster to be reported. Default: 2 */
|
|
277
|
+
minClusterSize?: number;
|
|
284
278
|
/** Minimum impressions for a keyword to be included. Default: 10 */
|
|
285
279
|
minImpressions?: number;
|
|
280
|
+
/** Clustering method. Default: 'both' */
|
|
281
|
+
clusterBy?: ClusterType;
|
|
286
282
|
}
|
|
287
|
-
interface
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
283
|
+
interface KeywordCluster {
|
|
284
|
+
clusterName: string;
|
|
285
|
+
clusterType: 'prefix' | 'intent';
|
|
286
|
+
keywords: KeywordData[];
|
|
287
|
+
totalClicks: number;
|
|
288
|
+
totalImpressions: number;
|
|
289
|
+
avgPosition: number;
|
|
290
|
+
keywordCount: number;
|
|
293
291
|
}
|
|
294
|
-
interface
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
summary: BrandSummary;
|
|
292
|
+
interface ClusteringResult {
|
|
293
|
+
clusters: KeywordCluster[];
|
|
294
|
+
unclustered: KeywordData[];
|
|
298
295
|
}
|
|
299
296
|
/**
|
|
300
|
-
*
|
|
301
|
-
* Simple
|
|
297
|
+
* Clusters keywords by intent prefix or common word prefix.
|
|
298
|
+
* Simple regex/prefix approach - no external NLP dependencies.
|
|
299
|
+
*
|
|
300
|
+
* @param keywords Array of keyword data
|
|
301
|
+
* @param options Clustering options
|
|
302
302
|
*/
|
|
303
|
-
declare function
|
|
303
|
+
declare function analyzeClustering(keywords: KeywordData[], options?: ClusteringOptions): ClusteringResult;
|
|
304
304
|
//#endregion
|
|
305
305
|
//#region src/analysis/concentration.d.ts
|
|
306
306
|
/**
|
|
@@ -439,69 +439,42 @@ interface MoversResult {
|
|
|
439
439
|
*/
|
|
440
440
|
declare function analyzeMovers(input: MoversInput, options?: MoversOptions): MoversResult;
|
|
441
441
|
//#endregion
|
|
442
|
-
//#region src/analysis/
|
|
443
|
-
type
|
|
444
|
-
interface
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
maxPositionSpread?: number;
|
|
449
|
-
/** Minimum number of pages ranking for same query. Default: 2 */
|
|
450
|
-
minPages?: number;
|
|
451
|
-
/** Sort metric. Default: clicks */
|
|
452
|
-
sortBy?: CannibalizationSortMetric;
|
|
453
|
-
/** Sort order. Default: desc */
|
|
454
|
-
sortOrder?: SortOrder;
|
|
455
|
-
}
|
|
456
|
-
interface CannibalizationPage {
|
|
457
|
-
page: string;
|
|
458
|
-
clicks: number;
|
|
459
|
-
impressions: number;
|
|
460
|
-
ctr: number;
|
|
461
|
-
position: number;
|
|
462
|
-
}
|
|
463
|
-
interface CannibalizationResult {
|
|
464
|
-
query: string;
|
|
465
|
-
pages: CannibalizationPage[];
|
|
466
|
-
totalClicks: number;
|
|
467
|
-
totalImpressions: number;
|
|
468
|
-
positionSpread: number;
|
|
442
|
+
//#region src/analysis/opportunity.d.ts
|
|
443
|
+
type OpportunitySortMetric = 'opportunityScore' | 'potentialClicks' | 'impressions' | 'position';
|
|
444
|
+
interface OpportunityWeights {
|
|
445
|
+
position?: number;
|
|
446
|
+
impressions?: number;
|
|
447
|
+
ctrGap?: number;
|
|
469
448
|
}
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
* Returns queries where multiple pages compete for the same search term.
|
|
473
|
-
*
|
|
474
|
-
* @param rows Query+page data rows
|
|
475
|
-
* @param options Filtering and sorting options
|
|
476
|
-
*/
|
|
477
|
-
declare function analyzeCannibalization(rows: QueryPageRow[], options?: CannibalizationOptions): CannibalizationResult[];
|
|
478
|
-
//#endregion
|
|
479
|
-
//#region src/analysis/zero-click.d.ts
|
|
480
|
-
interface ZeroClickOptions {
|
|
481
|
-
/** Minimum impressions. Default: 1000 */
|
|
449
|
+
interface OpportunityOptions {
|
|
450
|
+
/** Minimum impressions to consider. Default: 100 */
|
|
482
451
|
minImpressions?: number;
|
|
483
|
-
/**
|
|
484
|
-
|
|
485
|
-
/**
|
|
486
|
-
|
|
452
|
+
/** Custom weights for score factors. Default: all 1 */
|
|
453
|
+
weights?: OpportunityWeights;
|
|
454
|
+
/** Sort metric. Default: opportunityScore */
|
|
455
|
+
sortBy?: OpportunitySortMetric;
|
|
487
456
|
}
|
|
488
|
-
interface
|
|
489
|
-
|
|
490
|
-
|
|
457
|
+
interface OpportunityFactors {
|
|
458
|
+
positionScore: number;
|
|
459
|
+
impressionScore: number;
|
|
460
|
+
ctrGapScore: number;
|
|
461
|
+
}
|
|
462
|
+
interface OpportunityResult {
|
|
463
|
+
keyword: string;
|
|
464
|
+
page: string | null;
|
|
491
465
|
clicks: number;
|
|
492
466
|
impressions: number;
|
|
493
467
|
ctr: number;
|
|
494
468
|
position: number;
|
|
469
|
+
opportunityScore: number;
|
|
470
|
+
potentialClicks: number;
|
|
471
|
+
factors: OpportunityFactors;
|
|
495
472
|
}
|
|
496
473
|
/**
|
|
497
|
-
*
|
|
498
|
-
*
|
|
499
|
-
* often due to SERP features (Answer Boxes, Knowledge Panels, AI Overviews).
|
|
500
|
-
*
|
|
501
|
-
* @param rows Query+page data rows
|
|
502
|
-
* @param options Filtering options
|
|
474
|
+
* Scores keywords by optimization opportunity.
|
|
475
|
+
* Composite score combining position, impressions, and CTR gap factors.
|
|
503
476
|
*/
|
|
504
|
-
declare function
|
|
477
|
+
declare function analyzeOpportunity(keywords: KeywordData[], options?: OpportunityOptions): OpportunityResult[];
|
|
505
478
|
//#endregion
|
|
506
479
|
//#region src/analysis/seasonality.d.ts
|
|
507
480
|
type SeasonalityMetric = 'clicks' | 'impressions';
|
|
@@ -534,37 +507,64 @@ interface SeasonalityResult {
|
|
|
534
507
|
*/
|
|
535
508
|
declare function analyzeSeasonality(dates: DateMetrics[], options?: SeasonalityOptions): SeasonalityResult;
|
|
536
509
|
//#endregion
|
|
537
|
-
//#region src/analysis/
|
|
538
|
-
type
|
|
539
|
-
interface
|
|
540
|
-
/** Minimum
|
|
541
|
-
|
|
542
|
-
/**
|
|
510
|
+
//#region src/analysis/striking-distance.d.ts
|
|
511
|
+
type StrikingDistanceSortMetric = 'clicks' | 'impressions' | 'ctr' | 'position' | 'potentialClicks';
|
|
512
|
+
interface StrikingDistanceOptions {
|
|
513
|
+
/** Minimum position (inclusive). Default: 4 */
|
|
514
|
+
minPosition?: number;
|
|
515
|
+
/** Maximum position (inclusive). Default: 20 */
|
|
516
|
+
maxPosition?: number;
|
|
517
|
+
/** Minimum impressions. Default: 100 */
|
|
543
518
|
minImpressions?: number;
|
|
544
|
-
/**
|
|
545
|
-
|
|
519
|
+
/** Maximum CTR (queries with low CTR have more potential). Default: 0.05 (5%) */
|
|
520
|
+
maxCtr?: number;
|
|
521
|
+
/** Sort metric. Default: potentialClicks */
|
|
522
|
+
sortBy?: StrikingDistanceSortMetric;
|
|
523
|
+
/** Sort order. Default: desc */
|
|
524
|
+
sortOrder?: SortOrder;
|
|
546
525
|
}
|
|
547
|
-
interface
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
526
|
+
interface StrikingDistanceResult {
|
|
527
|
+
keyword: string;
|
|
528
|
+
page: string | null;
|
|
529
|
+
clicks: number;
|
|
530
|
+
impressions: number;
|
|
531
|
+
ctr: number;
|
|
532
|
+
position: number;
|
|
533
|
+
/** Estimated clicks if position improved to top 3 */
|
|
534
|
+
potentialClicks: number;
|
|
555
535
|
}
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
536
|
+
/**
|
|
537
|
+
* Finds striking distance keywords - high impressions, low CTR, position 4-20.
|
|
538
|
+
* These are "quick wins" that could gain significant traffic with small ranking improvements.
|
|
539
|
+
*/
|
|
540
|
+
declare function analyzeStrikingDistance(keywords: KeywordData[], options?: StrikingDistanceOptions): StrikingDistanceResult[];
|
|
541
|
+
//#endregion
|
|
542
|
+
//#region src/analysis/zero-click.d.ts
|
|
543
|
+
interface ZeroClickOptions {
|
|
544
|
+
/** Minimum impressions. Default: 1000 */
|
|
545
|
+
minImpressions?: number;
|
|
546
|
+
/** Maximum CTR to be considered "Zero Click". Default: 0.03 (3%) */
|
|
547
|
+
maxCtr?: number;
|
|
548
|
+
/** Only consider queries in top X positions. Default: 10 */
|
|
549
|
+
maxPosition?: number;
|
|
550
|
+
}
|
|
551
|
+
interface ZeroClickResult {
|
|
552
|
+
query: string;
|
|
553
|
+
page: string;
|
|
554
|
+
clicks: number;
|
|
555
|
+
impressions: number;
|
|
556
|
+
ctr: number;
|
|
557
|
+
position: number;
|
|
559
558
|
}
|
|
560
559
|
/**
|
|
561
|
-
*
|
|
562
|
-
*
|
|
560
|
+
* Identifies potential "Zero-Click" queries.
|
|
561
|
+
* These are high-volume queries where you rank well but get few clicks,
|
|
562
|
+
* often due to SERP features (Answer Boxes, Knowledge Panels, AI Overviews).
|
|
563
563
|
*
|
|
564
|
-
* @param
|
|
565
|
-
* @param options
|
|
564
|
+
* @param rows Query+page data rows
|
|
565
|
+
* @param options Filtering options
|
|
566
566
|
*/
|
|
567
|
-
declare function
|
|
567
|
+
declare function analyzeZeroClick(rows: QueryPageRow[], options?: ZeroClickOptions): ZeroClickResult[];
|
|
568
568
|
//#endregion
|
|
569
569
|
//#region src/core/client.d.ts
|
|
570
570
|
/**
|
|
@@ -682,34 +682,6 @@ declare function batchInspectUrls(client: GoogleSearchConsoleClient, siteUrl: st
|
|
|
682
682
|
onProgress?: (result: InspectUrlResult, index: number, total: number) => void;
|
|
683
683
|
}): Promise<InspectUrlResult[]>;
|
|
684
684
|
//#endregion
|
|
685
|
-
//#region src/api/sites.d.ts
|
|
686
|
-
/**
|
|
687
|
-
* Fetches all sites the authenticated user has access to in Google Search Console.
|
|
688
|
-
*/
|
|
689
|
-
declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[]>;
|
|
690
|
-
/**
|
|
691
|
-
* Fetches sitemaps for a site.
|
|
692
|
-
*/
|
|
693
|
-
declare function fetchSitemaps(client: GoogleSearchConsoleClient, siteUrl: string): Promise<ApiSitemap[]>;
|
|
694
|
-
/**
|
|
695
|
-
* Gets details for a specific sitemap.
|
|
696
|
-
*/
|
|
697
|
-
declare function fetchSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<ApiSitemap>;
|
|
698
|
-
/**
|
|
699
|
-
* Submits a sitemap to Google Search Console.
|
|
700
|
-
*/
|
|
701
|
-
declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
|
|
702
|
-
/**
|
|
703
|
-
* Deletes a sitemap from Google Search Console.
|
|
704
|
-
*/
|
|
705
|
-
declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
|
|
706
|
-
/**
|
|
707
|
-
* Fetches all verified sites with their sitemaps from Google Search Console.
|
|
708
|
-
*/
|
|
709
|
-
declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
|
|
710
|
-
sitemaps: RequiredNonNullable<ApiSitemap>[];
|
|
711
|
-
})[]>;
|
|
712
|
-
//#endregion
|
|
713
685
|
//#region src/api/search-analytics/analytics.d.ts
|
|
714
686
|
/**
|
|
715
687
|
* Fetches overall site analytics summary with period comparison and keyword data.
|
|
@@ -828,9 +800,9 @@ interface FetchKeywordOptions extends QueryOptions {
|
|
|
828
800
|
declare function fetchKeyword(client: GoogleSearchConsoleClient, siteUrl: string, keyword: string, options?: FetchKeywordOptions): Promise<FetchKeywordResult>;
|
|
829
801
|
//#endregion
|
|
830
802
|
//#region src/api/search-analytics/pages.d.ts
|
|
831
|
-
|
|
803
|
+
interface Page {
|
|
832
804
|
page: string;
|
|
833
|
-
}
|
|
805
|
+
}
|
|
834
806
|
/**
|
|
835
807
|
* Fetches all pages with their performance data using recursive pagination.
|
|
836
808
|
*/
|
|
@@ -899,7 +871,7 @@ type DimensionKey = 'query' | 'page' | 'date' | 'device' | 'country';
|
|
|
899
871
|
* Maps each dimension to its output field name.
|
|
900
872
|
* Note: 'query' maps to 'keyword' to match existing API conventions.
|
|
901
873
|
*/
|
|
902
|
-
|
|
874
|
+
interface DimensionFields {
|
|
903
875
|
query: {
|
|
904
876
|
keyword: string;
|
|
905
877
|
};
|
|
@@ -915,7 +887,7 @@ type DimensionFields = {
|
|
|
915
887
|
country: {
|
|
916
888
|
country: string;
|
|
917
889
|
};
|
|
918
|
-
}
|
|
890
|
+
}
|
|
919
891
|
/**
|
|
920
892
|
* Recursively extracts and merges fields for each dimension in a tuple.
|
|
921
893
|
* Used for type inference from dimensions array.
|
|
@@ -980,6 +952,34 @@ declare function queryRecursiveStream<const D extends readonly DimensionKey[]>(c
|
|
|
980
952
|
/** Collect all batches into single array (for testing / simple cases) */
|
|
981
953
|
declare function collectStream<T>(gen: AsyncGenerator<T[], void, undefined>): Promise<T[]>;
|
|
982
954
|
//#endregion
|
|
955
|
+
//#region src/api/sites.d.ts
|
|
956
|
+
/**
|
|
957
|
+
* Fetches all sites the authenticated user has access to in Google Search Console.
|
|
958
|
+
*/
|
|
959
|
+
declare function fetchSites(client: GoogleSearchConsoleClient): Promise<ApiSite[]>;
|
|
960
|
+
/**
|
|
961
|
+
* Fetches sitemaps for a site.
|
|
962
|
+
*/
|
|
963
|
+
declare function fetchSitemaps(client: GoogleSearchConsoleClient, siteUrl: string): Promise<ApiSitemap[]>;
|
|
964
|
+
/**
|
|
965
|
+
* Gets details for a specific sitemap.
|
|
966
|
+
*/
|
|
967
|
+
declare function fetchSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<ApiSitemap>;
|
|
968
|
+
/**
|
|
969
|
+
* Submits a sitemap to Google Search Console.
|
|
970
|
+
*/
|
|
971
|
+
declare function submitSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
|
|
972
|
+
/**
|
|
973
|
+
* Deletes a sitemap from Google Search Console.
|
|
974
|
+
*/
|
|
975
|
+
declare function deleteSitemap(client: GoogleSearchConsoleClient, siteUrl: string, feedpath: string): Promise<void>;
|
|
976
|
+
/**
|
|
977
|
+
* Fetches all verified sites with their sitemaps from Google Search Console.
|
|
978
|
+
*/
|
|
979
|
+
declare function fetchSitesWithSitemaps(client: GoogleSearchConsoleClient): Promise<(Site & {
|
|
980
|
+
sitemaps: RequiredNonNullable<ApiSitemap>[];
|
|
981
|
+
})[]>;
|
|
982
|
+
//#endregion
|
|
983
983
|
//#region src/core/errors.d.ts
|
|
984
984
|
/**
|
|
985
985
|
* GSC API error detection and formatting utilities.
|
|
@@ -1104,26 +1104,17 @@ interface BuilderState {
|
|
|
1104
1104
|
//#endregion
|
|
1105
1105
|
//#region src/query/builder.d.ts
|
|
1106
1106
|
interface GSCQueryBuilder<D extends Dimension[] = [], C = object> {
|
|
1107
|
-
select<T extends Dimension[]>(...dims: T)
|
|
1108
|
-
where<F extends Filter<any>>(filter: F)
|
|
1109
|
-
siteUrl(url: string)
|
|
1110
|
-
limit(n: number)
|
|
1111
|
-
execute(client: GoogleSearchConsoleClient)
|
|
1112
|
-
toBody()
|
|
1107
|
+
select: <T extends Dimension[]>(...dims: T) => GSCQueryBuilder<T, C>;
|
|
1108
|
+
where: <F extends Filter<any>>(filter: F) => GSCQueryBuilder<D, C & F['_constraints']>;
|
|
1109
|
+
siteUrl: (url: string) => GSCQueryBuilder<D, C>;
|
|
1110
|
+
limit: (n: number) => GSCQueryBuilder<D, C>;
|
|
1111
|
+
execute: (client: GoogleSearchConsoleClient) => Promise<GSCResult<D, C>>;
|
|
1112
|
+
toBody: () => SearchAnalyticsQuery;
|
|
1113
1113
|
/** Expose internal state for analysis functions to merge with */
|
|
1114
|
-
getState()
|
|
1114
|
+
getState: () => BuilderState;
|
|
1115
1115
|
}
|
|
1116
1116
|
declare const gsc: GSCQueryBuilder<[], object>;
|
|
1117
1117
|
//#endregion
|
|
1118
|
-
//#region src/query/resolver.d.ts
|
|
1119
|
-
/**
|
|
1120
|
-
* Extract date range from filters. Used by analysis functions to get the period.
|
|
1121
|
-
*/
|
|
1122
|
-
declare function extractDateRange(filters: Filter<any>[]): {
|
|
1123
|
-
startDate?: string;
|
|
1124
|
-
endDate?: string;
|
|
1125
|
-
};
|
|
1126
|
-
//#endregion
|
|
1127
1118
|
//#region src/query/columns.d.ts
|
|
1128
1119
|
declare const page: Column<"page">;
|
|
1129
1120
|
declare const query: Column<"query">;
|
|
@@ -1149,25 +1140,21 @@ declare function lte<D extends Dimension>(column: Column<D>, value: DimensionVal
|
|
|
1149
1140
|
declare function lt<D extends Dimension>(column: Column<D>, value: DimensionValueMap[D]): Filter<object>;
|
|
1150
1141
|
declare function between<D extends Dimension>(column: Column<D>, start: DimensionValueMap[D], end: DimensionValueMap[D]): Filter<object>;
|
|
1151
1142
|
//#endregion
|
|
1143
|
+
//#region src/query/resolver.d.ts
|
|
1144
|
+
/**
|
|
1145
|
+
* Extract date range from filters. Used by analysis functions to get the period.
|
|
1146
|
+
*/
|
|
1147
|
+
declare function extractDateRange(filters: Filter<any>[]): {
|
|
1148
|
+
startDate?: string;
|
|
1149
|
+
endDate?: string;
|
|
1150
|
+
};
|
|
1151
|
+
//#endregion
|
|
1152
|
+
//#region src/utils/dayjs.d.ts
|
|
1153
|
+
declare function dayjs(date?: _dayjs.ConfigType): Dayjs;
|
|
1154
|
+
declare function currentPstDate(): string;
|
|
1155
|
+
declare function dayjsPst(): Dayjs;
|
|
1156
|
+
//#endregion
|
|
1152
1157
|
//#region src/utils/format.d.ts
|
|
1153
|
-
interface ResolvedPeriodRange {
|
|
1154
|
-
period: {
|
|
1155
|
-
startTimestamp: number;
|
|
1156
|
-
start: Date;
|
|
1157
|
-
startDateTime: string;
|
|
1158
|
-
startDate: string;
|
|
1159
|
-
end: Date;
|
|
1160
|
-
endDate: string;
|
|
1161
|
-
endTimestamp: number;
|
|
1162
|
-
endDateTime: string;
|
|
1163
|
-
};
|
|
1164
|
-
prevPeriod: {
|
|
1165
|
-
start: Date;
|
|
1166
|
-
startDate: string;
|
|
1167
|
-
end: Date;
|
|
1168
|
-
endDate: string;
|
|
1169
|
-
};
|
|
1170
|
-
}
|
|
1171
1158
|
/**
|
|
1172
1159
|
* Formats a date for GSC API queries (YYYY-MM-DD format).
|
|
1173
1160
|
* @param d - Date object, date string, or null/undefined
|
|
@@ -1182,14 +1169,5 @@ declare function formatDateGsc(d?: Date | string | null): string | null | undefi
|
|
|
1182
1169
|
* @returns Percentage difference (positive = increase, negative = decrease), or 0 if either value is falsy
|
|
1183
1170
|
*/
|
|
1184
1171
|
declare function percentDifference(a?: number | null, b?: number | null): number;
|
|
1185
|
-
/**
|
|
1186
|
-
* Resolves a period string or object into start/end dates for current and previous periods.
|
|
1187
|
-
* @param periodRange - Period string (e.g., '30d', '3mo', 'all') or Period object with start/end dates
|
|
1188
|
-
* @returns Resolved period ranges with timestamps and formatted dates for both current and previous periods
|
|
1189
|
-
*/
|
|
1190
|
-
declare function userPeriodRange(periodRange?: string | Period): ResolvedPeriodRange;
|
|
1191
|
-
//#endregion
|
|
1192
|
-
//#region src/utils/dayjs.d.ts
|
|
1193
|
-
declare function dayjs(date?: _dayjs.ConfigType): Dayjs;
|
|
1194
1172
|
//#endregion
|
|
1195
|
-
export { AggregationType, AnalyticsData, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BaseMetrics, BrandSegmentationOptions, BrandSegmentationResult, BrandSummary, type BuilderState, CannibalizationOptions, CannibalizationPage, CannibalizationResult, CannibalizationSortMetric, ClusterType, ClusteringOptions, ClusteringResult, type Column, ComparisonResult, ConcentrationInput, ConcentrationItem, ConcentrationOptions, ConcentrationResult, ConcentrationRiskLevel, Country, type Country as CountryType, CountryData, DataRow, DataState, DataType, DateData, DateMetrics, DateRow, DatesComparisonResult, DecayInput, DecayOptions, DecayResult, DecaySortMetric, Device, type Device as DeviceType, DeviceData, type Dimension, DimensionFilter, DimensionFilterGroup, DimensionKey, type DimensionValueMap, ErrorInfo, FetchKeywordOptions, FetchKeywordResult, FetchPageOptions, FetchPageResult, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, KeywordCluster, KeywordData, KeywordRow, MobileUsabilityResult, MonthlyData, MoverData, MoversInput, MoversOptions, MoversResult, MoversSortMetric, OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, Page, PageData, PageRow, Period, PublishUrlNotificationResponse, QueryOptions, QueryPageRow, QueryResultRow, RequiredNonNullable, ResolvedAnalyticsRange,
|
|
1173
|
+
export { AggregationType, AnalyticsData, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, BaseMetrics, BrandSegmentationOptions, BrandSegmentationResult, BrandSummary, type BuilderState, CannibalizationOptions, CannibalizationPage, CannibalizationResult, CannibalizationSortMetric, ClusterType, ClusteringOptions, ClusteringResult, type Column, ComparisonResult, ConcentrationInput, ConcentrationItem, ConcentrationOptions, ConcentrationResult, ConcentrationRiskLevel, Country, type Country as CountryType, CountryData, DataRow, DataState, DataType, DateData, DateMetrics, DateRow, DatesComparisonResult, DecayInput, DecayOptions, DecayResult, DecaySortMetric, Device, type Device as DeviceType, DeviceData, type Dimension, DimensionFilter, DimensionFilterGroup, DimensionKey, type DimensionValueMap, ErrorInfo, FetchKeywordOptions, FetchKeywordResult, FetchPageOptions, FetchPageResult, type Filter, type GSCQueryBuilder, type GSCResult, type GSCRow, GSC_QUOTAS, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, IndexStatusResult, IndexingMetadata, IndexingNotificationType, IndexingResult, InspectUrlIndexResponse, InspectUrlResult, KeywordCluster, KeywordData, KeywordRow, MobileUsabilityResult, MonthlyData, MoverData, MoversInput, MoversOptions, MoversResult, MoversSortMetric, OpportunityFactors, OpportunityOptions, OpportunityResult, OpportunitySortMetric, OpportunityWeights, Page, PageData, PageRow, Period, PublishUrlNotificationResponse, QueryOptions, QueryPageRow, QueryResultRow, RequiredNonNullable, ResolvedAnalyticsRange, RichResultsResult, SearchAnalyticsQuery, SearchAnalyticsResponse, SearchAppearanceData, SeasonalityMetric, SeasonalityOptions, SeasonalityResult, Site, SiteAnalytics, SortOrder, StreamRow, StrikingDistanceOptions, StrikingDistanceResult, StrikingDistanceSortMetric, UrlInspectionResult, UrlNotificationMetadata, YoYComparisonOptions, YoYComparisonResult, YoYMetrics, ZeroClickOptions, ZeroClickResult, analyzeBrandSegmentation, analyzeCannibalization, analyzeClustering, analyzeConcentration, analyzeDecay, analyzeError, analyzeKeywordConcentration, analyzeMovers, analyzeOpportunity, analyzePageConcentration, analyzeSeasonality, analyzeStrikingDistance, analyzeZeroClick, and, batchInspectUrls, batchRequestIndexing, between, collectStream, contains, _default as countries, country, createAuth, createFetch, createQueryBody, createSorter, currentPstDate, date, dayjs, dayjsPst, deleteSitemap, device, eq, extractDateRange, fetchAnalyticsWithComparison, fetchCountries, fetchCountriesWithComparison, fetchDates, fetchDatesWithComparison, fetchDevices, fetchDevicesWithComparison, fetchKeyword, fetchKeywords, fetchKeywordsWithComparison, fetchPage, fetchPages, fetchPagesWithComparison, fetchSearchAppearance, fetchSearchAppearanceWithComparison, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, fetchYoYComparison, formatDateGsc, formatErrorForCli, getErrorCode, getErrorMessage, getIndexingMetadata, getRetryAfter, googleSearchConsole, gsc, gt, gte, inArray, inspectUrl, isAuthError, isQuotaError, isRateLimitError, like, lt, lte, ne, not, notRegex, num, or, page, percentDifference, query, queryRecursive, queryRecursiveStream, regex, requestIndexing, searchAppearance, submitSitemap, withDataType, withFinalData, withFreshData, withPropertyAggregation, withSearchAppearance };
|