@gscdump/contracts 5.5.0 → 5.7.0

package/dist/v1/operations.mjs

@@ -1,6 +1,7 @@
 import { siteHoldReasonSchema } from "../entitlements.mjs";
 import { watchedUrlsChangeRequestSchema, watchedUrlsChangeResponseSchema, watchedUrlsResponseSchema } from "../indexing-coverage.mjs";
-import { addPartnerTeamMemberSchema, bindPartnerSiteTeamSchema, bindPartnerTeamCatalogResponseSchema, bindPartnerTeamCatalogSchema, builderStateSchema, createPartnerTeamSchema, gscComparisonFilterSchema, gscdumpAnalysisBundleResponseSchema, gscdumpAnalysisPresetSchema, gscdumpAnalysisResponseSchema, gscdumpAvailableSiteSchema, gscdumpCanonicalMismatchesResponseSchema, gscdumpDataDetailResponseSchema, gscdumpDataResponseSchema, gscdumpDeletePartnerUserResponseSchema, gscdumpIndexPercentResponseSchema, gscdumpIndexingDiagnosticsResponseSchema, gscdumpIndexingResponseSchema, gscdumpIndexingTransitionFieldSchema, gscdumpKeywordSparklinesResponseSchema, gscdumpPageTrendResponseSchema, gscdumpQueryTrendResponseSchema, gscdumpSiteRegistrationSchema, gscdumpSitemapChangesResponseSchema, gscdumpSitemapExportQuerySchema, gscdumpSitemapExportResponseSchema, gscdumpSitemapMembershipParamsSchema, gscdumpSitemapMembershipResponseSchema, gscdumpSitemapUrlsQuerySchema, gscdumpSitemapUrlsResponseSchema, gscdumpSitemapsResponseSchema, gscdumpTeamRoleSchema, gscdumpTopAssociationResponseSchema, gscdumpUserRegistrationSchema, indexingUrlsResponseSchema, partnerSiteTeamBindingResponseSchema, partnerSitemapActionResponseSchema, partnerSitemapActionSchema, partnerTeamCreatedResponseSchema, partnerTeamDeletedResponseSchema, partnerTeamMemberAddedResponseSchema, partnerTeamMemberRemovedResponseSchema, partnerTeamMemberRoleResponseSchema, partnerTeamMembersResponseSchema, partnerTeamRenamedResponseSchema, registerPartnerSiteSchema, registerPartnerUserSchema, renamePartnerTeamSchema, searchTypeSchema, siteIntIdCrosswalkResponseSchema, sitemapChangesTruncationReasonSchema, teamCatalogRefSchema, updatePartnerUserTokensSchema } from "../schemas.mjs";
+import { addPartnerTeamMemberSchema, bindPartnerSiteTeamSchema, bindPartnerTeamCatalogResponseSchema, bindPartnerTeamCatalogSchema, builderStateSchema, createPartnerTeamSchema, gscComparisonFilterSchema, gscComparisonOrderBySchema, gscdumpAnalysisBundleResponseSchema, gscdumpAnalysisPresetSchema, gscdumpAnalysisResponseSchema, gscdumpAvailableSiteSchema, gscdumpCanonicalMismatchesResponseSchema, gscdumpDataDetailResponseSchema, gscdumpDataResponseSchema, gscdumpDeletePartnerUserResponseSchema, gscdumpIndexPercentResponseSchema, gscdumpIndexingDiagnosticsResponseSchema, gscdumpIndexingResponseSchema, gscdumpIndexingTransitionFieldSchema, gscdumpKeywordSparklinesResponseSchema, gscdumpPageTrendResponseSchema, gscdumpQueryTrendResponseSchema, gscdumpSiteRegistrationSchema, gscdumpSitemapChangesResponseSchema, gscdumpSitemapExportQuerySchema, gscdumpSitemapExportResponseSchema, gscdumpSitemapMembershipParamsSchema, gscdumpSitemapMembershipResponseSchema, gscdumpSitemapUrlsQuerySchema, gscdumpSitemapUrlsResponseSchema, gscdumpSitemapsResponseSchema, gscdumpTeamRoleSchema, gscdumpTopAssociationResponseSchema, gscdumpUserRegistrationSchema, indexingUrlsResponseSchema, partnerSiteTeamBindingResponseSchema, partnerSitemapActionResponseSchema, partnerSitemapActionSchema, partnerTeamCreatedResponseSchema, partnerTeamDeletedResponseSchema, partnerTeamMemberAddedResponseSchema, partnerTeamMemberRemovedResponseSchema, partnerTeamMemberRoleResponseSchema, partnerTeamMembersResponseSchema, partnerTeamRenamedResponseSchema, registerPartnerSiteSchema, registerPartnerUserSchema, renamePartnerTeamSchema, searchTypeSchema, siteIntIdCrosswalkResponseSchema, sitemapChangesTruncationReasonSchema, teamCatalogRefSchema, updatePartnerUserTokensSchema } from "../schemas.mjs";
+import { siteVersionBeginRequestSchema, siteVersionCandidateRequestSchema, siteVersionCandidateSchema, siteVersionIdentityResponseSchema, siteVersionPreviewRequestSchema, siteVersionPreviewSchema } from "../site-version.mjs";
 import "./version.mjs";
 import { HTTP_V1_ERROR_CODES, defineHttpOperation, defineHttpSurface, defineResponseObject, defineSuccessResponse } from "./http-core.mjs";
 import { analyticsCoverageQueryV1Schema, analyticsCoverageV1Schemas } from "./analytics-coverage.mjs";
