@gscdump/contracts 4.6.0 → 4.7.0

package/dist/v1/operations.mjs

@@ -1,3 +1,4 @@
+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";
@@ -386,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,
@@ -813,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",
@@ -5281,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";

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",

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.6.0",
+  "version": "4.7.0",
   "description": "Shared gscdump.com API, webhook, realtime, and lifecycle contracts.",
   "author": {
     "name": "Harlan Wilton",