@gscdump/contracts 5.8.1 → 5.9.0

package/dist/v1/operations.mjs

@@ -13,6 +13,7 @@ import { GSCDUMP_V1_ANALYTICS_DIMENSIONS, createGscdumpV1BrowserSchemas } from "
 import { googleSubmissionReceiptV1Schemas, googleSubmitV1Schema, indexingApiGrantUpdateV1Schema, indexingApiGrantV1Schemas, siteIndexingApiGrantV1Schemas } from "./google-indexing.mjs";
 import { indexNowConfigureV1Schema, indexNowConnectionV1Schemas, indexNowSubmissionReceiptV1Schemas, indexNowSubmitV1Schema } from "./indexnow.mjs";
 import { gscdumpV1OperationRoute, gscdumpV1Surface } from "./route-catalog.mjs";
+import { sitemapEvidenceV1Schemas, sitemapInspectQueryV1Schema } from "./sitemap-evidence.mjs";
 import { sitemapSubmissionV1Schemas, sitemapSubmitResultV1Schemas } from "./sitemap-submission.mjs";
 import { z } from "zod";
 function errorEnvelopeSchemas(codes, publicRequestId) {
@@ -294,6 +295,7 @@ function createGscdumpV1Protocol() {
 	const bingLinkResponse = defineSuccessResponse(bingLinkResultV1Schemas, partnerResponseMeta);
 	const bingAuthorizationResponse = defineSuccessResponse(bingAuthorizationV1Schemas, partnerResponseMeta);
 	const bingSitemapSubmitResponse = defineSuccessResponse(bingSitemapSubmitResultV1Schemas, partnerResponseMeta);
+	const sitemapEvidenceResponse = defineSuccessResponse(sitemapEvidenceV1Schemas, partnerResponseMeta);
 	const sitemapSubmissionResponse = defineSuccessResponse(sitemapSubmissionV1Schemas, partnerResponseMeta);
 	const sitemapSubmitResponse = defineSuccessResponse(sitemapSubmitResultV1Schemas, partnerResponseMeta);
 	const indexingTransition = defineResponseObject({
@@ -2973,6 +2975,84 @@ function createGscdumpV1Protocol() {
 					}
 				}
 			}),
+			inspectSiteSitemap: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.inspect"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["sitemaps:read"],
+					ownership: [{
+						credential: "user_key",
+						rule: "authorized_site"
+					}, {
+						credential: "partner_key",
+						rule: "authorized_site"
+					}]
+				},
+				request: {
+					params: z.strictObject({ siteId: realtimeSchemas.publicSiteId }),
+					query: sitemapInspectQueryV1Schema,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: sitemapEvidenceResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.sitemaps",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "5.9.0" },
+				docs: {
+					summary: "Inspect a Sitemap",
+					description: "Reads provider evidence for one exact Sitemap URL. Google uses a live read. Bing uses its dated stored read. Missing means the provider did not list that exact Sitemap at Capture time. Unavailable never means missing. This operation submits nothing.",
+					tags: ["Sitemaps"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							query: {
+								searchEngine: "google",
+								url: "https://example.com/sitemap-old.xml"
+							}
+						},
+						response: {
+							data: {
+								searchEngine: "google",
+								sitemapUrl: "https://example.com/sitemap-old.xml",
+								capture: {
+									_tag: "captured",
+									source: "live",
+									capturedAt: "2026-10-08T02:00:00.000Z"
+								},
+								state: {
+									_tag: "listed",
+									lastSubmitted: null,
+									lastDownloaded: null,
+									isPending: true,
+									errors: 0,
+									warnings: 0,
+									urlCount: null
+								}
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
 			getSiteSitemapSubmission: defineHttpOperation({
 				...gscdumpV1OperationRoute("partner.sites.sitemaps.submission.get"),
 				visibility: "public",
@@ -6747,6 +6827,7 @@ function createGscdumpV1Protocol() {
 			bingLinkResponse,
 			bingAuthorizationResponse,
 			bingSitemapSubmitResponse,
+			sitemapEvidenceResponse,
 			sitemapSubmissionResponse,
 			sitemapSubmitResponse,
 			lifecycleResponse,

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

@@ -211,6 +211,11 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "GET";
       readonly template: "/sites/{siteId}/sitemaps/changes";
     };
+    readonly 'partner.sites.sitemaps.inspect': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/sites/{siteId}/sitemaps/inspect";
+    };
     readonly 'partner.sites.sitemaps.submission.get': {
       readonly surface: "partner";
       readonly method: "GET";

package/dist/v1/route-catalog.mjs

@@ -198,6 +198,11 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "GET",
 			template: "/sites/{siteId}/sitemaps/changes"
 		},
+		"partner.sites.sitemaps.inspect": {
+			surface: "partner",
+			method: "GET",
+			template: "/sites/{siteId}/sitemaps/inspect"
+		},
 		"partner.sites.sitemaps.submission.get": {
 			surface: "partner",
 			method: "GET",

package/dist/v1/sitemap-evidence.d.mts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+export declare const sitemapInspectQueryV1Schema: z.ZodObject<{
+  searchEngine: z.ZodEnum<{
+    google: "google";
+    bing: "bing";
+  }>;
+  url: z.ZodURL;
+}, z.core.$strict>;
+/** Exact provider listing evidence. Missing requires a successful dated read. */
+export declare const sitemapEvidenceV1Schemas: {
+  producer: z.ZodUnion<readonly [z.ZodObject<{
+    readonly searchEngine: z.ZodLiteral<"google">;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"captured">;
+      readonly source: z.ZodEnum<{
+        live: "live";
+        stored: "stored";
+      }>;
+      readonly capturedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"listed">;
+      readonly lastSubmitted: z.ZodNullable<z.ZodISODateTime>;
+      readonly lastDownloaded: z.ZodNullable<z.ZodISODateTime>;
+      readonly isPending: z.ZodBoolean;
+      readonly errors: z.ZodNumber;
+      readonly warnings: z.ZodNumber;
+      readonly urlCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"missing">;
+    }, z.core.$strip>], "_tag">;
+  }, z.core.$strip>, z.ZodObject<{
+    readonly searchEngine: z.ZodLiteral<"bing">;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"captured">;
+      readonly source: z.ZodEnum<{
+        live: "live";
+        stored: "stored";
+      }>;
+      readonly capturedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"listed">;
+      readonly status: z.ZodString;
+      readonly submittedAt: z.ZodNullable<z.ZodISODateTime>;
+      readonly lastCrawledAt: z.ZodNullable<z.ZodISODateTime>;
+      readonly urlCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"missing">;
+    }, z.core.$strip>], "_tag">;
+  }, z.core.$strip>, z.ZodObject<{
+    readonly searchEngine: z.ZodEnum<{
+      google: "google";
+      bing: "bing";
+    }>;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"unavailable">;
+    }, z.core.$strip>;
+    readonly state: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"unavailable">;
+      readonly reason: z.ZodEnum<{
+        "not-checked": "not-checked";
+        "permission-lost": "permission-lost";
+        "grant-missing": "grant-missing";
+        "provider-unavailable": "provider-unavailable";
+        "reauthorization-required": "reauthorization-required";
+        "not-enabled": "not-enabled";
+        "site-unverified": "site-unverified";
+        throttled: "throttled";
+      }>;
+      readonly retryable: z.ZodBoolean;
+    }, z.core.$strip>;
+  }, z.core.$strip>]>;
+  client: z.ZodUnion<readonly [z.ZodObject<{
+    readonly searchEngine: z.ZodLiteral<"google">;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"captured">;
+      readonly source: z.ZodEnum<{
+        live: "live";
+        stored: "stored";
+      }>;
+      readonly capturedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"listed">;
+      readonly lastSubmitted: z.ZodNullable<z.ZodISODateTime>;
+      readonly lastDownloaded: z.ZodNullable<z.ZodISODateTime>;
+      readonly isPending: z.ZodBoolean;
+      readonly errors: z.ZodNumber;
+      readonly warnings: z.ZodNumber;
+      readonly urlCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"missing">;
+    }, z.core.$strip>], "_tag">;
+  }, z.core.$strip>, z.ZodObject<{
+    readonly searchEngine: z.ZodLiteral<"bing">;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"captured">;
+      readonly source: z.ZodEnum<{
+        live: "live";
+        stored: "stored";
+      }>;
+      readonly capturedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    readonly state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"listed">;
+      readonly status: z.ZodString;
+      readonly submittedAt: z.ZodNullable<z.ZodISODateTime>;
+      readonly lastCrawledAt: z.ZodNullable<z.ZodISODateTime>;
+      readonly urlCount: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"missing">;
+    }, z.core.$strip>], "_tag">;
+  }, z.core.$strip>, z.ZodObject<{
+    readonly searchEngine: z.ZodEnum<{
+      google: "google";
+      bing: "bing";
+    }>;
+    readonly sitemapUrl: z.ZodURL;
+    readonly capture: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"unavailable">;
+    }, z.core.$strip>;
+    readonly state: z.ZodObject<{
+      readonly _tag: z.ZodLiteral<"unavailable">;
+      readonly reason: z.ZodEnum<{
+        "not-checked": "not-checked";
+        "permission-lost": "permission-lost";
+        "grant-missing": "grant-missing";
+        "provider-unavailable": "provider-unavailable";
+        "reauthorization-required": "reauthorization-required";
+        "not-enabled": "not-enabled";
+        "site-unverified": "site-unverified";
+        throttled: "throttled";
+      }>;
+      readonly retryable: z.ZodBoolean;
+    }, z.core.$strip>;
+  }, z.core.$strip>]>;
+};
+export type SitemapInspectQueryV1 = z.infer<typeof sitemapInspectQueryV1Schema>;
+export type SitemapEvidenceV1 = z.infer<typeof sitemapEvidenceV1Schemas.producer>;