@@ -85,7 +86,11 @@ function createGscdumpV1Protocol() {
 	const analyticsReportRequest = z.strictObject({
 		state: analyticsListReportState,
 		comparison: analyticsListReportState.optional(),
-		filter: gscComparisonFilterSchema.optional()
+		filter: gscComparisonFilterSchema.optional(),
+		comparisonOrderBy: gscComparisonOrderBySchema.optional()
+	}).refine((request) => request.comparisonOrderBy === void 0 || request.comparison !== void 0, {
+		message: "comparisonOrderBy requires a comparison window.",
+		path: ["comparisonOrderBy"]
 	});
 	const analyticsReportDetailRequest = z.strictObject({
 		state: analyticsDetailReportState,
@@ -778,6 +783,63 @@ function createGscdumpV1Protocol() {
 		"internal_error",
 		"contract_violation"
 	];
+	const siteVersionErrors = [
+		...partnerSiteErrors,
+		"conflict",
+		"service_unavailable"
+	];
+	const siteVersionIdentityResponse = defineSuccessResponse({
+		producer: siteVersionIdentityResponseSchema,
+		client: siteVersionIdentityResponseSchema
+	}, partnerResponseMeta);
+	const siteVersionPreviewResponse = defineSuccessResponse({
+		producer: siteVersionPreviewSchema,
+		client: siteVersionPreviewSchema
+	}, partnerResponseMeta);
+	const siteVersionCandidateResponse = defineSuccessResponse({
+		producer: siteVersionCandidateSchema,
+		client: siteVersionCandidateSchema
+	}, partnerResponseMeta);
+	const siteVersionExampleIdentity = {
+		siteId: "s_01",
+		userId: "u_01",
+		teamId: "t_01",
+		requestedUrl: "https://example.com/",
+		catalogSiteId: 17,
+		warehouse: "team_catalog",
+		namespace: "gsc",
+		version: 0,
+		revision: 1,
+		catalogRevision: 1,
+		dataVersion: 1
+	};
+	const siteVersionExamplePreview = {
+		_tag: "eligible",
+		identity: siteVersionExampleIdentity,
+		requestedUrl: "https://www.example.com/",
+		window: {
+			startDate: "2026-09-05",
+			endDate: "2026-10-02"
+		},
+		requiredSlices: [{
+			table: "dates",
+			searchType: "web"
+		}],
+		candidateNamespace: "gsc_v1",
+		candidateVersion: 1
+	};
+	const siteVersionExampleCandidate = {
+		version: 1,
+		namespace: "gsc_v1",
+		requestedUrl: "https://www.example.com/",
+		window: siteVersionExamplePreview.window,
+		requiredSlices: siteVersionExamplePreview.requiredSlices
+	};
+	const siteVersionExampleMeta = {
+		requestId: "req_01",
+		surface: "partner",
+		version: "1.0"
+	};
 	const partnerUserErrors = [
 		"invalid_request",
 		"unauthorized",
@@ -5799,6 +5861,421 @@ function createGscdumpV1Protocol() {
 						}
 					}
 				}
+			}),
+			getRegisteredHostIdentity: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.identity.get"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:read"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: siteVersionIdentityResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Get registered host identity",
+					description: "Returns the authorized Site version and its effective Team Catalog binding.",
+					tags: ["Sites"],
+					examples: {
+						request: { params: { siteId: "s_01" } },
+						response: {
+							data: {
+								identity: siteVersionExampleIdentity,
+								coverage: { _tag: "legacy" }
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			previewRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.preview"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:read"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionPreviewRequestSchema
+				},
+				responses: { 200: siteVersionPreviewResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Preview registered host correction",
+					description: "Checks exact-host correction eligibility without creating resources or changing the Site.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: {
+								requestedUrl: siteVersionExamplePreview.requestedUrl,
+								catalogSiteId: 17,
+								window: siteVersionExamplePreview.window
+							}
+						},
+						response: {
+							data: siteVersionExamplePreview,
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			beginRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.begin"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: false,
+					retry: "never",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionBeginRequestSchema
+				},
+				responses: { 200: siteVersionCandidateResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.lifecycle",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Begin registered host correction",
+					description: "Reserves an isolated candidate. Current registration and current reads keep their existing version.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: { preview: siteVersionExamplePreview }
+						},
+						response: {
+							data: {
+								...siteVersionExampleCandidate,
+								state: "collecting"
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			verifyRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.verify"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionCandidateRequestSchema
+				},
+				responses: { 200: siteVersionCandidateResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.analytics",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.lifecycle",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Verify registered host correction",
+					description: "Requires completed Google collection and matching physical coverage for every required slice.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: {
+								version: 1,
+								identity: siteVersionExampleIdentity
+							}
+						},
+						response: {
+							data: {
+								...siteVersionExampleCandidate,
+								state: "verified"
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			promoteRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.promote"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionCandidateRequestSchema
+				},
+				responses: { 200: siteVersionCandidateResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}, {
+						type: "site.analytics",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Promote registered host correction",
+					description: "Atomically promotes a verified candidate while preserving Source and Catalog identities.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: {
+								version: 1,
+								identity: siteVersionExampleIdentity
+							}
+						},
+						response: {
+							data: {
+								...siteVersionExampleCandidate,
+								state: "active"
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			abortRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.abort"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionCandidateRequestSchema
+				},
+				responses: { 200: siteVersionCandidateResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.lifecycle",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Abort registered host correction",
+					description: "Excludes the candidate. Historical tables and the active Site version remain preserved.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: {
+								version: 1,
+								identity: siteVersionExampleIdentity
+							}
+						},
+						response: {
+							data: {
+								...siteVersionExampleCandidate,
+								state: "aborted"
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
+			}),
+			rollbackRegisteredHost: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.registered_host.rollback"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["sites:write"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: siteVersionCandidateRequestSchema
+				},
+				responses: { 200: siteVersionCandidateResponse },
+				errors: siteVersionErrors,
+				errorResponse: errorEnvelopeSchemas(siteVersionErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.registration",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.lifecycle",
+						idFrom: "params.siteId"
+					}, {
+						type: "site.analytics",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "5.6.0" },
+				docs: {
+					summary: "Roll back registered host correction",
+					description: "Suspends current analytics for the promoted version. The registered host and collected history remain preserved.",
+					tags: ["Sites"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: {
+								version: 1,
+								identity: {
+									...siteVersionExampleIdentity,
+									requestedUrl: siteVersionExampleCandidate.requestedUrl,
+									namespace: siteVersionExampleCandidate.namespace,
+									version: 1,
+									revision: 2
+								}
+							}
+						},
+						response: {
+							data: {
+								...siteVersionExampleCandidate,
+								state: "aborted"
+							},
+							meta: siteVersionExampleMeta
+						}
+					}
+				}
 			})
 		}
 	});

