@gscdump/contracts 1.5.3 → 2.0.0

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";
@@ -52,7 +52,7 @@ function createGscdumpV1Protocol() {
 	});
 	const requestHeaders = z.strictObject({ "x-request-id": realtimeSchemas.publicRequestId.optional() });
 	const errorEnvelope = errorEnvelopeSchemas(HTTP_V1_ERROR_CODES, realtimeSchemas.publicRequestId);
-	const { analyticsRowsRequest, analyticsRowsResponse, lifecycleResponse } = browserSchemas;
+	const { analyticsRowsRequest, analyticsRowsResponse, keywordEnrichmentRequest, keywordEnrichmentResponse, lifecycleResponse } = browserSchemas;
 	const dimensions = GSCDUMP_V1_ANALYTICS_DIMENSIONS;
 	const analyticsMeta = defineResponseObject({
 		requestId: realtimeSchemas.publicRequestId,
@@ -495,6 +495,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();
@@ -564,12 +574,6 @@ function createGscdumpV1Protocol() {
 		sources: z.array(z.string()),
 		rows: z.array(z.record(z.string(), z.json()))
 	}), partnerResponseMeta);
-	const enrichKeywordsRequest = z.strictObject({ keywords: z.array(z.string().min(1)).min(1).max(500) });
-	const enrichKeywordsResponse = defineSuccessResponse(defineResponseObject({ metrics: z.record(z.string(), z.object({
-		difficulty: z.number().nullable(),
-		searchVolume: z.number().nullable(),
-		cpc: z.number().nullable()
-	}).loose()) }), partnerResponseMeta);
 	const responseStreamHead = defineResponseObject({
 		streamId: realtimeSchemas.streamId,
 		sequence: realtimeSchemas.sequence
@@ -1341,6 +1345,7 @@ function createGscdumpV1Protocol() {
 								sitemaps: [],
 								history: [],
 								perSitemapHistory: {},
+								generation: null,
 								meta: {
 									siteUrl: "sc-domain:example.com",
 									gscPropertyUrl: "sc-domain:example.com",
@@ -1413,9 +1418,12 @@ function createGscdumpV1Protocol() {
 							data: {
 								added: [],
 								removed: [],
+								updated: [],
+								generation: null,
 								summary: {
 									totalAdded: 0,
 									totalRemoved: 0,
+									totalUpdated: 0,
 									period: { days: 28 }
 								},
 								completeness: {
@@ -2755,26 +2763,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: {
@@ -3807,9 +3958,9 @@ function createGscdumpV1Protocol() {
 					params: null,
 					query: null,
 					headers: requestHeaders,
-					body: enrichKeywordsRequest
+					body: keywordEnrichmentRequest
 				},
-				responses: { 200: enrichKeywordsResponse },
+				responses: { 200: keywordEnrichmentResponse },
 				errors: partnerUserErrors,
 				errorResponse: errorEnvelopeSchemas(partnerUserErrors, realtimeSchemas.publicRequestId),
 				resources: {
@@ -4251,6 +4402,8 @@ function createGscdumpV1Protocol() {
 			indexingTransitionsResponse,
 			indexingUrlsQuery,
 			indexingUrlsResponse,
+			keywordEnrichmentRequest,
+			keywordEnrichmentResponse,
 			lifecycleResponse,
 			registerSiteRequest,
 			sitemapChangesQuery,

package/package.json

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