@gscdump/contracts 4.5.0 → 4.6.0

package/dist/v1/operations.mjs

@@ -1,3 +1,4 @@
+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 { bingConnectionV1Schemas } from "./bing.mjs";
 import "./version.mjs";
@@ -454,6 +455,8 @@ function createGscdumpV1Protocol() {
 			reason: z.enum(["domain_mismatch", "rate_limited"])
 		}))
 	}), partnerResponseMeta);
+	const watchedUrlsResponse = defineSuccessResponse(defineResponseObject(watchedUrlsResponseSchema.shape), partnerResponseMeta);
+	const watchedUrlsChangeResponse = defineSuccessResponse(defineResponseObject(watchedUrlsChangeResponseSchema.shape), partnerResponseMeta);
 	const dateRangeQuery = z.strictObject({
 		startDate: calendarDate,
 		endDate: calendarDate
@@ -2469,6 +2472,211 @@ function createGscdumpV1Protocol() {
 					}
 				}
 			}),
+			listSiteWatchedUrls: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.indexing.watched.list"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["indexing:read"],
+					ownership: [{
+						credential: "user_key",
+						rule: "authorized_site"
+					}, {
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: watchedUrlsResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.indexing",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "4.6.0" },
+				docs: {
+					summary: "List Watched URLs",
+					description: "Returns the Site's Watched URLs. gscdump inspects each one every 7 days, before other scheduled URLs, and never backs off. Each Checkpoint is one scheduled URL Inspection, newest first, with the parsed coverage state and Google's coverage text.",
+					tags: ["Indexing"],
+					examples: {
+						request: { params: { siteId: "s_01" } },
+						response: {
+							data: {
+								watched: [{
+									url: "https://example.com/guide",
+									addedAt: "2026-09-30T00:00:00.000Z",
+									dueAt: "2026-10-07T01:00:00.000Z",
+									checkpoints: [{
+										checkedAt: "2026-09-30T01:00:00.000Z",
+										coverageState: "unknown_to_google",
+										googleCoverageState: "URL is unknown to Google",
+										verdict: "NEUTRAL",
+										lastCrawlTime: null
+									}]
+								}],
+								limit: 50,
+								cadenceDays: 7,
+								meta: { siteUrl: "sc-domain:example.com" }
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			addSiteWatchedUrls: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.indexing.watched.add"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["indexing:write"],
+					ownership: [{
+						credential: "user_key",
+						rule: "authorized_site"
+					}, {
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: watchedUrlsChangeRequestSchema
+				},
+				responses: { 200: watchedUrlsChangeResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.indexing",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.indexing",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "4.6.0" },
+				docs: {
+					summary: "Add Watched URLs",
+					description: "Adds URLs on the Site host to the Site's Watched URLs, up to 50 per Site. A new Watched URL is due for inspection at once. Each scheduled inspection spends the Site's daily URL Inspection budget and the URL Inspections meter. URLs off the Site host, fragment URLs, and URLs past the limit come back in `skipped`.",
+					tags: ["Indexing"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: { urls: ["https://example.com/guide"] }
+						},
+						response: {
+							data: {
+								changed: ["https://example.com/guide"],
+								unchanged: [],
+								skipped: [],
+								total: 1,
+								limit: 50
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			removeSiteWatchedUrls: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.indexing.watched.remove"),
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["indexing:write"],
+					ownership: [{
+						credential: "user_key",
+						rule: "authorized_site"
+					}, {
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: null,
+					headers: requestHeaders,
+					body: watchedUrlsChangeRequestSchema
+				},
+				responses: { 200: watchedUrlsChangeResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.indexing",
+						idFrom: "params.siteId"
+					}],
+					changes: [{
+						type: "site.indexing",
+						idFrom: "params.siteId"
+					}]
+				},
+				lifecycle: { introduced: "4.6.0" },
+				docs: {
+					summary: "Remove Watched URLs",
+					description: "Removes URLs from the Site's Watched URLs and deletes their Checkpoints. The stored URL Inspection results stay. URLs that were not watched come back in `unchanged`.",
+					tags: ["Indexing"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: { urls: ["https://example.com/guide"] }
+						},
+						response: {
+							data: {
+								changed: ["https://example.com/guide"],
+								unchanged: [],
+								skipped: [],
+								total: 0,
+								limit: 50
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
 			recoverSitePermission: defineHttpOperation({
 				...gscdumpV1OperationRoute("partner.sites.permission.recover"),
 				visibility: "public",
@@ -5064,6 +5272,8 @@ function createGscdumpV1Protocol() {
 			indexingTransitionsResponse,
 			indexingUrlsQuery,
 			indexingUrlsResponse,
+			watchedUrlsResponse,
+			watchedUrlsChangeResponse,
 			bingIndexingEvidenceQuery,
 			bingIndexingEvidenceResponse,
 			bingConnectionResponse,

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

@@ -141,6 +141,21 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "POST";
       readonly template: "/sites/{siteId}/indexing/inspect";
     };
+    readonly 'partner.sites.indexing.watched.list': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/sites/{siteId}/indexing/watched";
+    };
+    readonly 'partner.sites.indexing.watched.add': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/indexing/watched";
+    };
+    readonly 'partner.sites.indexing.watched.remove': {
+      readonly surface: "partner";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/indexing/watched/remove";
+    };
     readonly 'partner.sites.permission.recover': {
       readonly surface: "partner";
       readonly method: "POST";

package/dist/v1/route-catalog.mjs

@@ -128,6 +128,21 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "POST",
 			template: "/sites/{siteId}/indexing/inspect"
 		},
+		"partner.sites.indexing.watched.list": {
+			surface: "partner",
+			method: "GET",
+			template: "/sites/{siteId}/indexing/watched"
+		},
+		"partner.sites.indexing.watched.add": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/indexing/watched"
+		},
+		"partner.sites.indexing.watched.remove": {
+			surface: "partner",
+			method: "POST",
+			template: "/sites/{siteId}/indexing/watched/remove"
+		},
 		"partner.sites.permission.recover": {
 			surface: "partner",
 			method: "POST",

package/package.json

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