package/dist/v1/route-catalog.d.mts

@@ -16,6 +16,41 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
     };
   };
   readonly operations: {
+    readonly 'partner.sites.registered_host.identity.get': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/sites/{siteId}/registered-host";
+    };
+    readonly 'partner.sites.registered_host.preview': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/preview";
+    };
+    readonly 'partner.sites.registered_host.begin': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/begin";
+    };
+    readonly 'partner.sites.registered_host.verify': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/verify";
+    };
+    readonly 'partner.sites.registered_host.promote': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/promote";
+    };
+    readonly 'partner.sites.registered_host.abort': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/abort";
+    };
+    readonly 'partner.sites.registered_host.rollback': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/registered-host/rollback";
+    };
     readonly 'partner.sites.analytics.coverage.get': {
       readonly surface: "partner";
       readonly method: "GET";

package/dist/v1/route-catalog.mjs

@@ -3,6 +3,41 @@ import { GSCDUMP_V1_ROUTE_SURFACES } from "./route-surfaces.mjs";
 const GSCDUMP_V1_ROUTE_CATALOG = {
 	surfaces: GSCDUMP_V1_ROUTE_SURFACES,
 	operations: {
+		"partner.sites.registered_host.identity.get": {
+			surface: "partner",
+			method: "GET",
+			template: "/sites/{siteId}/registered-host"
+		},
+		"partner.sites.registered_host.preview": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/preview"
+		},
+		"partner.sites.registered_host.begin": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/begin"
+		},
+		"partner.sites.registered_host.verify": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/verify"
+		},
+		"partner.sites.registered_host.promote": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/promote"
+		},
+		"partner.sites.registered_host.abort": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/abort"
+		},
+		"partner.sites.registered_host.rollback": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/registered-host/rollback"
+		},
 		"partner.sites.analytics.coverage.get": {
 			surface: "partner",
 			method: "GET",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/contracts",
   "type": "module",
-  "version": "5.5.0",
+  "version": "5.7.0",
   "description": "Shared gscdump.com API, webhook, realtime, and lifecycle contracts.",
   "author": {
     "name": "Harlan Wilton",