package/dist/v1/sitemap-evidence.mjs

@@ -0,0 +1,93 @@
+import { defineResponseObject } from "./http-core.mjs";
+import { z } from "zod";
+const sitemapUrl = z.url({ protocol: /^https?$/ }).max(2048).refine((value) => {
+	const url = new URL(value);
+	return !url.username && !url.password && !url.hash;
+}, "Use a Sitemap URL without credentials or a fragment.");
+const sitemapInspectQueryV1Schema = z.strictObject({
+	searchEngine: z.enum(["google", "bing"]),
+	url: sitemapUrl
+});
+const captured = defineResponseObject({
+	_tag: z.literal("captured"),
+	source: z.enum(["live", "stored"]),
+	capturedAt: z.iso.datetime()
+});
+const unavailableCapture = defineResponseObject({ _tag: z.literal("unavailable") });
+const missing = defineResponseObject({ _tag: z.literal("missing") });
+const unavailable = defineResponseObject({
+	_tag: z.literal("unavailable"),
+	reason: z.enum([
+		"grant-missing",
+		"reauthorization-required",
+		"permission-lost",
+		"site-unverified",
+		"not-enabled",
+		"not-checked",
+		"throttled",
+		"provider-unavailable"
+	]),
+	retryable: z.boolean()
+});
+const googleListed = defineResponseObject({
+	_tag: z.literal("listed"),
+	lastSubmitted: z.iso.datetime({ offset: true }).nullable(),
+	lastDownloaded: z.iso.datetime({ offset: true }).nullable(),
+	isPending: z.boolean(),
+	errors: z.number().int().nonnegative(),
+	warnings: z.number().int().nonnegative(),
+	urlCount: z.number().int().nonnegative().nullable()
+});
+const bingListed = defineResponseObject({
+	_tag: z.literal("listed"),
+	status: z.string(),
+	submittedAt: z.iso.datetime({ offset: true }).nullable(),
+	lastCrawledAt: z.iso.datetime({ offset: true }).nullable(),
+	urlCount: z.number().int().nonnegative().nullable()
+});
+const google = defineResponseObject({
+	searchEngine: z.literal("google"),
+	sitemapUrl,
+	capture: captured.producer,
+	state: z.discriminatedUnion("_tag", [googleListed.producer, missing.producer])
+}, {
+	searchEngine: z.literal("google"),
+	sitemapUrl,
+	capture: captured.client,
+	state: z.discriminatedUnion("_tag", [googleListed.client, missing.client])
+});
+const bing = defineResponseObject({
+	searchEngine: z.literal("bing"),
+	sitemapUrl,
+	capture: captured.producer,
+	state: z.discriminatedUnion("_tag", [bingListed.producer, missing.producer])
+}, {
+	searchEngine: z.literal("bing"),
+	sitemapUrl,
+	capture: captured.client,
+	state: z.discriminatedUnion("_tag", [bingListed.client, missing.client])
+});
+const failed = defineResponseObject({
+	searchEngine: z.enum(["google", "bing"]),
+	sitemapUrl,
+	capture: unavailableCapture.producer,
+	state: unavailable.producer
+}, {
+	searchEngine: z.enum(["google", "bing"]),
+	sitemapUrl,
+	capture: unavailableCapture.client,
+	state: unavailable.client
+});
+const sitemapEvidenceV1Schemas = {
+	producer: z.union([
+		google.producer,
+		bing.producer,
+		failed.producer
+	]),
+	client: z.union([
+		google.client,
+		bing.client,
+		failed.client
+	])
+};
+export { sitemapEvidenceV1Schemas, sitemapInspectQueryV1Schema };

package/package.json

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