@gscdump/sdk 1.0.1 → 1.0.3

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.
Files changed (52) hide show
  1. package/README.md +7 -1
  2. package/dist/_chunks/errors.d.mts +22 -0
  3. package/dist/_chunks/request.d.mts +25 -0
  4. package/dist/_chunks/request.mjs +84 -0
  5. package/dist/_chunks/search-console-signals.mjs +9 -0
  6. package/dist/analytics-client.d.mts +53 -0
  7. package/dist/analytics-client.mjs +128 -0
  8. package/dist/analyzer-defs.d.mts +73 -0
  9. package/dist/analyzer-defs.mjs +4 -0
  10. package/dist/anonymization.d.mts +6 -0
  11. package/dist/anonymization.mjs +12 -0
  12. package/dist/archetype-compile.d.mts +48 -0
  13. package/dist/archetype-compile.mjs +124 -0
  14. package/dist/client.d.mts +122 -0
  15. package/dist/client.mjs +365 -0
  16. package/dist/country-names.d.mts +2 -0
  17. package/dist/country-names.mjs +56 -0
  18. package/dist/cwv-thresholds.d.mts +13 -0
  19. package/dist/cwv-thresholds.mjs +23 -0
  20. package/dist/errors.d.mts +2 -0
  21. package/dist/errors.mjs +47 -0
  22. package/dist/gsc-console-url.d.mts +12 -0
  23. package/dist/gsc-console-url.mjs +15 -0
  24. package/dist/gsc-constants.d.mts +17 -0
  25. package/dist/gsc-constants.mjs +2 -0
  26. package/dist/gsc-error.d.mts +12 -0
  27. package/dist/gsc-error.mjs +42 -0
  28. package/dist/gsc-period-presets.d.mts +31 -0
  29. package/dist/gsc-period-presets.mjs +115 -0
  30. package/dist/gsc-rows.d.mts +54 -0
  31. package/dist/gsc-rows.mjs +48 -0
  32. package/dist/hosted-query.d.mts +31 -0
  33. package/dist/hosted-query.mjs +105 -0
  34. package/dist/index.d.mts +21 -852
  35. package/dist/index.mjs +21 -2275
  36. package/dist/indexing-issues.d.mts +29 -0
  37. package/dist/indexing-issues.mjs +168 -0
  38. package/dist/lifecycle.d.mts +14 -0
  39. package/dist/lifecycle.mjs +84 -0
  40. package/dist/period.d.mts +49 -0
  41. package/dist/period.mjs +138 -0
  42. package/dist/search-console-stage.d.mts +102 -0
  43. package/dist/search-console-stage.mjs +292 -0
  44. package/dist/site-baseline.d.mts +69 -0
  45. package/dist/site-baseline.mjs +112 -0
  46. package/dist/site-triage.d.mts +86 -0
  47. package/dist/site-triage.mjs +268 -0
  48. package/dist/v1/index.d.mts +1 -1
  49. package/dist/v1/index.mjs +2 -2
  50. package/dist/webhook.d.mts +29 -0
  51. package/dist/webhook.mjs +118 -0
  52. package/package.json +110 -5
