@pagebridge/core 0.0.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/.turbo/turbo-build.log +2 -0
- package/LICENSE +21 -0
- package/README.md +241 -0
- package/dist/decay-detector.d.ts +37 -0
- package/dist/decay-detector.d.ts.map +1 -0
- package/dist/decay-detector.js +175 -0
- package/dist/gsc-client.d.ts +40 -0
- package/dist/gsc-client.d.ts.map +1 -0
- package/dist/gsc-client.js +76 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/sync-engine.d.ts +41 -0
- package/dist/sync-engine.d.ts.map +1 -0
- package/dist/sync-engine.js +333 -0
- package/dist/task-generator.d.ts +26 -0
- package/dist/task-generator.d.ts.map +1 -0
- package/dist/task-generator.js +101 -0
- package/dist/url-matcher.d.ts +49 -0
- package/dist/url-matcher.d.ts.map +1 -0
- package/dist/url-matcher.js +227 -0
- package/eslint.config.js +3 -0
- package/package.json +33 -0
- package/src/decay-detector.ts +254 -0
- package/src/gsc-client.ts +126 -0
- package/src/index.ts +31 -0
- package/src/sync-engine.ts +485 -0
- package/src/task-generator.ts +160 -0
- package/src/url-matcher.ts +307 -0
- package/tsconfig.json +9 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Soma Somorjai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# @pagebridge/core
|
|
2
|
+
|
|
3
|
+
Core business logic for syncing Google Search Console data to Sanity CMS, detecting content decay patterns, and generating refresh tasks.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pnpm add @pagebridge/core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
This package provides the main building blocks for content performance tracking:
|
|
14
|
+
|
|
15
|
+
- **GSCClient** - Fetches search analytics from Google Search Console API
|
|
16
|
+
- **SyncEngine** - Orchestrates data sync between GSC, PostgreSQL, and Sanity
|
|
17
|
+
- **DecayDetector** - Analyzes metrics to identify content decay patterns
|
|
18
|
+
- **URLMatcher** - Maps GSC URLs to Sanity documents by slug
|
|
19
|
+
- **TaskGenerator** - Creates refresh tasks in Sanity for decaying content
|
|
20
|
+
|
|
21
|
+
## Usage
|
|
22
|
+
|
|
23
|
+
### GSCClient
|
|
24
|
+
|
|
25
|
+
Authenticates with Google and fetches search analytics data.
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { GSCClient } from '@pagebridge/core';
|
|
29
|
+
|
|
30
|
+
const client = new GSCClient({
|
|
31
|
+
serviceAccountJson: process.env.GOOGLE_SERVICE_ACCOUNT,
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
// List available sites
|
|
35
|
+
const sites = await client.listSites();
|
|
36
|
+
|
|
37
|
+
// Fetch search analytics
|
|
38
|
+
const data = await client.fetchSearchAnalytics({
|
|
39
|
+
siteUrl: 'sc-domain:example.com',
|
|
40
|
+
startDate: '2024-01-01',
|
|
41
|
+
endDate: '2024-01-31',
|
|
42
|
+
dimensions: ['page', 'query'],
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
// Check URL index status
|
|
46
|
+
const status = await client.inspectUrl({
|
|
47
|
+
siteUrl: 'sc-domain:example.com',
|
|
48
|
+
inspectionUrl: 'https://example.com/blog/post',
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### SyncEngine
|
|
53
|
+
|
|
54
|
+
Coordinates the full sync workflow: fetching data, storing metrics, and writing Sanity snapshots.
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { SyncEngine } from '@pagebridge/core';
|
|
58
|
+
import { createDb } from '@pagebridge/db';
|
|
59
|
+
import { createClient } from '@sanity/client';
|
|
60
|
+
|
|
61
|
+
const db = createDb(process.env.DATABASE_URL);
|
|
62
|
+
const sanityClient = createClient({
|
|
63
|
+
projectId: 'your-project',
|
|
64
|
+
dataset: 'production',
|
|
65
|
+
token: process.env.SANITY_TOKEN,
|
|
66
|
+
apiVersion: '2024-01-01',
|
|
67
|
+
useCdn: false,
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
const engine = new SyncEngine({
|
|
71
|
+
gscClient,
|
|
72
|
+
db,
|
|
73
|
+
sanityClient,
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
const result = await engine.sync({
|
|
77
|
+
siteUrl: 'sc-domain:example.com',
|
|
78
|
+
siteId: 'sanity-site-document-id',
|
|
79
|
+
dryRun: false,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### DecayDetector
|
|
84
|
+
|
|
85
|
+
Identifies content showing signs of performance decline.
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import { DecayDetector } from '@pagebridge/core';
|
|
89
|
+
|
|
90
|
+
const detector = new DecayDetector({
|
|
91
|
+
db,
|
|
92
|
+
rules: [
|
|
93
|
+
{
|
|
94
|
+
name: 'position_decay',
|
|
95
|
+
enabled: true,
|
|
96
|
+
threshold: 3, // positions dropped
|
|
97
|
+
windowDays: 28,
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
name: 'low_ctr',
|
|
101
|
+
enabled: true,
|
|
102
|
+
threshold: 0.01, // 1% CTR
|
|
103
|
+
positionThreshold: 10,
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
name: 'impressions_drop',
|
|
107
|
+
enabled: true,
|
|
108
|
+
threshold: 0.5, // 50% drop
|
|
109
|
+
windowDays: 28,
|
|
110
|
+
},
|
|
111
|
+
],
|
|
112
|
+
quietPeriod: {
|
|
113
|
+
enabled: true,
|
|
114
|
+
days: 45,
|
|
115
|
+
},
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
const signals = await detector.detect({
|
|
119
|
+
siteId: 'sanity-site-document-id',
|
|
120
|
+
documents: matchedDocuments,
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### URLMatcher
|
|
125
|
+
|
|
126
|
+
Maps GSC page URLs to Sanity documents.
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
import { URLMatcher } from '@pagebridge/core';
|
|
130
|
+
|
|
131
|
+
const matcher = new URLMatcher({
|
|
132
|
+
siteUrl: 'https://example.com',
|
|
133
|
+
pathPrefix: '/blog',
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
const results = matcher.match({
|
|
137
|
+
pages: gscPages,
|
|
138
|
+
documents: sanityDocuments,
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
// Results include exact, normalized, and fuzzy matches
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### TaskGenerator
|
|
145
|
+
|
|
146
|
+
Creates refresh tasks in Sanity for pages with decay signals.
|
|
147
|
+
|
|
148
|
+
```typescript
|
|
149
|
+
import { TaskGenerator } from '@pagebridge/core';
|
|
150
|
+
|
|
151
|
+
const generator = new TaskGenerator({
|
|
152
|
+
sanityClient,
|
|
153
|
+
siteId: 'sanity-site-document-id',
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
const tasks = await generator.generate({
|
|
157
|
+
signals: decaySignals,
|
|
158
|
+
dryRun: false,
|
|
159
|
+
});
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Decay Detection Rules
|
|
163
|
+
|
|
164
|
+
The default rules detect three patterns:
|
|
165
|
+
|
|
166
|
+
| Rule | Description | Default Threshold |
|
|
167
|
+
|------|-------------|-------------------|
|
|
168
|
+
| `position_decay` | Average position dropped significantly | 3+ positions over 28 days |
|
|
169
|
+
| `low_ctr` | Low CTR despite good rankings | CTR < 1% for pages in top 10 |
|
|
170
|
+
| `impressions_drop` | Sharp decline in impressions | 50%+ drop over 28 days |
|
|
171
|
+
|
|
172
|
+
A configurable "quiet period" (default 45 days) prevents flagging recently published content.
|
|
173
|
+
|
|
174
|
+
## Environment Variables
|
|
175
|
+
|
|
176
|
+
Required for full functionality:
|
|
177
|
+
|
|
178
|
+
- `GOOGLE_SERVICE_ACCOUNT` - JSON stringified Google service account credentials
|
|
179
|
+
- `DATABASE_URL` - PostgreSQL connection string
|
|
180
|
+
- `SANITY_PROJECT_ID` - Sanity project ID
|
|
181
|
+
- `SANITY_DATASET` - Sanity dataset name
|
|
182
|
+
- `SANITY_TOKEN` - Sanity API token with write access
|
|
183
|
+
|
|
184
|
+
## API Reference
|
|
185
|
+
|
|
186
|
+
### Types
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
// GSC Client
|
|
190
|
+
interface GSCClientOptions {
|
|
191
|
+
serviceAccountJson: string;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
interface IndexStatusResult {
|
|
195
|
+
verdict: IndexVerdict;
|
|
196
|
+
coverageState: string;
|
|
197
|
+
indexingState: string;
|
|
198
|
+
pageFetchState: string;
|
|
199
|
+
lastCrawlTime?: string;
|
|
200
|
+
robotsTxtState: string;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// Sync Engine
|
|
204
|
+
interface SyncOptions {
|
|
205
|
+
siteUrl: string;
|
|
206
|
+
siteId: string;
|
|
207
|
+
dryRun?: boolean;
|
|
208
|
+
days?: number;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
interface SyncResult {
|
|
212
|
+
rowsProcessed: number;
|
|
213
|
+
snapshotsWritten: number;
|
|
214
|
+
errors: string[];
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// Decay Detection
|
|
218
|
+
interface DecaySignal {
|
|
219
|
+
page: string;
|
|
220
|
+
documentId: string;
|
|
221
|
+
rule: string;
|
|
222
|
+
severity: 'low' | 'medium' | 'high';
|
|
223
|
+
metrics: {
|
|
224
|
+
before: number;
|
|
225
|
+
now: number;
|
|
226
|
+
delta: number;
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
// URL Matching
|
|
231
|
+
interface MatchResult {
|
|
232
|
+
page: string;
|
|
233
|
+
documentId: string;
|
|
234
|
+
matchType: 'exact' | 'normalized' | 'fuzzy';
|
|
235
|
+
confidence: number;
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { DrizzleClient } from "@pagebridge/db";
|
|
2
|
+
export interface DecayRule {
|
|
3
|
+
type: "position_decay" | "low_ctr" | "impressions_drop";
|
|
4
|
+
threshold: number;
|
|
5
|
+
minImpressions: number;
|
|
6
|
+
comparisonWindowDays: number;
|
|
7
|
+
sustainedDays: number;
|
|
8
|
+
}
|
|
9
|
+
export interface QuietPeriodConfig {
|
|
10
|
+
enabled: boolean;
|
|
11
|
+
days: number;
|
|
12
|
+
}
|
|
13
|
+
export interface DecaySignal {
|
|
14
|
+
page: string;
|
|
15
|
+
reason: "position_decay" | "low_ctr" | "impressions_drop";
|
|
16
|
+
severity: "low" | "medium" | "high";
|
|
17
|
+
metrics: {
|
|
18
|
+
positionBefore: number;
|
|
19
|
+
positionNow: number;
|
|
20
|
+
positionDelta: number;
|
|
21
|
+
ctrBefore: number;
|
|
22
|
+
ctrNow: number;
|
|
23
|
+
impressions: number;
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
export declare const defaultRules: DecayRule[];
|
|
27
|
+
export declare class DecayDetector {
|
|
28
|
+
private db;
|
|
29
|
+
private rules;
|
|
30
|
+
constructor(db: DrizzleClient, rules?: DecayRule[]);
|
|
31
|
+
detectDecay(siteId: string, publishedDates: Map<string, Date>, quietPeriod?: QuietPeriodConfig): Promise<DecaySignal[]>;
|
|
32
|
+
private getAverageMetrics;
|
|
33
|
+
private evaluateRule;
|
|
34
|
+
private calculateSeverity;
|
|
35
|
+
private deduplicateSignals;
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=decay-detector.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"decay-detector.d.ts","sourceRoot":"","sources":["../src/decay-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,gBAAgB,GAAG,SAAS,GAAG,kBAAkB,CAAC;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,kBAAkB,CAAC;IAC1D,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AASD,eAAO,MAAM,YAAY,EAAE,SAAS,EAsBnC,CAAC;AAEF,qBAAa,aAAa;IAEtB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,KAAK;gBADL,EAAE,EAAE,aAAa,EACjB,KAAK,GAAE,SAAS,EAAiB;IAGrC,WAAW,CACf,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EACjC,WAAW,GAAE,iBAA+C,GAC3D,OAAO,CAAC,WAAW,EAAE,CAAC;YAsCX,iBAAiB;IA8B/B,OAAO,CAAC,YAAY;IAwEpB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;CAgB3B"}
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { searchAnalytics } from "@pagebridge/db";
|
|
2
|
+
import { and, avg, gte, lte, sql, eq } from "drizzle-orm";
|
|
3
|
+
export const defaultRules = [
|
|
4
|
+
{
|
|
5
|
+
type: "position_decay",
|
|
6
|
+
threshold: 3,
|
|
7
|
+
minImpressions: 100,
|
|
8
|
+
comparisonWindowDays: 28,
|
|
9
|
+
sustainedDays: 14,
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
type: "low_ctr",
|
|
13
|
+
threshold: 0.01,
|
|
14
|
+
minImpressions: 1000,
|
|
15
|
+
comparisonWindowDays: 28,
|
|
16
|
+
sustainedDays: 7,
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
type: "impressions_drop",
|
|
20
|
+
threshold: 0.5,
|
|
21
|
+
minImpressions: 500,
|
|
22
|
+
comparisonWindowDays: 28,
|
|
23
|
+
sustainedDays: 14,
|
|
24
|
+
},
|
|
25
|
+
];
|
|
26
|
+
export class DecayDetector {
|
|
27
|
+
db;
|
|
28
|
+
rules;
|
|
29
|
+
constructor(db, rules = defaultRules) {
|
|
30
|
+
this.db = db;
|
|
31
|
+
this.rules = rules;
|
|
32
|
+
}
|
|
33
|
+
async detectDecay(siteId, publishedDates, quietPeriod = { enabled: true, days: 45 }) {
|
|
34
|
+
const signals = [];
|
|
35
|
+
const now = new Date();
|
|
36
|
+
for (const rule of this.rules) {
|
|
37
|
+
const currentPeriodEnd = now;
|
|
38
|
+
const currentPeriodStart = daysAgo(rule.sustainedDays);
|
|
39
|
+
const previousPeriodEnd = daysAgo(rule.comparisonWindowDays);
|
|
40
|
+
const previousPeriodStart = daysAgo(rule.comparisonWindowDays + rule.sustainedDays);
|
|
41
|
+
const [currentMetrics, previousMetrics] = await Promise.all([
|
|
42
|
+
this.getAverageMetrics(siteId, currentPeriodStart, currentPeriodEnd),
|
|
43
|
+
this.getAverageMetrics(siteId, previousPeriodStart, previousPeriodEnd),
|
|
44
|
+
]);
|
|
45
|
+
for (const current of currentMetrics) {
|
|
46
|
+
if (quietPeriod.enabled) {
|
|
47
|
+
const publishDate = publishedDates.get(current.page);
|
|
48
|
+
if (publishDate && daysSince(publishDate) < quietPeriod.days) {
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
if (current.impressions < rule.minImpressions)
|
|
53
|
+
continue;
|
|
54
|
+
const previous = previousMetrics.find((p) => p.page === current.page);
|
|
55
|
+
if (!previous)
|
|
56
|
+
continue;
|
|
57
|
+
const signal = this.evaluateRule(rule, current, previous);
|
|
58
|
+
if (signal)
|
|
59
|
+
signals.push(signal);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return this.deduplicateSignals(signals);
|
|
63
|
+
}
|
|
64
|
+
async getAverageMetrics(siteId, startDate, endDate) {
|
|
65
|
+
const results = await this.db
|
|
66
|
+
.select({
|
|
67
|
+
page: searchAnalytics.page,
|
|
68
|
+
avgPosition: avg(searchAnalytics.position),
|
|
69
|
+
avgCtr: avg(searchAnalytics.ctr),
|
|
70
|
+
totalImpressions: sql `sum(${searchAnalytics.impressions})`,
|
|
71
|
+
})
|
|
72
|
+
.from(searchAnalytics)
|
|
73
|
+
.where(and(eq(searchAnalytics.siteId, siteId), gte(searchAnalytics.date, formatDate(startDate)), lte(searchAnalytics.date, formatDate(endDate))))
|
|
74
|
+
.groupBy(searchAnalytics.page);
|
|
75
|
+
return results.map((r) => ({
|
|
76
|
+
page: r.page,
|
|
77
|
+
position: Number(r.avgPosition) || 0,
|
|
78
|
+
ctr: Number(r.avgCtr) || 0,
|
|
79
|
+
impressions: Number(r.totalImpressions) || 0,
|
|
80
|
+
}));
|
|
81
|
+
}
|
|
82
|
+
evaluateRule(rule, current, previous) {
|
|
83
|
+
switch (rule.type) {
|
|
84
|
+
case "position_decay": {
|
|
85
|
+
const delta = current.position - previous.position;
|
|
86
|
+
if (delta >= rule.threshold) {
|
|
87
|
+
return {
|
|
88
|
+
page: current.page,
|
|
89
|
+
reason: "position_decay",
|
|
90
|
+
severity: this.calculateSeverity(delta, [3, 5, 8]),
|
|
91
|
+
metrics: {
|
|
92
|
+
positionBefore: previous.position,
|
|
93
|
+
positionNow: current.position,
|
|
94
|
+
positionDelta: delta,
|
|
95
|
+
ctrBefore: previous.ctr,
|
|
96
|
+
ctrNow: current.ctr,
|
|
97
|
+
impressions: current.impressions,
|
|
98
|
+
},
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
break;
|
|
102
|
+
}
|
|
103
|
+
case "low_ctr": {
|
|
104
|
+
if (current.ctr < rule.threshold && current.position <= 10) {
|
|
105
|
+
return {
|
|
106
|
+
page: current.page,
|
|
107
|
+
reason: "low_ctr",
|
|
108
|
+
severity: this.calculateSeverity(rule.threshold - current.ctr, [0.005, 0.01, 0.02]),
|
|
109
|
+
metrics: {
|
|
110
|
+
positionBefore: previous.position,
|
|
111
|
+
positionNow: current.position,
|
|
112
|
+
positionDelta: current.position - previous.position,
|
|
113
|
+
ctrBefore: previous.ctr,
|
|
114
|
+
ctrNow: current.ctr,
|
|
115
|
+
impressions: current.impressions,
|
|
116
|
+
},
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
break;
|
|
120
|
+
}
|
|
121
|
+
case "impressions_drop": {
|
|
122
|
+
const dropRatio = 1 - current.impressions / previous.impressions;
|
|
123
|
+
if (dropRatio >= rule.threshold) {
|
|
124
|
+
return {
|
|
125
|
+
page: current.page,
|
|
126
|
+
reason: "impressions_drop",
|
|
127
|
+
severity: this.calculateSeverity(dropRatio, [0.3, 0.5, 0.7]),
|
|
128
|
+
metrics: {
|
|
129
|
+
positionBefore: previous.position,
|
|
130
|
+
positionNow: current.position,
|
|
131
|
+
positionDelta: current.position - previous.position,
|
|
132
|
+
ctrBefore: previous.ctr,
|
|
133
|
+
ctrNow: current.ctr,
|
|
134
|
+
impressions: current.impressions,
|
|
135
|
+
},
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
break;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return undefined;
|
|
142
|
+
}
|
|
143
|
+
calculateSeverity(value, thresholds) {
|
|
144
|
+
if (value >= thresholds[2])
|
|
145
|
+
return "high";
|
|
146
|
+
if (value >= thresholds[1])
|
|
147
|
+
return "medium";
|
|
148
|
+
return "low";
|
|
149
|
+
}
|
|
150
|
+
deduplicateSignals(signals) {
|
|
151
|
+
const byPage = new Map();
|
|
152
|
+
const severityOrder = { high: 3, medium: 2, low: 1 };
|
|
153
|
+
for (const signal of signals) {
|
|
154
|
+
const existing = byPage.get(signal.page);
|
|
155
|
+
if (!existing ||
|
|
156
|
+
severityOrder[signal.severity] > severityOrder[existing.severity]) {
|
|
157
|
+
byPage.set(signal.page, signal);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
return Array.from(byPage.values());
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
function daysAgo(days) {
|
|
164
|
+
const date = new Date();
|
|
165
|
+
date.setDate(date.getDate() - days);
|
|
166
|
+
return date;
|
|
167
|
+
}
|
|
168
|
+
function daysSince(date) {
|
|
169
|
+
const now = new Date();
|
|
170
|
+
const diff = now.getTime() - date.getTime();
|
|
171
|
+
return Math.floor(diff / (1000 * 60 * 60 * 24));
|
|
172
|
+
}
|
|
173
|
+
function formatDate(date) {
|
|
174
|
+
return date.toISOString().split("T")[0];
|
|
175
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
export interface GSCClientOptions {
|
|
2
|
+
credentials: {
|
|
3
|
+
client_email: string;
|
|
4
|
+
private_key: string;
|
|
5
|
+
};
|
|
6
|
+
}
|
|
7
|
+
export interface SearchAnalyticsRow {
|
|
8
|
+
page: string;
|
|
9
|
+
query?: string;
|
|
10
|
+
date?: string;
|
|
11
|
+
clicks: number;
|
|
12
|
+
impressions: number;
|
|
13
|
+
ctr: number;
|
|
14
|
+
position: number;
|
|
15
|
+
}
|
|
16
|
+
export interface FetchOptions {
|
|
17
|
+
siteUrl: string;
|
|
18
|
+
startDate: Date;
|
|
19
|
+
endDate: Date;
|
|
20
|
+
dimensions?: ("page" | "query" | "date")[];
|
|
21
|
+
rowLimit?: number;
|
|
22
|
+
}
|
|
23
|
+
export type IndexVerdict = "PASS" | "FAIL" | "NEUTRAL" | "VERDICT_UNSPECIFIED";
|
|
24
|
+
export interface IndexStatusResult {
|
|
25
|
+
verdict: IndexVerdict;
|
|
26
|
+
coverageState: string | null;
|
|
27
|
+
indexingState: string | null;
|
|
28
|
+
pageFetchState: string | null;
|
|
29
|
+
lastCrawlTime: Date | null;
|
|
30
|
+
robotsTxtState: string | null;
|
|
31
|
+
}
|
|
32
|
+
export declare class GSCClient {
|
|
33
|
+
private auth;
|
|
34
|
+
private searchConsole;
|
|
35
|
+
constructor(options: GSCClientOptions);
|
|
36
|
+
fetchSearchAnalytics(options: FetchOptions): Promise<SearchAnalyticsRow[]>;
|
|
37
|
+
listSites(): Promise<string[]>;
|
|
38
|
+
inspectUrl(siteUrl: string, inspectionUrl: string): Promise<IndexStatusResult>;
|
|
39
|
+
}
|
|
40
|
+
//# sourceMappingURL=gsc-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"gsc-client.d.ts","sourceRoot":"","sources":["../src/gsc-client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,qBAAqB,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,aAAa,CAAiC;gBAE1C,OAAO,EAAE,gBAAgB;IAa/B,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAyC1E,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAK9B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAmBrF"}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { google } from "googleapis";
|
|
2
|
+
export class GSCClient {
|
|
3
|
+
auth;
|
|
4
|
+
searchConsole;
|
|
5
|
+
constructor(options) {
|
|
6
|
+
this.auth = new google.auth.JWT({
|
|
7
|
+
email: options.credentials.client_email,
|
|
8
|
+
key: options.credentials.private_key,
|
|
9
|
+
scopes: ["https://www.googleapis.com/auth/webmasters.readonly"],
|
|
10
|
+
});
|
|
11
|
+
this.searchConsole = google.searchconsole({
|
|
12
|
+
version: "v1",
|
|
13
|
+
auth: this.auth,
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
async fetchSearchAnalytics(options) {
|
|
17
|
+
const { siteUrl, startDate, endDate, dimensions = ["page", "date"], rowLimit = 25000 } = options;
|
|
18
|
+
const rows = [];
|
|
19
|
+
let startRow = 0;
|
|
20
|
+
while (true) {
|
|
21
|
+
const response = await this.searchConsole.searchanalytics.query({
|
|
22
|
+
siteUrl,
|
|
23
|
+
requestBody: {
|
|
24
|
+
startDate: formatDate(startDate),
|
|
25
|
+
endDate: formatDate(endDate),
|
|
26
|
+
dimensions,
|
|
27
|
+
rowLimit,
|
|
28
|
+
startRow,
|
|
29
|
+
},
|
|
30
|
+
});
|
|
31
|
+
const responseRows = response.data.rows ?? [];
|
|
32
|
+
if (responseRows.length === 0)
|
|
33
|
+
break;
|
|
34
|
+
for (const row of responseRows) {
|
|
35
|
+
const keys = row.keys ?? [];
|
|
36
|
+
rows.push({
|
|
37
|
+
page: dimensions.includes("page") ? keys[dimensions.indexOf("page")] : "",
|
|
38
|
+
query: dimensions.includes("query") ? keys[dimensions.indexOf("query")] : undefined,
|
|
39
|
+
date: dimensions.includes("date") ? keys[dimensions.indexOf("date")] : undefined,
|
|
40
|
+
clicks: row.clicks ?? 0,
|
|
41
|
+
impressions: row.impressions ?? 0,
|
|
42
|
+
ctr: row.ctr ?? 0,
|
|
43
|
+
position: row.position ?? 0,
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
if (responseRows.length < rowLimit)
|
|
47
|
+
break;
|
|
48
|
+
startRow += rowLimit;
|
|
49
|
+
}
|
|
50
|
+
return rows;
|
|
51
|
+
}
|
|
52
|
+
async listSites() {
|
|
53
|
+
const response = await this.searchConsole.sites.list();
|
|
54
|
+
return (response.data.siteEntry ?? []).map((site) => site.siteUrl).filter(Boolean);
|
|
55
|
+
}
|
|
56
|
+
async inspectUrl(siteUrl, inspectionUrl) {
|
|
57
|
+
const response = await this.searchConsole.urlInspection.index.inspect({
|
|
58
|
+
requestBody: {
|
|
59
|
+
inspectionUrl,
|
|
60
|
+
siteUrl,
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
const result = response.data.inspectionResult?.indexStatusResult;
|
|
64
|
+
return {
|
|
65
|
+
verdict: result?.verdict ?? "VERDICT_UNSPECIFIED",
|
|
66
|
+
coverageState: result?.coverageState ?? null,
|
|
67
|
+
indexingState: result?.indexingState ?? null,
|
|
68
|
+
pageFetchState: result?.pageFetchState ?? null,
|
|
69
|
+
lastCrawlTime: result?.lastCrawlTime ? new Date(result.lastCrawlTime) : null,
|
|
70
|
+
robotsTxtState: result?.robotsTxtState ?? null,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
function formatDate(date) {
|
|
75
|
+
return date.toISOString().split("T")[0];
|
|
76
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { GSCClient, type GSCClientOptions, type IndexStatusResult, type IndexVerdict, } from "./gsc-client.js";
|
|
2
|
+
export { SyncEngine, type SyncOptions, type SyncResult, type IndexStatusSyncResult, } from "./sync-engine.js";
|
|
3
|
+
export { DecayDetector, defaultRules, type DecayRule, type DecaySignal, type QuietPeriodConfig, } from "./decay-detector.js";
|
|
4
|
+
export { URLMatcher, type MatchResult, type URLMatcherConfig, type UnmatchReason, type MatchDiagnostics, } from "./url-matcher.js";
|
|
5
|
+
export { TaskGenerator, type TaskGeneratorOptions, type QueryContext, } from "./task-generator.js";
|
|
6
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { DrizzleClient } from "@pagebridge/db";
|
|
2
|
+
import type { SanityClient } from "@sanity/client";
|
|
3
|
+
import type { GSCClient, IndexStatusResult } from "./gsc-client.js";
|
|
4
|
+
export interface SyncOptions {
|
|
5
|
+
siteUrl: string;
|
|
6
|
+
startDate?: Date;
|
|
7
|
+
endDate?: Date;
|
|
8
|
+
dimensions?: ("page" | "query" | "date")[];
|
|
9
|
+
}
|
|
10
|
+
export interface SyncResult {
|
|
11
|
+
pages: string[];
|
|
12
|
+
rowsProcessed: number;
|
|
13
|
+
syncLogId: string;
|
|
14
|
+
}
|
|
15
|
+
export interface IndexStatusSyncResult {
|
|
16
|
+
checked: number;
|
|
17
|
+
indexed: number;
|
|
18
|
+
notIndexed: number;
|
|
19
|
+
skipped: number;
|
|
20
|
+
}
|
|
21
|
+
export interface SyncEngineOptions {
|
|
22
|
+
gsc: GSCClient;
|
|
23
|
+
db: DrizzleClient;
|
|
24
|
+
sanity: SanityClient;
|
|
25
|
+
}
|
|
26
|
+
export declare class SyncEngine {
|
|
27
|
+
private gsc;
|
|
28
|
+
private db;
|
|
29
|
+
private sanity;
|
|
30
|
+
constructor(options: SyncEngineOptions);
|
|
31
|
+
sync(options: SyncOptions): Promise<SyncResult>;
|
|
32
|
+
writeSnapshots(siteId: string, matches: {
|
|
33
|
+
gscUrl: string;
|
|
34
|
+
sanityId: string | undefined;
|
|
35
|
+
}[], siteUrl?: string): Promise<void>;
|
|
36
|
+
syncIndexStatus(siteUrl: string, pages: string[]): Promise<IndexStatusSyncResult>;
|
|
37
|
+
getIndexStatus(siteUrl: string, page: string): Promise<IndexStatusResult | null>;
|
|
38
|
+
private getAggregatedMetrics;
|
|
39
|
+
private getTopQueries;
|
|
40
|
+
}
|
|
41
|
+
//# sourceMappingURL=sync-engine.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../src/sync-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,SAAS,CAAC;IACf,EAAE,EAAE,aAAa,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,MAAM,CAAe;gBAEjB,OAAO,EAAE,iBAAiB;IAMhC,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA+G/C,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,EAC3D,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmFV,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,qBAAqB,CAAC;IA6E3B,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;YAqBtB,oBAAoB;YAiDpB,aAAa;CAyD5B"}
|