@gscdump/contracts 4.5.0 → 4.7.0

package/dist/v1/operations.mjs

@@ -1,3 +1,5 @@
+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 { bingConnectionV1Schemas } from "./bing.mjs";
 import "./version.mjs";
@@ -385,6 +387,52 @@ function createGscdumpV1Protocol() {
 		ok: z.literal(true),
 		keyId: partnerUserApiKeyId
 	}), partnerResponseMeta);
+	const entitlementCount = z.number().int().nonnegative();
+	const entitlementUsage = defineResponseObject({
+		used: entitlementCount,
+		allowance: entitlementCount
+	});
+	const preservedRowsUsage = defineResponseObject({
+		used: entitlementCount.nullable(),
+		allowance: entitlementCount
+	});
+	const urlInspectionsUsage = defineResponseObject({
+		used: entitlementCount,
+		allowance: entitlementCount.nullable(),
+		resetsAt: z.iso.date()
+	});
+	const entitlementMeters = defineResponseObject({
+		sites: entitlementUsage.producer,
+		preservedRows: preservedRowsUsage.producer,
+		urlInspections: urlInspectionsUsage.producer
+	}, {
+		sites: entitlementUsage.client,
+		preservedRows: preservedRowsUsage.client,
+		urlInspections: urlInspectionsUsage.client
+	});
+	const heldSite = defineResponseObject({
+		siteId: realtimeSchemas.publicSiteId,
+		hold: siteHoldReasonSchema
+	});
+	const exemptEntitlements = defineResponseObject({ mode: z.literal("exempt") });
+	const meteredEntitlementsShape = {
+		mode: z.literal("metered"),
+		phase: z.enum(["beta", "billing"]),
+		sizeLimitRowsPerDay: z.number().int().positive()
+	};
+	const meteredEntitlements = defineResponseObject({
+		...meteredEntitlementsShape,
+		meters: entitlementMeters.producer,
+		heldSites: z.array(heldSite.producer)
+	}, {
+		...meteredEntitlementsShape,
+		meters: entitlementMeters.client,
+		heldSites: z.array(heldSite.client)
+	});
+	const userEntitlementsResponse = defineSuccessResponse({
+		producer: z.discriminatedUnion("mode", [exemptEntitlements.producer, meteredEntitlements.producer]),
+		client: z.discriminatedUnion("mode", [exemptEntitlements.client, meteredEntitlements.client])
+	}, partnerResponseMeta);
 	const trendQuery = z.strictObject({
 		startDate: calendarDate,
 		endDate: calendarDate,
@@ -454,6 +502,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
@@ -810,6 +860,87 @@ function createGscdumpV1Protocol() {
 					}
 				}
 			}),
+			getUserEntitlements: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.users.entitlements.get"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["users:read"],
+					ownership: [{
+						credential: "user_key",
+						rule: "self"
+					}, {
+						credential: "partner_key",
+						rule: "linked_user"
+					}]
+				},
+				request: {
+					params: z.strictObject({ userId: realtimeSchemas.publicUserId }),
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: userEntitlementsResponse },
+				errors: partnerUserErrors,
+				errorResponse: errorEnvelopeSchemas(partnerUserErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}, {
+						type: "user.sites",
+						idFrom: "params.userId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "4.7.0" },
+				docs: {
+					summary: "Get user entitlements",
+					description: "Returns the Meters that apply to the user's partner Sites. If the partner is exempt, the response is `{ mode: \"exempt\" }` and no free allowance applies. If the partner is metered, the response gives the usage of the user's Billing owner against each free allowance, the size limit in query×page rows per day, and the held Sites the user can read. `urlInspections.allowance` is `null` when URL Inspections have no cap. `urlInspections.resetsAt` is the first UTC day of the next usage month.",
+					tags: ["Users"],
+					examples: {
+						request: { params: { userId: "u_01" } },
+						response: {
+							data: {
+								mode: "metered",
+								phase: "beta",
+								meters: {
+									sites: {
+										used: 2,
+										allowance: 3
+									},
+									preservedRows: {
+										used: 12e4,
+										allowance: 25e4
+									},
+									urlInspections: {
+										used: 310,
+										allowance: 5e3,
+										resetsAt: "2026-11-01"
+									}
+								},
+								sizeLimitRowsPerDay: 2500,
+								heldSites: [{
+									siteId: "s_02",
+									hold: "size_limit"
+								}]
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
 			listAvailableSites: defineHttpOperation({
 				...gscdumpV1OperationRoute("partner.users.sites.available.list"),
 				visibility: "public",
@@ -2469,6 +2600,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 +5400,8 @@ function createGscdumpV1Protocol() {
 			indexingTransitionsResponse,
 			indexingUrlsQuery,
 			indexingUrlsResponse,
+			watchedUrlsResponse,
+			watchedUrlsChangeResponse,
 			bingIndexingEvidenceQuery,
 			bingIndexingEvidenceResponse,
 			bingConnectionResponse,
@@ -5071,6 +5409,7 @@ function createGscdumpV1Protocol() {
 			indexNowSubmissionResponse,
 			indexNowSubmissionReceiptsResponse,
 			lifecycleResponse,
+			userEntitlementsResponse,
 			registerSiteRequest,
 			sitemapChangesQuery,
 			sitemapChangesResponse,

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

@@ -21,6 +21,11 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "GET";
       readonly template: "/users/{userId}/lifecycle";
     };
+    readonly 'partner.users.entitlements.get': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/users/{userId}/entitlements";
+    };
     readonly 'partner.users.sites.available.list': {
       readonly surface: "partner";
       readonly method: "GET";
@@ -141,6 +146,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

@@ -8,6 +8,11 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "GET",
 			template: "/users/{userId}/lifecycle"
 		},
+		"partner.users.entitlements.get": {
+			surface: "partner",
+			method: "GET",
+			template: "/users/{userId}/entitlements"
+		},
 		"partner.users.sites.available.list": {
 			surface: "partner",
 			method: "GET",
@@ -128,6 +133,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/dist/webhook-constants.d.mts

@@ -4,5 +4,5 @@ export declare const WEBHOOK_EVENT_HEADER = "X-GSCDump-Event";
 export declare const WEBHOOK_DELIVERY_HEADER = "X-GSCDump-Delivery";
 export declare const WEBHOOK_CONTRACT_VERSION_HEADER = "X-GSCDump-Contract-Version";
 export declare const WEBHOOK_TIMESTAMP_HEADER = "X-GSCDump-Timestamp";
-export declare const CANONICAL_WEBHOOK_EVENTS: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed"];
-export declare const VALID_WEBHOOK_EVENTS: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed"];
+export declare const CANONICAL_WEBHOOK_EVENTS: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed", "user.allowance.notice"];
+export declare const VALID_WEBHOOK_EVENTS: readonly ["user.lifecycle.changed", "site.lifecycle.changed", "site.analytics.ready", "site.indexing.ready", "site.auth.failed", "job.failed", "user.allowance.notice"];

package/dist/webhook-constants.mjs

@@ -10,7 +10,8 @@ const CANONICAL_WEBHOOK_EVENTS = [
 	"site.analytics.ready",
 	"site.indexing.ready",
 	"site.auth.failed",
-	"job.failed"
+	"job.failed",
+	"user.allowance.notice"
 ];
 const VALID_WEBHOOK_EVENTS = CANONICAL_WEBHOOK_EVENTS;
 export { 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 };

package/package.json

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