@gscdump/contracts 1.5.4 → 2.0.1

package/dist/v1/operations.mjs

@@ -1,4 +1,4 @@
-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, gscdumpSitemapMembershipParamsSchema, gscdumpSitemapMembershipResponseSchema, 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, 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 "./version.mjs";
 import { HTTP_V1_ERROR_CODES, defineHttpOperation, defineHttpSurface, defineResponseObject, defineSuccessResponse } from "./http-core.mjs";
 import { GSCDUMP_REALTIME_ACK_POLICY, GSCDUMP_REALTIME_CLOSE_CODES, GSCDUMP_REALTIME_CONNECTION_POLICY, GSCDUMP_REALTIME_LIMITS, GSCDUMP_REALTIME_PING, GSCDUMP_REALTIME_PONG, GSCDUMP_REALTIME_REPLAY_POLICY, GSCDUMP_REALTIME_SUBPROTOCOL, GSCDUMP_REALTIME_TICKET_AUDIENCE, GSCDUMP_REALTIME_TICKET_ISSUER, GSCDUMP_REALTIME_TICKET_POLICY, GSCDUMP_REALTIME_TICKET_PREFIX, REALTIME_V1_EVENT_SEMANTICS, createRealtimeV1Schemas } from "./realtime.mjs";
@@ -242,10 +242,12 @@ function createGscdumpV1Protocol() {
 		_tag: z.literal("truncated"),
 		scannedUrls: z.number().int().nonnegative(),
 		reasons: z.array(sitemapChangesTruncationReasonSchema).min(1),
+		historyAvailableFrom: z.number().int().nonnegative().optional(),
 		limits: z.strictObject({
 			scannedUrls: z.number().int().positive(),
 			added: z.number().int().positive(),
-			removed: z.number().int().positive()
+			removed: z.number().int().positive(),
+			updated: z.number().int().positive()
 		})
 	};
 	const sitemapChangesResponse = defineSuccessResponse(defineResponseObject({
@@ -495,6 +497,16 @@ function createGscdumpV1Protocol() {
 	}, partnerResponseMeta);
 	const sitemapMembershipRequest = gscdumpSitemapMembershipParamsSchema.strict();
 	const sitemapMembershipResponse = defineSuccessResponse(defineResponseObject(gscdumpSitemapMembershipResponseSchema.shape), partnerResponseMeta);
+	const sitemapUrlsQuery = gscdumpSitemapUrlsQuerySchema;
+	const sitemapUrlsResponse = defineSuccessResponse({
+		producer: gscdumpSitemapUrlsResponseSchema,
+		client: gscdumpSitemapUrlsResponseSchema
+	}, partnerResponseMeta);
+	const sitemapExportQuery = gscdumpSitemapExportQuerySchema;
+	const sitemapExportResponse = defineSuccessResponse({
+		producer: gscdumpSitemapExportResponseSchema,
+		client: gscdumpSitemapExportResponseSchema
+	}, partnerResponseMeta);
 	const createTeamRequest = createPartnerTeamSchema.strict();
 	const teamCreatedResponse = defineSuccessResponse(defineResponseObject(partnerTeamCreatedResponseSchema.shape), partnerResponseMeta);
 	const renameTeamRequest = renamePartnerTeamSchema.strict();
@@ -1335,6 +1347,7 @@ function createGscdumpV1Protocol() {
 								sitemaps: [],
 								history: [],
 								perSitemapHistory: {},
+								generation: null,
 								meta: {
 									siteUrl: "sc-domain:example.com",
 									gscPropertyUrl: "sc-domain:example.com",
@@ -1407,9 +1420,12 @@ function createGscdumpV1Protocol() {
 							data: {
 								added: [],
 								removed: [],
+								updated: [],
+								generation: null,
 								summary: {
 									totalAdded: 0,
 									totalRemoved: 0,
+									totalUpdated: 0,
 									period: { days: 28 }
 								},
 								completeness: {
@@ -2749,26 +2765,169 @@ function createGscdumpV1Protocol() {
 				lifecycle: { introduced: "1.3.0" },
 				docs: {
 					summary: "Query sitemap membership",
-					description: "Checks whether each requested URL is present in the site's known sitemaps, subject to a freshness cap.",
+					description: "Returns generation-pinned present, absent, or unknown evidence for each exact requested URL.",
 					tags: ["Sitemaps"],
 					examples: {
 						request: {
 							params: { siteId: "s_01" },
-							body: {
-								urls: ["https://example.com/"],
-								maxAgeDays: 30
-							}
+							body: { urls: ["https://example.com/"] }
 						},
 						response: {
 							data: {
-								urls: [],
+								generation: null,
+								evidence: [{
+									_tag: "unknown",
+									url: "https://example.com/",
+									reason: "no_generation"
+								}],
 								meta: {
-									available: true,
-									reason: null,
 									requested: 1,
-									checked: 1,
-									matched: 0,
-									newestFetchedAt: null
+									checked: 0,
+									matched: 0
+								}
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			listSitemapUrls: defineHttpOperation({
+				id: "partner.sites.sitemaps.urls.get",
+				method: "GET",
+				path: "/sites/{siteId}/sitemaps/urls",
+				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: sitemapUrlsQuery,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: sitemapUrlsResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.sitemaps",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "2.0.0" },
+				docs: {
+					summary: "List sitemap URLs",
+					description: "Returns an exact generation-pinned cursor page of sitemap membership and lastmod evidence.",
+					tags: ["Sitemaps"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							query: { limit: 500 }
+						},
+						response: {
+							data: {
+								generation: {
+									id: "site-01JZ",
+									observedAt: 1753746e6,
+									publishedAt: 1753746000100,
+									completeness: { _tag: "complete" },
+									membershipHistoryAvailableFrom: 1753746e6,
+									legacyImport: { _tag: "none" }
+								},
+								items: [],
+								page: {
+									nextCursor: null,
+									limit: 500
+								}
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			getSitemapExport: defineHttpOperation({
+				id: "partner.sites.sitemaps.export.get",
+				method: "GET",
+				path: "/sites/{siteId}/sitemaps/export",
+				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: sitemapExportQuery,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: sitemapExportResponse },
+				errors: partnerSiteErrors,
+				errorResponse: errorEnvelopeSchemas(partnerSiteErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.sitemaps",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "2.0.0" },
+				docs: {
+					summary: "Get sitemap bulk export",
+					description: "Returns a generation-pinned expiring URL for the full NDJSON sitemap projection.",
+					tags: ["Sitemaps"],
+					examples: {
+						request: { params: { siteId: "s_01" } },
+						response: {
+							data: {
+								generation: {
+									id: "site-01JZ",
+									observedAt: 1753746e6,
+									publishedAt: 1753746000100,
+									completeness: { _tag: "complete" },
+									membershipHistoryAvailableFrom: 1753746e6,
+									legacyImport: { _tag: "none" }
+								},
+								export: {
+									_tag: "unavailable",
+									reason: "export_unavailable"
 								}
 							},
 							meta: {

package/package.json

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