package/dist/index.d.mts CHANGED
@@ -1,853 +1,22 @@
1
- import { Result } from "gscdump/result";
2
- import { BuilderState } from "gscdump/query";
3
- import { AddPartnerTeamMemberParams, AnalysisSourcesResponse, ArchetypeQuery, BackfillRange, BackfillResponse, BindPartnerSiteTeamParams, BindPartnerTeamCatalogParams, BindPartnerTeamCatalogResponse, BuilderStateWire, BulkFileResolutionRequest, BulkFileResolutionResponse, BulkRegisterPartnerSitesParams, BulkRegisterPartnerSitesResponse, CANONICAL_WEBHOOK_EVENTS, CountriesResponse, CreatePartnerTeamParams, DataDetailOptions, DataQueryOptions, DeletePartnerUserResponse, GscAddAndVerifyResponse, GscSearchType, GscVerificationRequest, GscVerificationTokenResponse, GscdumpAnalysisSourcesResponse, GscdumpAvailableSite, GscdumpCanonicalMismatchesResponse, GscdumpDataDetailResponse, GscdumpDataResponse, GscdumpIndexPercentResponse, GscdumpIndexingDiagnosticsResponse, GscdumpIndexingResponse, GscdumpIndexingUrlsResponse, GscdumpKeywordSparklinesParams, GscdumpKeywordSparklinesResponse, GscdumpPageTrendParams, GscdumpPageTrendResponse, GscdumpPermissionRecovery, GscdumpQueryTrendParams, GscdumpQueryTrendResponse, GscdumpSiteIntIdCrosswalkResponse, GscdumpSiteRegistration, GscdumpSitemapChangesResponse, GscdumpSitemapMembershipParams, GscdumpSitemapMembershipResponse, GscdumpSitemapsResponse, GscdumpSyncStatusResponse, GscdumpTeamCatalogRef, GscdumpTeamMemberRow, GscdumpTeamRow, GscdumpTopAssociationParams, GscdumpTopAssociationResponse, GscdumpUserRegistration, GscdumpUserSettings, GscdumpUserSite, GscdumpUserStatus, GscdumpUserTokenUpdate, IndexingDiagnostics, IndexingDiagnosticsParams, IndexingInspectRateLimited, IndexingInspectRequest, IndexingInspectResponse, IndexingUrlStatus, IndexingUrlsParams, IndexingUrlsResponse, InspectionHistoryResponse, InspectionIndex, PartnerLifecycleResponse, PartnerLifecycleSite, PartnerSitemapAction, PartnerSitemapActionResponse, PartnerWebhookHeaders, QueryDimSourceResponse, RegisterPartnerSiteParams, RegisterPartnerUserParams, RollupEnvelope, SearchAppearanceResponse, SiteListItem, SitemapChangesResponse, SitemapHistoryResponse, SitemapIndex, SourceInfoOptions, SourceInfoResponse, UpdatePartnerUserTokensParams, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookEnvelope, WhoamiResponse, WireDateRange } from "@gscdump/contracts";
4
- import { ZodTypeAny } from "zod";
5
- import { ActionSource } from "@gscdump/analysis";
6
- import { AnalysisTool } from "@gscdump/engine/analysis-types";
7
- type GscSearchType$1 = 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews';
8
- interface SearchTypeOptions {
9
- searchType?: GscSearchType$1;
10
- }
11
- interface SourceRangeOptions {
12
- start?: string;
13
- end?: string;
14
- startDate?: string;
15
- endDate?: string;
16
- }
17
- interface AnalysisSourcesOptions extends SearchTypeOptions, SourceRangeOptions {
18
- tables?: string[] | string;
19
- maxBytes?: number;
20
- maxRows?: number;
21
- maxFiles?: number;
22
- }
23
- declare const DEFAULT_SEARCH_TYPE: GscSearchType$1;
24
- declare function withDefaultSearchType<T extends object>(value: T, searchType?: GscSearchType$1): T & SearchTypeOptions & Record<string, unknown>;
25
- declare function withDefaultSearchType<T>(value: T, searchType?: GscSearchType$1): T;
26
- declare function searchTypeQuery(searchType?: GscSearchType$1): Record<string, string>;
27
- declare function dateRangeOptionsQuery(options: SourceRangeOptions | undefined): Record<string, string>;
28
- declare function sourceInfoQuery(options: SourceInfoOptions | undefined): Record<string, string>;
29
- declare function tablesQuery(tablesOrOptions: string[] | string | AnalysisSourcesOptions | undefined, options?: AnalysisSourcesOptions): Record<string, string>;
30
- type PartnerErrorKind = 'auth' | 'rate-limit' | 'provisioning' | 'permission' | 'network' | 'validation' | 'not-found' | 'server' | 'unknown';
31
- interface PartnerErrorInfo {
32
- kind: PartnerErrorKind;
33
- statusCode?: number;
34
- message: string;
35
- data?: unknown;
36
- }
37
- declare class PartnerApiError extends Error {
38
- readonly kind: PartnerErrorKind;
39
- readonly statusCode?: number;
40
- readonly data?: unknown;
41
- constructor(info: PartnerErrorInfo);
42
- }
43
- declare function toPartnerError(error: unknown): PartnerApiError;
44
- /**
45
- * Re-raise a modelled `PartnerApiError` as itself. The error variant of every
46
- * `*Result` core already IS the throwable `PartnerApiError`, so the throwing
47
- * wrappers preserve the exact identity/message existing call sites and tests
48
- * assert (`rejects.toThrow(PartnerApiError)`, `toThrow('Invalid webhook signature')`).
49
- */
50
- declare function partnerErrorToException(error: PartnerApiError): PartnerApiError;
51
- type HostedFetch = <T = unknown>(request: string, options?: HostedFetchOptions) => Promise<T>;
52
- type HostedHeaders = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
53
- interface HostedFetchOptions {
54
- method?: string;
55
- headers?: HeadersInit;
56
- query?: Record<string, unknown>;
57
- body?: unknown;
58
- /** Opt into in-flight de-dupe for safe read-style POST requests. */
59
- dedupe?: boolean;
60
- [key: string]: unknown;
61
- }
62
- interface HostedClientOptions {
63
- apiBase?: string;
64
- fetch?: HostedFetch;
65
- headers?: HostedHeaders;
66
- validate?: boolean | 'request' | 'response';
67
- /** Coalesce concurrent identical GET/HEAD requests within this client instance. */
68
- dedupe?: boolean;
69
- /** Optional shared in-flight map for de-duping across related client instances. */
70
- dedupeScope?: Map<string, Promise<Result<unknown, PartnerApiError>>>;
71
- }
72
- type AnalyticsFetch = HostedFetch;
73
- type AnalyticsHeaders = HostedHeaders;
74
- type AnalyticsFetchOptions = HostedFetchOptions;
75
- interface AnalyticsClientOptions extends HostedClientOptions {
76
- apiBase?: string;
77
- fetch?: AnalyticsFetch;
78
- headers?: AnalyticsHeaders;
79
- validate?: boolean | 'request' | 'response';
80
- }
81
- /** Hosted analytics transport exposed by `@gscdump/sdk`. */
82
- interface AnalyticsClient {
83
- whoami: () => Promise<WhoamiResponse>;
84
- listSites: () => Promise<SiteListItem[]>;
85
- getBulkSources: (params: BulkFileResolutionRequest) => Promise<BulkFileResolutionResponse>;
86
- getSourceInfo: (siteId: string, options?: SourceInfoOptions) => Promise<SourceInfoResponse>;
87
- getAnalysisSources: (siteId: string, tables?: string[] | string | AnalysisSourcesOptions, options?: SearchTypeOptions & SourceRangeOptions) => Promise<AnalysisSourcesResponse>;
88
- getQueryDimSource: (siteId: string) => Promise<QueryDimSourceResponse>;
89
- analyze: <T = unknown>(siteId: string, params: unknown) => Promise<T>;
90
- getRollup: <T = unknown>(siteId: string, rollupId: string, params?: {
91
- start?: string;
92
- end?: string;
93
- }) => Promise<RollupEnvelope<T>>;
94
- requestBackfill: (siteId: string, range: BackfillRange) => Promise<BackfillResponse>;
95
- getSitemaps: (siteId: string) => Promise<SitemapIndex>;
96
- getSitemapHistory: (siteId: string, hash: string) => Promise<SitemapHistoryResponse>;
97
- getSitemapChanges: (siteId: string, params?: {
98
- days?: number;
99
- }) => Promise<SitemapChangesResponse>;
100
- getInspections: (siteId: string) => Promise<InspectionIndex>;
101
- getInspectionHistory: (siteId: string, hash: string) => Promise<InspectionHistoryResponse>;
102
- getIndexingUrls: (siteId: string, params?: {
103
- limit?: number;
104
- offset?: number;
105
- status?: IndexingUrlStatus;
106
- issue?: string;
107
- search?: string;
108
- }) => Promise<IndexingUrlsResponse>;
109
- getIndexingDiagnostics: (siteId: string, params?: IndexingDiagnosticsParams) => Promise<IndexingDiagnostics>;
110
- requestIndexingInspect: (siteId: string, body: IndexingInspectRequest) => Promise<IndexingInspectResponse | IndexingInspectRateLimited>;
111
- getCountries: (siteId: string, range: {
112
- start: string;
113
- end: string;
114
- }) => Promise<CountriesResponse>;
115
- getSearchAppearance: (siteId: string, range: {
116
- start: string;
117
- end: string;
118
- }) => Promise<SearchAppearanceResponse>;
119
- }
120
- declare function createAnalyticsClient(options?: AnalyticsClientOptions): AnalyticsClient;
121
- type GscAnalyzerKind = 'analyzer' | 'semantic' | 'action';
122
- type GscAnalyzerAccent = 'primary' | 'warning' | 'success' | 'error' | 'neutral';
123
- interface GscAnalyzerInsightCard {
124
- icon: string;
125
- accent: GscAnalyzerAccent;
126
- description: string;
127
- summarize: (res: {
128
- results: unknown[];
129
- meta: Record<string, unknown>;
130
- }) => {
131
- headline: string;
132
- tagline: string;
133
- };
134
- }
135
- interface GscAnalyzerStatTile {
136
- label: string;
137
- value: string | number;
138
- /** Optional CSS color for the value (e.g. improved/worsened in change-points). */
139
- valueColor?: string;
140
- }
141
- interface GscAnalyzerPanelResult {
142
- results: unknown[];
143
- meta: Record<string, unknown>;
144
- queryMs?: number | null;
145
- }
146
- interface GscAnalyzerPanelSpec<TComponent = unknown> {
147
- /**
148
- * Body component. Receives `{ rows, meta, range }` as props. Lazy-import
149
- * to preserve route-level codesplitting.
150
- *
151
- * Typed `unknown` in the SDK; consumers can narrow via generic
152
- * (`GscAnalyzerDefinition<VueComponent>`).
153
- */
154
- component: TComponent;
155
- /** Project a result to the header stat tiles. Empty array = no tiles. */
156
- summarize?: (res: GscAnalyzerPanelResult) => GscAnalyzerStatTile[];
157
- /** Italic footer caption explaining the underlying method. */
158
- caption?: string;
159
- /**
160
- * When true, the shell skips its loading/error/empty gating and renders
161
- * the body component immediately (pipeline panels: action priority, content gap).
162
- */
163
- ownsLifecycle?: boolean;
164
- }
165
- interface GscAnalyzerCapabilities<TComponent = unknown> {
166
- /** Opt into the `/insights` curated grid by providing a card config. */
167
- insightCard?: GscAnalyzerInsightCard;
168
- /** Opt into `useActionPriority`. The value is the typed `ActionSource` slug. */
169
- actionPriority?: ActionSource;
170
- /**
171
- * Opt into the unified `/analyze` panel renderer. Without this, the tab
172
- * falls back to the generic table renderer.
173
- */
174
- panel?: GscAnalyzerPanelSpec<TComponent>;
175
- }
176
- type GscAnalyzerCapability = keyof GscAnalyzerCapabilities;
177
- interface GscAnalyzerDefinition<TComponent = unknown> {
178
- /** Stable analyzer id. Must match an `AnalysisTool` slug for built-in analyzers. */
179
- id: AnalysisTool | (string & {});
180
- label: string;
181
- kind: GscAnalyzerKind;
182
- /** Reads the per-query table; sums silently drop GSC-anonymized impressions. */
183
- isQueryGrained?: boolean;
184
- /** Capability opt-ins. Each key gates a downstream consumer. */
185
- capabilities?: GscAnalyzerCapabilities<TComponent>;
186
- }
187
- type GscAnalyzerDefinitionWithCapability<K extends GscAnalyzerCapability, TComponent = unknown> = GscAnalyzerDefinition<TComponent> & {
188
- capabilities: { [P in K]: NonNullable<GscAnalyzerCapabilities<TComponent>[P]>; };
189
- };
190
- declare function defineGscAnalyzer<TComponent = unknown>(def: GscAnalyzerDefinition<TComponent>): GscAnalyzerDefinition<TComponent>;
191
- interface DailyAnonInput {
192
- impressions: number;
193
- anonymizedImpressionsPct: number;
194
- }
195
- declare function weightedAnonPct(days: readonly DailyAnonInput[] | null | undefined, window?: number): number | null;
196
- /**
197
- * Extract the `{ start, end }` date window from a builder-state filter in
198
- * either accepted format (SDK-branded or partner wire). Returns `null` when no
199
- * complete range is present.
200
- */
201
- declare function extractWireDateRange(filter: unknown): WireDateRange | null;
202
- interface BuilderStateToArchetypeOptions {
203
- searchType?: GscSearchType;
204
- compareRange?: WireDateRange;
205
- }
206
- /**
207
- * Translate a `BuilderState` into the best-fit `ArchetypeQuery`, or `null`
208
- * when the shape can't be expressed (the caller keeps its legacy path — this
209
- * function never throws).
210
- *
211
- * Supported shapes (5 of the archetypes — the others are either caller-driven
212
- * builders never reached via a BuilderState, `arbitrary-sql`, or
213
- * `aux-cloud-only`):
214
- * - `dimensions: ['date']`, no entity filter → site-daily-timeseries
215
- * - `dimensions: ['date']`, one page/query/queryCanonical
216
- * equality → entity-daily-timeseries
217
- * - `dimensions: ['date', X]` → multi-series-stacked-daily
218
- * - `dimensions: [X]` (non-date) → top-n-breakdown (extra
219
- * equality filters on OTHER dimensions become `facets`)
220
- * - `dimensions: ['page','query']` (either order) → two-dimension-detail
221
- *
222
- * Everything else — 0 or 3+ dimensions, no date range, an OR group, a
223
- * non-equality predicate the target SQL builder can't apply, a
224
- * `two-dimension-detail` pair that isn't exactly {page, query} (the SQL is
225
- * hardcoded to `url, query` regardless of which two dims were requested) —
226
- * returns `null`.
227
- */
228
- declare function builderStateToArchetype(siteId: string, state: BuilderState, opts?: BuilderStateToArchetypeOptions): ArchetypeQuery | null;
229
- /**
230
- * Archetypes a hosted seam's execution wrapper can safely serve end-to-end
231
- * today (rows + an ACCURATE `totalCount`/`totals`, matching the legacy
232
- * `R2QueryResult` contract). `builderStateToArchetype` above can produce a
233
- * `two-dimension-detail` query, but `TwoDimensionDetailQuery`/
234
- * `buildTwoDimensionDetail` support neither `offset` nor `includeTotal` —
235
- * there is no way to get an exact grand total or paginate past page 1 through
236
- * the dispatcher yet, so seam wrappers decline it (same as a compile miss)
237
- * rather than serve a wrong `totalCount`. Revisit once the contract grows
238
- * those fields.
239
- */
240
- declare function archetypeSeamSupportsQuery(query: ArchetypeQuery): boolean;
241
- type PartnerFetch = HostedFetch;
242
- type PartnerHeaders = HostedHeaders;
243
- type PartnerFetchOptions = HostedFetchOptions;
244
- interface PartnerClientOptions extends HostedClientOptions {
245
- /**
246
- * Origin API base. Use `/api` for same-origin Nitro routes, or pass a full
247
- * remote origin base from the host app. The client has no baked-in origin.
248
- */
249
- apiBase?: string;
250
- /** Convenience auth hook. Equivalent to supplying `headers: { 'x-api-key': apiKey }`. */
251
- apiKey?: string;
252
- /** Any ofetch-compatible instance: global `$fetch`, `useGscFetch()`, or a custom test fake. */
253
- fetch?: PartnerFetch;
254
- /** Static or lazy headers. Lazy headers are resolved on every operation. */
255
- headers?: PartnerHeaders;
256
- /** Validate request payloads and response bodies with exported Zod schemas. */
257
- validate?: boolean | 'request' | 'response';
258
- }
259
- /** Hosted partner transport exposed by `@gscdump/sdk`. */
260
- interface PartnerClient {
261
- registerUser: (params: RegisterPartnerUserParams) => Promise<GscdumpUserRegistration>;
262
- updateUserTokens: (userId: string, params: UpdatePartnerUserTokensParams) => Promise<GscdumpUserTokenUpdate>;
263
- getUserStatus: (userId: string) => Promise<GscdumpUserStatus>;
264
- getUserLifecycle: (userId: string) => Promise<PartnerLifecycleResponse>;
265
- waitForUserReady: (userId: string, options?: {
266
- attempts?: number;
267
- intervalMs?: number;
268
- }) => Promise<GscdumpUserStatus>;
269
- waitForUserLifecycleReady: (userId: string, options?: {
270
- attempts?: number;
271
- intervalMs?: number;
272
- }) => Promise<PartnerLifecycleResponse>;
273
- getUserSites: (userId: string) => Promise<{
274
- sites: GscdumpUserSite[];
275
- }>;
276
- getAvailableSites: (userId: string) => Promise<{
277
- sites: GscdumpAvailableSite[];
278
- }>;
279
- getUserSiteIntIdCrosswalk: (userId: string) => Promise<GscdumpSiteIntIdCrosswalkResponse>;
280
- registerSite: (params: RegisterPartnerSiteParams) => Promise<GscdumpSiteRegistration>;
281
- bulkRegisterSites: (params: BulkRegisterPartnerSitesParams) => Promise<BulkRegisterPartnerSitesResponse>;
282
- requestSiteVerificationToken: (params: GscVerificationRequest) => Promise<GscVerificationTokenResponse>;
283
- addAndVerifySite: (params: GscVerificationRequest) => Promise<GscAddAndVerifyResponse>;
284
- deleteUser: (userId: string) => Promise<DeletePartnerUserResponse>;
285
- deleteSite: (siteId: string) => Promise<{
286
- success: boolean;
287
- }>;
288
- getAnalysisSources: (siteId: string, tables?: string[] | string | AnalysisSourcesOptions, options?: SearchTypeOptions & SourceRangeOptions) => Promise<GscdumpAnalysisSourcesResponse>;
289
- getSiteSyncStatus: (siteId: string, userId?: string) => Promise<GscdumpSyncStatusResponse>;
290
- getData: (siteId: string, state: BuilderStateWire, options?: DataQueryOptions) => Promise<GscdumpDataResponse>;
291
- getDataDetail: (siteId: string, state: BuilderStateWire, options?: DataDetailOptions) => Promise<GscdumpDataDetailResponse>;
292
- getSitemaps: (siteId: string) => Promise<GscdumpSitemapsResponse>;
293
- getSitemapChanges: (siteId: string, days?: number) => Promise<GscdumpSitemapChangesResponse>;
294
- getSitemapMembership: (siteId: string, params: GscdumpSitemapMembershipParams) => Promise<GscdumpSitemapMembershipResponse>;
295
- postSitemapAction: (siteId: string, action: PartnerSitemapAction) => Promise<PartnerSitemapActionResponse>;
296
- submitSitemap: (siteId: string, sitemapUrl: string, action?: 'submit' | 'delete') => Promise<Extract<PartnerSitemapActionResponse, {
297
- action: 'submitted' | 'deleted';
298
- }>>;
299
- refreshSitemaps: (siteId: string) => Promise<Extract<PartnerSitemapActionResponse, {
300
- action: 'refreshed';
301
- }>>;
302
- autoDiscoverSitemap: (siteId: string) => Promise<Extract<PartnerSitemapActionResponse, {
303
- action: 'auto-discover';
304
- }>>;
305
- getIndexing: (siteId: string, days?: number) => Promise<GscdumpIndexingResponse>;
306
- getIndexingUrls: (siteId: string, params?: IndexingUrlsParams) => Promise<GscdumpIndexingUrlsResponse>;
307
- getIndexingDiagnostics: (siteId: string, params?: IndexingDiagnosticsParams) => Promise<GscdumpIndexingDiagnosticsResponse>;
308
- requestIndexingInspect: (siteId: string, body: IndexingInspectRequest) => Promise<IndexingInspectResponse | IndexingInspectRateLimited>;
309
- getUserSettings: () => Promise<GscdumpUserSettings>;
310
- patchUserSettings: (body: Partial<GscdumpUserSettings>) => Promise<GscdumpUserSettings>;
311
- recoverPermission: (siteId: string) => Promise<GscdumpPermissionRecovery>;
312
- getTopAssociation: (siteId: string, params: GscdumpTopAssociationParams) => Promise<GscdumpTopAssociationResponse>;
313
- getKeywordSparklines: (siteId: string, params: GscdumpKeywordSparklinesParams) => Promise<GscdumpKeywordSparklinesResponse>;
314
- getQueryTrend: (siteId: string, params: GscdumpQueryTrendParams) => Promise<GscdumpQueryTrendResponse>;
315
- getPageTrend: (siteId: string, params: GscdumpPageTrendParams) => Promise<GscdumpPageTrendResponse>;
316
- getCanonicalMismatches: (siteId: string) => Promise<GscdumpCanonicalMismatchesResponse>;
317
- getIndexPercent: (siteId: string, params?: {
318
- invisibleLimit?: number;
319
- invisibleOffset?: number;
320
- orphanLimit?: number;
321
- }) => Promise<GscdumpIndexPercentResponse>;
322
- createTeam: (params: CreatePartnerTeamParams) => Promise<{
323
- team: GscdumpTeamRow;
324
- }>;
325
- renameTeam: (teamId: string, params: {
326
- name: string;
327
- }) => Promise<{
328
- ok: true;
329
- name: string;
330
- }>;
331
- deleteTeam: (teamId: string) => Promise<{
332
- ok: true;
333
- }>;
334
- listTeamMembers: (teamId: string) => Promise<{
335
- members: GscdumpTeamMemberRow[];
336
- }>;
337
- addTeamMember: (teamId: string, params: AddPartnerTeamMemberParams) => Promise<{
338
- ok: true;
339
- role: string;
340
- alreadyExisted?: boolean;
341
- }>;
342
- updateTeamMemberRole: (teamId: string, userId: string, params: {
343
- role: GscdumpTeamMemberRow['role'];
344
- }) => Promise<{
345
- ok: true;
346
- role: string;
347
- }>;
348
- removeTeamMember: (teamId: string, userId: string) => Promise<{
349
- ok: true;
350
- }>;
351
- bindSiteToTeam: (userId: string, siteId: string, params: BindPartnerSiteTeamParams) => Promise<{
352
- ok: true;
353
- teamId: string | null;
354
- }>;
355
- getTeamCatalog: (teamId: string) => Promise<GscdumpTeamCatalogRef>;
356
- bindTeamCatalog: (teamId: string, params: BindPartnerTeamCatalogParams) => Promise<BindPartnerTeamCatalogResponse>;
357
- }
358
- declare function createPartnerClient(options?: PartnerClientOptions): PartnerClient;
359
- declare const countryName: (code: string) => string;
360
- declare const CWV_GOOD_LCP = 2500;
361
- declare const CWV_POOR_LCP = 4000;
362
- declare const CWV_GOOD_INP = 200;
363
- declare const CWV_POOR_INP = 500;
364
- declare const CWV_GOOD_CLS = 0.1;
365
- declare const CWV_POOR_CLS = 0.25;
366
- type CwvBucket = 'good' | 'ni' | 'poor';
367
- declare function cwvBucket(metric: 'lcp' | 'inp' | 'cls', v: number): CwvBucket;
368
- /** Trim long query strings for table cells / chart tooltips. */
369
- declare function truncateQuery(q: string, max?: number): string;
370
- /** Best-effort extract a hostname; returns undefined if the URL is unparseable. */
371
- declare function siteUrlToHostname(url: string | undefined | null): string | undefined;
372
- interface GscConsoleUrlOpts {
373
- /** The GSC property — either `sc-domain:example.com` or a URL-prefix. */
374
- siteLabel: string;
375
- /** Optional page to open Performance drilldown for. */
376
- page?: string;
377
- /** Optional query filter. */
378
- query?: string;
379
- /** Resource: `performance`, `url-inspection`, `sitemaps`, … */
380
- resource?: 'performance' | 'url-inspection' | 'sitemaps' | 'index';
381
- }
382
- declare function gscConsoleUrl(opts: GscConsoleUrlOpts): string;
383
- /**
384
- * Google Search Console data is considered "unstable" for this many days from
385
- * today (PST). Rows within the window may still shift as GSC finalizes clicks/
386
- * impressions; charts render those points under a dimmed / striped overlay so
387
- * users don't misread last-day dips as trends.
388
- *
389
- * This is the client DISPLAY-latency band, NOT the server lake-membership
390
- * boundary. gscdump's `DEFAULT_STABILITY_CUTOFF_DAYS` (= 4) decides which days
391
- * live in the Iceberg lake vs the recent overlay; this constant (= 3) only dims
392
- * the UI. The display band is intentionally one day SMALLER so that, even at
393
- * maximum UTC-vs-PST clock skew, the freshest UI-requested day is lake-resident
394
- * (R2-SQL-complete) rather than overlay-only. The two are distinct concepts; do
395
- * not unify them to a single value (gscdump plan
396
- * `2026-06-24-overlay-canonical-merge-unification.md` W6).
397
- */
398
- declare const GSC_STABLE_LATENCY_DAYS = 3;
399
- type GscErrorStatus = 'auth-missing' | 'rate-limited' | 'network' | 'error';
400
- interface GscClassifiedError {
401
- status: GscErrorStatus;
402
- /** HTTP status code if the error came from a response, otherwise undefined. */
403
- code?: number;
404
- /** Best-effort human message: server-supplied `message`, then `data.message`, then the error's own message. */
405
- message?: string;
406
- /** Seconds the server suggested waiting (429/503 retry payloads). */
407
- retryAfter?: number;
408
- }
409
- declare function classifyGscError(e: unknown): GscClassifiedError;
410
- type RollingPeriod = '7d' | '28d' | '3m' | '6m' | '12m';
411
- type CalendarPeriod = 'this-week' | 'this-month' | 'last-month' | 'this-quarter' | 'this-year';
412
- /**
413
- * Custom date range from drag-to-zoom.
414
- * - `custom:CS:CE` - current range only; prev range resolved by compareMode.
415
- * - `custom:CS:CE:PS:PE` - explicit prev range.
416
- */
417
- type CustomPeriod = `custom:${string}:${string}` | `custom:${string}:${string}:${string}:${string}`;
418
- type Period = RollingPeriod | CalendarPeriod | CustomPeriod;
419
- type CompareMode = 'previous' | 'year' | 'none';
420
- interface DateRangeResult {
421
- start: string;
422
- end: string;
423
- prevStart: string;
424
- prevEnd: string;
425
- yearStart: string;
426
- yearEnd: string;
427
- days: number;
428
- }
429
- interface PeriodOptions {
430
- /** Subtract GSC's stable-data latency from `end`. Default `true`. */
431
- stableData?: boolean;
432
- /** IANA timezone used to resolve today's calendar date. Default GSC/Pacific time. */
433
- timezone?: string;
434
- /** Clock used to resolve today's calendar date. Defaults to the current time. */
435
- now?: Date;
436
- }
437
- declare function isCustomPeriod(p: Period | string): p is CustomPeriod;
438
- declare function parseCustomPeriod(p: Period | string): {
439
- start: string;
440
- end: string;
441
- prevStart?: string;
442
- prevEnd?: string;
443
- } | null;
444
- declare function periodToDateRange(period: Period | string, stableDataOrOptions?: boolean | PeriodOptions): DateRangeResult;
445
- declare function periodToDays(period: Period | string, stableDataOrOptions?: boolean | PeriodOptions): number;
446
- declare function compareRange(range: DateRangeResult, mode: CompareMode): {
447
- start: string;
448
- end: string;
449
- } | null;
450
- /**
451
- * GSC data within the last `GSC_STABLE_LATENCY_DAYS` (PST) is potentially
452
- * incomplete. Returns the cutoff date (YYYY-MM-DD); compare row dates against
453
- * this to dim/strike unstable points in charts.
454
- *
455
- * Uses YYYY-MM-DD string math directly to avoid UTC/local timezone shifts.
456
- */
457
- declare function getGscUnstableCutoffDate(): string;
458
- type GscColumn = 'clicks' | 'impressions' | 'ctr' | 'position';
459
- interface GscColumnOption {
460
- key: GscColumn;
461
- label: string;
462
- icon: string;
463
- color: string;
464
- }
465
- interface PeriodPreset {
466
- value: Period;
467
- label: string;
468
- shortLabel: string;
469
- group: 'rolling' | 'calendar';
470
- }
471
- declare const PERIOD_PRESETS: PeriodPreset[];
472
- declare const COMPARE_OPTIONS: {
473
- value: CompareMode;
474
- label: string;
475
- description: string;
476
- }[];
477
- declare const GSC_PERIOD_OPTIONS: {
478
- label: string;
479
- value: Period;
480
- longLabel: string;
481
- }[];
482
- declare const GSC_PERIOD_OPTIONS_LONG: {
483
- label: string;
484
- value: Period;
485
- }[];
486
- declare const GSC_COLUMN_OPTIONS: GscColumnOption[];
487
- interface RawDailyRow {
488
- date: string;
489
- clicks: number;
490
- impressions: number;
491
- sum_position?: number;
492
- position?: number;
493
- }
494
- interface CanonicalDailyRow {
495
- date: string;
496
- clicks: number;
497
- impressions: number;
498
- sum_position: number;
499
- }
500
- interface GscRowTotals {
501
- clicks: number;
502
- impressions: number;
503
- ctr: number;
504
- position: number;
505
- }
506
- interface GscDailySummary {
507
- daily: CanonicalDailyRow[];
508
- totals: GscRowTotals;
509
- chartData: Array<{
510
- date: string;
511
- clicks: number;
512
- impressions: number;
513
- }>;
514
- }
515
- /**
516
- * Fill `sum_position` from `(position - 1) * impressions` when the row only
517
- * carries `position`. GSC positions are 1-based and 0/absent is a no-data
518
- * sentinel — the old `Math.max(1, …)` clamp synthesized rank #1 (sum 0 with
519
- * full impression weight) for such rows instead of contributing nothing.
520
- */
521
- declare function coerceRowMetrics<T extends {
522
- impressions: number;
523
- sum_position?: number;
524
- position?: number;
525
- }>(row: T): T & {
526
- sum_position: number;
527
- };
528
- /** Sort daily rows by date asc, coerce `sum_position`, reduce totals, derive chartData. */
529
- declare function summarizeDailyRows(raw: readonly RawDailyRow[]): GscDailySummary;
530
- /**
531
- * Rollup-row position helper. `sum_position` is GSC's average-position sum
532
- * across impressions; dividing back out (+1 because GSC is 1-indexed) gives
533
- * the impression-weighted average position. Returns 0 when there were no
534
- * impressions so the column renders blank rather than NaN.
535
- */
536
- declare function positionFor(r: {
537
- impressions: number;
538
- sum_position: number;
539
- }): number;
540
- interface IndexingIssueDetail {
541
- description: string;
542
- fix: string;
543
- }
544
- type IssueSeverity = 'error' | 'warning' | 'info';
545
- interface IndexingIssue {
546
- type: string;
547
- label: string;
548
- severity: IssueSeverity;
549
- count: number;
550
- }
551
- declare const issueDetails: Record<string, IndexingIssueDetail>;
552
- declare const severityOrder: IssueSeverity[];
553
- interface IssueGroup {
554
- id: string;
555
- label: string;
556
- icon: string;
557
- description: string;
558
- /** How hard are these to fix? Shown as a badge */
559
- effort: 'quick' | 'moderate' | 'involved';
560
- /** Does the user have direct control over these? */
561
- controlLevel: 'full' | 'partial' | 'none';
562
- /** Educational explanation shown in the group header */
563
- education: string;
564
- /** Issue types belonging to this group */
565
- issueTypes: string[];
566
- }
567
- declare const issueGroups: IssueGroup[];
568
- /**
569
- * Stable lifecycle fields shared by the legacy partner response and public v1.
570
- * Keeping the adapters structural lets consumers migrate to v1 without
571
- * re-introducing legacy-only fields such as `intId` or `lifecycleRevision`.
572
- */
573
- type LifecycleSiteLike = Pick<PartnerLifecycleSite, 'siteId' | 'externalSiteId' | 'requestedUrl' | 'gscPropertyUrl' | 'permissionLevel' | 'analytics' | 'indexing' | 'latestError' | 'updatedAt'>;
574
- declare function analyticsStatusToSyncStatus(status: LifecycleSiteLike['analytics']['status']): GscdumpUserSite['syncStatus'];
575
- declare function lifecycleSiteToUserSite(site: LifecycleSiteLike): GscdumpUserSite;
576
- declare function lifecycleSiteToSyncStatus(site: LifecycleSiteLike): GscdumpSyncStatusResponse;
577
- declare function findLifecycleSite<TSite extends LifecycleSiteLike>(lifecycle: {
578
- sites: readonly TSite[];
579
- }, siteIdOrPropertyUrl: string): TSite | null;
580
- type SearchConsoleStageKey = 'not_connected' | 'waiting_for_data' | 'weak_discovery' | 'discovery_backlog' | 'crawl_blocked' | 'indexability_blocked' | 'index_rejection' | 'partially_indexed' | 'indexed_invisible' | 'visible_not_clicked' | 'ranking_stalled' | 'declining_visibility' | 'healthy_growth_ready';
581
- type SearchConsoleStageSeverity = 'success' | 'error' | 'warning' | 'info' | 'neutral';
582
- interface SearchConsoleStageEvidence {
583
- label: string;
584
- value: string;
585
- source: 'connection' | 'indexing' | 'sitemap' | 'performance' | 'inspection' | 'canonical';
586
- }
587
- interface SearchConsoleStage {
588
- key: SearchConsoleStageKey;
589
- label: string;
590
- severity: SearchConsoleStageSeverity;
591
- summary: string;
592
- primaryAction: string;
593
- nextStage: SearchConsoleStageKey | null;
594
- evidence: SearchConsoleStageEvidence[];
595
- sprintFindingTypes: string[];
596
- }
597
- interface SearchConsoleStageIssue {
598
- type: string;
599
- label: string;
600
- severity?: 'error' | 'warning' | 'info';
601
- count: number;
602
- }
603
- interface SearchConsoleStageSummary {
604
- totalUrls: number;
605
- indexed: number;
606
- indexedPercent: number;
607
- change7d?: number | null;
608
- change28d?: number | null;
609
- }
610
- /**
611
- * Trajectory + maturity signals (v2). These are first-class axes: a site that
612
- * is growing over the robust 90-day window is told to keep expanding, never to
613
- * "fix indexing", regardless of coverage%. Percent fields are whole numbers
614
- * (e.g. 42.6 for +42.6%); `positionDelta90d` is current − prior (negative =
615
- * rank improved). Window contract: callers MUST drop the trailing ~3 GSC lag
616
- * days before computing these, and the 7-day window is intentionally absent —
617
- * it is too lag-contaminated to classify on.
618
- */
619
- interface SearchConsoleStageTrajectory {
620
- clicksPct90d?: number | null;
621
- impressionsPct90d?: number | null;
622
- positionDelta90d?: number | null;
623
- clicksPct28d?: number | null;
624
- /**
625
- * Absolute clicks in the PRIOR 28-day window — the baseline a decline would
626
- * be measured against. Gates decline detection so a percentage crash on
627
- * trivial traffic (8 → 2 clicks) is not mistaken for a real loss.
628
- */
629
- clicksPrior28d?: number | null;
630
- }
631
- interface SearchConsoleStageSitemap {
632
- errors?: number | null;
633
- warnings?: number | null;
634
- lastError?: string | null;
635
- urlCount?: number | null;
636
- }
637
- interface SearchConsoleStagePage {
638
- impressions: number;
639
- clicks: number;
640
- position?: number | null;
641
- }
642
- interface ClassifySearchConsoleStageInput {
643
- connected: boolean;
644
- indexingStatus?: 'pending' | 'partial' | 'complete' | 'unknown' | string | null;
645
- summary?: SearchConsoleStageSummary | null;
646
- issues?: SearchConsoleStageIssue[] | null;
647
- sitemaps?: SearchConsoleStageSitemap[] | null;
648
- canonicalMismatchCount?: number | null;
649
- pageInventory?: SearchConsoleStagePage[] | null;
650
- ctrOutlierCount?: number | null;
651
- pageMoverDropCount?: number | null;
652
- /** v2 trajectory axis — when present, drives the growth override + decline detection. */
653
- trajectory?: SearchConsoleStageTrajectory | null;
654
- /** v2 maturity axis — impressions over the trailing 28 days. Gates whether coverage% is even meaningful. */
655
- impressions28d?: number | null;
656
- /**
657
- * v2 on-page technical faults from the crawl audit (broken links/images,
658
- * server errors, access failures) — counted as hard blockers alongside GSC
659
- * crawl reasons. Excludes intentional noindex.
660
- */
661
- crawlAuditBlockerCount?: number | null;
662
- /** v2 authority signal — open recoverable broken backlinks (expansion lever, not a defect). */
663
- recoverableBacklinkCount?: number | null;
664
- /** v2 authority signal — cross-competitor content-gap topics (expansion readiness). */
665
- competitorGapCount?: number | null;
666
- /**
667
- * v2 site purpose (AI profile `type`). Benchmarks the verdict against intent:
668
- * informational types (docs/blog/portfolio) earn structurally low CTR, so the
669
- * visible-not-clicked bar is raised for them. Unknown/null → `other`.
670
- */
671
- siteType?: string | null;
672
- }
673
- /**
674
- * v2 classifier. Trajectory and maturity are first-class axes that run BEFORE
675
- * the coverage/discovery rungs, so a growing site is told to keep expanding —
676
- * never to "fix indexing". Reuses the existing stage-key enum (growth →
677
- * `healthy_growth_ready`, nascent → `waiting_for_data`, mass crawled-not-indexed
678
- * → `index_rejection`, on-page/crawl faults → `crawl_blocked`).
679
- */
680
- declare function classifySearchConsoleStage(input: ClassifySearchConsoleStageInput): SearchConsoleStage;
681
- type SiteType = 'saas' | 'ecommerce' | 'docs' | 'blog' | 'agency' | 'portfolio' | 'other';
682
- /**
683
- * Normalise the AI profile `type` to the closed enum. The categoriser mostly
684
- * emits the 7 values but occasionally leaks free-text (e.g. "event") or null
685
- * (~40% of live sites are unprofiled) — everything unknown collapses to `other`
686
- * so downstream logic always has a defined bucket.
687
- */
688
- declare function normalizeSiteType(raw: string | null | undefined): SiteType;
689
- interface SiteTypeBaseline {
690
- label: string;
691
- /**
692
- * Whether indexed-coverage% is a meaningful health signal for this type.
693
- * docs/blog/portfolio accumulate intentional low-value pages (tags, versions,
694
- * pagination, archives) so coverage% is noise; ecommerce/saas/agency care.
695
- */
696
- coverageMatters: boolean;
697
- /**
698
- * Typical click-through at good positions. Informational types (docs/blog)
699
- * earn structurally lower CTR (answer shown in SERP, multi-page research), so
700
- * a low CTR is NOT a defect — the classifier raises the visible-not-clicked
701
- * bar for these.
702
- */
703
- ctrExpectation: 'low' | 'medium' | 'high';
704
- /** The default growth lever when the site is healthy and leading. */
705
- primaryGoal: 'content' | 'authority' | 'conversion' | 'coverage';
706
- }
707
- declare const SITE_TYPE_BASELINE: Record<SiteType, SiteTypeBaseline>;
708
- declare function siteTypeBaseline(raw: string | null | undefined): SiteTypeBaseline;
709
- type PeerStanding = 'leader' | 'on_par' | 'behind' | 'unknown';
710
- /** How much to trust the standing: a median over 1–2 peers is noisy. */
711
- type PeerConfidence = 'high' | 'low' | 'none';
712
- /**
713
- * Peer metrics from tracked competitors (`siteCompetitors`). Domain rank is the
714
- * DataForSEO-derived 0–100 score (`min(100, log10(keywordCount)*20)`), NOT a
715
- * true authority metric — good enough for relative standing within a peer set.
716
- * The site's OWN metrics are not stored alongside competitors, so callers must
717
- * supply them (one cheap cached `estimateDomainTraffic` call).
718
- */
719
- interface PeerBaselineInput {
720
- siteDomainRank?: number | null;
721
- siteOrganicTraffic?: number | null;
722
- competitorDomainRanks?: number[] | null;
723
- competitorOrganicTraffic?: number[] | null;
724
- }
725
- interface SiteBaseline {
726
- siteType: SiteType;
727
- baseline: SiteTypeBaseline;
728
- peerStanding: PeerStanding;
729
- peerConfidence: PeerConfidence;
730
- peerMedianDomainRank: number | null;
731
- peerMedianOrganicTraffic: number | null;
732
- /** Human-facing goal headline combining type + standing. */
733
- recommendedGoal: string;
734
- goalKind: SiteTypeBaseline['primaryGoal'];
735
- }
736
- /** Standing is decided on domain rank first; organic traffic breaks the tie. */
737
- declare function derivePeerStanding(input: PeerBaselineInput): {
738
- standing: PeerStanding;
739
- confidence: PeerConfidence;
740
- peerMedianDomainRank: number | null;
741
- peerMedianOrganicTraffic: number | null;
742
- };
743
- /**
744
- * Combine the site type with its peer standing into a relative goal. A leader
745
- * defends and expands on its type's lever; a site that's behind closes the gap
746
- * on the same lever; unknown standing falls back to the type default.
747
- */
748
- declare function deriveSiteBaseline(rawType: string | null | undefined, peer?: PeerBaselineInput): SiteBaseline;
749
- type ReachStage = 'waiting_for_data' | 'emerging' | 'growing' | 'plateaued' | 'declining' | 'faded' | 'decayed';
750
- type HealthStage = 'healthy' | 'crawl_faults' | 'quality_rejection';
751
- interface TriageEvidence {
752
- label: string;
753
- value: string;
754
- }
755
- /**
756
- * Distance-to-next-stage for one axis, so the UI never re-derives thresholds.
757
- *
758
- * `direction`:
759
- * - `advance` — up-path rung (waiting → emerging → growing). `pct` = value/target.
760
- * - `escape` — off-ramp recovery (declining/faded/decayed) or a held health gate
761
- * (crawl_faults/quality_rejection). `pct` = inverse distance: closer to passing ⇒ higher.
762
- * - `sustain` — already good (growing/healthy). `nextStage` null, `pct` 1, framed as momentum.
763
- *
764
- * `gapLabel` is always a concrete count (pages/clicks/points), never a bare %.
765
- */
766
- interface StageProgression {
767
- nextStage: ReachStage | HealthStage | null;
768
- metric: string;
769
- value: number;
770
- target: number;
771
- pct: number;
772
- gapLabel: string;
773
- direction: 'advance' | 'escape' | 'sustain';
774
- }
775
- interface ReachVerdict {
776
- stage: ReachStage;
777
- summary: string;
778
- primaryAction: string;
779
- evidence: TriageEvidence[];
780
- progression: StageProgression;
781
- }
782
- interface HealthVerdict {
783
- stage: HealthStage;
784
- summary: string;
785
- primaryAction: string;
786
- evidence: TriageEvidence[];
787
- progression: StageProgression;
788
- }
789
- interface SiteTriage {
790
- reach: ReachVerdict;
791
- health: HealthVerdict;
792
- /** Which axis leads the dashboard headline. */
793
- headline: 'reach' | 'health';
794
- }
795
- interface SiteTriageInput {
796
- connected: boolean;
797
- /** Impressions over the trailing 28 days — the maturity tier. */
798
- impressions28d?: number | null;
799
- /** Lifetime-ish impressions (trailing 12 months) — separates new from decayed/faded. */
800
- impressions12m?: number | null;
801
- /** Absolute clicks over the trailing 28 days — for the clicks≪impressions decay tell. */
802
- clicks28d?: number | null;
803
- clicksPct90d?: number | null;
804
- clicksPct28d?: number | null;
805
- /** Absolute prior-28d clicks — gates decline so a % crash on trivial traffic isn't a false decline. */
806
- clicksPrior28d?: number | null;
807
- impressionsPct90d?: number | null;
808
- positionDelta90d?: number | null;
809
- /** Latest complete week ÷ 90d peak week (lag-trimmed). <0.2 = faded (spike→died). */
810
- livenessRatio?: number | null;
811
- totalUrls?: number | null;
812
- indexed?: number | null;
813
- issues?: SearchConsoleStageIssue[] | null;
814
- /** Real on-page faults from the crawl audit: 5xx, broken internal links/images. Excludes intentional noindex/404. */
815
- crawlAuditBlockerCount?: number | null;
816
- /** AI profile type — drives purpose-expected subtraction. */
817
- siteType?: string | null;
818
- }
819
- /**
820
- * Reach liveness: latest complete week ÷ peak rolling-7d week over a daily
821
- * impressions series (typically the trailing 90 days). `<0.2` means recent
822
- * impressions have collapsed versus the site's own peak (spike→died) — the
823
- * signal a period-vs-prior delta cannot see. Trailing zero-impression days
824
- * (GSC reporting lag) are trimmed before the latest-week sum. Returns null when
825
- * the series is too short to judge.
826
- */
827
- declare function reachLivenessRatio(daily: Array<{
828
- impressions: number;
829
- }> | null | undefined): number | null;
830
- declare function classifyHealthStage(input: SiteTriageInput): HealthVerdict;
831
- declare function classifyReachStage(input: SiteTriageInput): ReachVerdict;
832
- declare function classifySiteTriage(input: SiteTriageInput): SiteTriage;
833
- declare function verifyWebhookSignature(payload: string | object, signature: string | null | undefined, secret: string): Promise<boolean>;
834
- /**
835
- * Errors-as-values core for {@link parseWebhookPayload}: a failed HMAC signature
836
- * check is a caller-actionable `auth` (401) failure at the webhook boundary, so
837
- * it is returned as a modelled `PartnerApiError` rather than only thrown. A
838
- * malformed envelope (schema parse) is a defect and keeps propagating.
839
- */
840
- declare function parseWebhookPayloadResult<TData extends Record<string, unknown> = Record<string, unknown>>(payload: string | object, options?: {
841
- secret?: string;
842
- signature?: string | null;
843
- headers?: PartnerWebhookHeaders | Headers;
844
- validateSignature?: boolean;
845
- }): Promise<Result<WebhookEnvelope<TData>, PartnerApiError>>;
846
- declare function parseWebhookPayload<TData extends Record<string, unknown> = Record<string, unknown>>(payload: string | object, options?: {
847
- secret?: string;
848
- signature?: string | null;
849
- headers?: PartnerWebhookHeaders | Headers;
850
- validateSignature?: boolean;
851
- }): Promise<WebhookEnvelope<TData>>;
852
- declare function readWebhookHeaders(headers: Headers | PartnerWebhookHeaders | null | undefined): Required<PartnerWebhookHeaders>;
1
+ import { AnalysisSourcesOptions, DEFAULT_SEARCH_TYPE, SearchTypeOptions, SourceRangeOptions, dateRangeOptionsQuery, searchTypeQuery, sourceInfoQuery, tablesQuery, withDefaultSearchType } from "./hosted-query.mjs";
2
+ import { PartnerApiError, PartnerErrorInfo, PartnerErrorKind, partnerErrorToException, toPartnerError } from "./_chunks/errors.mjs";
3
+ import { AnalyticsClient, AnalyticsClientOptions, AnalyticsFetch, AnalyticsFetchOptions, AnalyticsHeaders, createAnalyticsClient } from "./analytics-client.mjs";
4
+ import { GscAnalyzerAccent, GscAnalyzerCapabilities, GscAnalyzerCapability, GscAnalyzerDefinition, GscAnalyzerDefinitionWithCapability, GscAnalyzerInsightCard, GscAnalyzerKind, GscAnalyzerPanelResult, GscAnalyzerPanelSpec, GscAnalyzerStatTile, defineGscAnalyzer } from "./analyzer-defs.mjs";
5
+ import { DailyAnonInput, weightedAnonPct } from "./anonymization.mjs";
6
+ import { BuilderStateToArchetypeOptions, archetypeSeamSupportsQuery, builderStateToArchetype, extractWireDateRange } from "./archetype-compile.mjs";
7
+ import { PartnerClient, PartnerClientOptions, PartnerFetch, PartnerFetchOptions, PartnerHeaders, createPartnerClient } from "./client.mjs";
8
+ import { countryName } from "./country-names.mjs";
9
+ import { CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, CwvBucket, cwvBucket, siteUrlToHostname, truncateQuery } from "./cwv-thresholds.mjs";
10
+ import { GscConsoleUrlOpts, gscConsoleUrl } from "./gsc-console-url.mjs";
11
+ import { GSC_STABLE_LATENCY_DAYS } from "./gsc-constants.mjs";
12
+ import { GscClassifiedError, GscErrorStatus, classifyGscError } from "./gsc-error.mjs";
13
+ import { CalendarPeriod, CompareMode, CustomPeriod, DateRangeResult, Period, PeriodOptions, RollingPeriod, compareRange, getGscUnstableCutoffDate, isCustomPeriod, parseCustomPeriod, periodToDateRange, periodToDays } from "./period.mjs";
14
+ import { COMPARE_OPTIONS, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GscColumn, GscColumnOption, PERIOD_PRESETS, PeriodPreset } from "./gsc-period-presets.mjs";
15
+ import { CanonicalDailyRow, GscDailySummary, GscRowTotals, RawDailyRow, coerceRowMetrics, positionFor, summarizeDailyRows } from "./gsc-rows.mjs";
16
+ import { IndexingIssue, IndexingIssueDetail, IssueGroup, IssueSeverity, issueDetails, issueGroups, severityOrder } from "./indexing-issues.mjs";
17
+ import { LifecycleSiteLike, analyticsStatusToSyncStatus, findLifecycleSite, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite } from "./lifecycle.mjs";
18
+ import { ClassifySearchConsoleStageInput, SearchConsoleStage, SearchConsoleStageEvidence, SearchConsoleStageIssue, SearchConsoleStageKey, SearchConsoleStagePage, SearchConsoleStageSeverity, SearchConsoleStageSitemap, SearchConsoleStageSummary, SearchConsoleStageTrajectory, classifySearchConsoleStage } from "./search-console-stage.mjs";
19
+ import { PeerBaselineInput, PeerConfidence, PeerStanding, SITE_TYPE_BASELINE, SiteBaseline, SiteType, SiteTypeBaseline, derivePeerStanding, deriveSiteBaseline, normalizeSiteType, siteTypeBaseline } from "./site-baseline.mjs";
20
+ import { HealthStage, HealthVerdict, ReachStage, ReachVerdict, SiteTriage, SiteTriageInput, TriageEvidence, classifyHealthStage, classifyReachStage, classifySiteTriage, reachLivenessRatio } from "./site-triage.mjs";
21
+ import { CANONICAL_WEBHOOK_EVENTS, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, parseWebhookPayload, parseWebhookPayloadResult, readWebhookHeaders, verifyWebhookSignature } from "./webhook.mjs";
853
22
  export { type AnalysisSourcesOptions, type AnalyticsClient, type AnalyticsClientOptions, type AnalyticsFetch, type AnalyticsFetchOptions, type AnalyticsHeaders, type BuilderStateToArchetypeOptions, CANONICAL_WEBHOOK_EVENTS, COMPARE_OPTIONS, CWV_GOOD_CLS, CWV_GOOD_INP, CWV_GOOD_LCP, CWV_POOR_CLS, CWV_POOR_INP, CWV_POOR_LCP, type CalendarPeriod, type CanonicalDailyRow, type ClassifySearchConsoleStageInput, type CompareMode, type CustomPeriod, type CwvBucket, DEFAULT_SEARCH_TYPE, type DailyAnonInput, type DateRangeResult, GSC_COLUMN_OPTIONS, GSC_PERIOD_OPTIONS, GSC_PERIOD_OPTIONS_LONG, GSC_STABLE_LATENCY_DAYS, type GscAnalyzerAccent, type GscAnalyzerCapabilities, type GscAnalyzerCapability, type GscAnalyzerDefinition, type GscAnalyzerDefinitionWithCapability, type GscAnalyzerInsightCard, type GscAnalyzerKind, type GscAnalyzerPanelResult, type GscAnalyzerPanelSpec, type GscAnalyzerStatTile, type GscClassifiedError, type GscColumn, type GscColumnOption, type GscConsoleUrlOpts, type GscDailySummary, type GscErrorStatus, type GscRowTotals, type HealthStage, type HealthVerdict, type IndexingIssue, type IndexingIssueDetail, type IssueGroup, type IssueSeverity, type LifecycleSiteLike, PERIOD_PRESETS, PartnerApiError, type PartnerClient, type PartnerClientOptions, type PartnerErrorInfo, type PartnerErrorKind, type PartnerFetch, type PartnerFetchOptions, type PartnerHeaders, type PeerBaselineInput, type PeerConfidence, type PeerStanding, type Period, type PeriodOptions, type PeriodPreset, type RawDailyRow, type ReachStage, type ReachVerdict, type RollingPeriod, SITE_TYPE_BASELINE, type SearchConsoleStage, type SearchConsoleStageEvidence, type SearchConsoleStageIssue, type SearchConsoleStageKey, type SearchConsoleStagePage, type SearchConsoleStageSeverity, type SearchConsoleStageSitemap, type SearchConsoleStageSummary, type SearchConsoleStageTrajectory, type SearchTypeOptions, type SiteBaseline, type SiteTriage, type SiteTriageInput, type SiteType, type SiteTypeBaseline, type SourceRangeOptions, type TriageEvidence, VALID_WEBHOOK_EVENTS, WEBHOOK_CONTRACT_VERSION, WEBHOOK_CONTRACT_VERSION_HEADER, WEBHOOK_DELIVERY_HEADER, WEBHOOK_EVENT_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, analyticsStatusToSyncStatus, archetypeSeamSupportsQuery, builderStateToArchetype, classifyGscError, classifyHealthStage, classifyReachStage, classifySearchConsoleStage, classifySiteTriage, coerceRowMetrics, compareRange, countryName, createAnalyticsClient, createPartnerClient, cwvBucket, dateRangeOptionsQuery, defineGscAnalyzer, derivePeerStanding, deriveSiteBaseline, extractWireDateRange, findLifecycleSite, getGscUnstableCutoffDate, gscConsoleUrl, isCustomPeriod, issueDetails, issueGroups, lifecycleSiteToSyncStatus, lifecycleSiteToUserSite, normalizeSiteType, parseCustomPeriod, parseWebhookPayload, parseWebhookPayloadResult, partnerErrorToException, periodToDateRange, periodToDays, positionFor, reachLivenessRatio, readWebhookHeaders, searchTypeQuery, severityOrder, siteTypeBaseline, siteUrlToHostname, sourceInfoQuery, summarizeDailyRows, tablesQuery, toPartnerError, truncateQuery, verifyWebhookSignature, weightedAnonPct, withDefaultSearchType };