@gscdump/contracts 7.11.0 → 7.12.0

package/dist/v1/operations.mjs

@@ -4,6 +4,7 @@ import { addPartnerTeamMemberSchema, bindPartnerSiteTeamSchema, bindPartnerTeamC
 import { siteVersionBeginRequestSchema, siteVersionCandidateRequestSchema, siteVersionCandidateSchema, siteVersionIdentityResponseSchema, siteVersionPreviewRequestSchema, siteVersionPreviewSchema } from "../site-version.mjs";
 import "./version.mjs";
 import { HTTP_V1_ERROR_CODES, defineHttpOperation, defineHttpSurface, defineResponseObject, defineSuccessResponse } from "./http-core.mjs";
+import { userIntegrationActivityV1Schemas } from "./agent-usage.mjs";
 import { analyticsCoverageQueryV1Schema, analyticsCoverageV1Schemas } from "./analytics-coverage.mjs";
 import { bingConnectionV1Schemas } from "./bing.mjs";
 import { bingDataQueryV1Schema, bingDataV1Schemas } from "./bing-data.mjs";
@@ -12,6 +13,7 @@ import { GSCDUMP_REALTIME_ACK_POLICY, GSCDUMP_REALTIME_CLOSE_CODES, GSCDUMP_REAL
 import { GSCDUMP_V1_ANALYTICS_DIMENSIONS, createGscdumpV1BrowserSchemas } from "./browser.mjs";
 import { googleSubmissionReceiptV1Schemas, googleSubmitV1Schema, indexingApiGrantUpdateV1Schema, indexingApiGrantV1Schemas, siteIndexingApiGrantV1Schemas } from "./google-indexing.mjs";
 import { indexNowConfigureV1Schema, indexNowConnectionV1Schemas, indexNowSubmissionReceiptV1Schemas, indexNowSubmitV1Schema } from "./indexnow.mjs";
+import { runReportV1DataSchemas, runReportV1RequestSchema } from "./report.mjs";
 import { gscdumpV1OperationRoute, gscdumpV1Surface } from "./route-catalog.mjs";
 import { sitemapEvidenceV1Schemas, sitemapInspectQueryV1Schema } from "./sitemap-evidence.mjs";
 import { sitemapSubmissionV1Schemas, sitemapSubmitResultV1Schemas } from "./sitemap-submission.mjs";
@@ -53,6 +55,8 @@ function createGscdumpV1Protocol() {
 		surface: z.literal("partner"),
 		version: z.literal("1.0")
 	});
+	const userIntegrationActivityResponse = defineSuccessResponse(userIntegrationActivityV1Schemas, partnerResponseMeta);
+	const runReportResponse = defineSuccessResponse(runReportV1DataSchemas, responseMeta);
 	const realtimeResponseMeta = defineResponseObject({
 		requestId: realtimeSchemas.publicRequestId,
 		surface: z.literal("realtime"),
@@ -5605,6 +5609,61 @@ function createGscdumpV1Protocol() {
 					}
 				}
 			}),
+			getUserIntegrationActivity: defineHttpOperation({
+				...gscdumpV1OperationRoute("partner.users.integration_activity.get"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["partner_key"],
+					scopes: ["users:read"],
+					ownership: [{
+						credential: "partner_key",
+						rule: "linked_user"
+					}]
+				},
+				request: {
+					params: z.strictObject({ userId: realtimeSchemas.publicUserId }),
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: userIntegrationActivityResponse },
+				errors: partnerUserErrors,
+				errorResponse: errorEnvelopeSchemas(partnerUserErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "partner.user",
+						idFrom: "params.userId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "7.12.0" },
+				docs: {
+					summary: "Read partner integration activity",
+					description: "Reads retained activity attributed to credentials issued by this partner. Unknown counts remain null.",
+					tags: ["Users"],
+					examples: {
+						request: { params: { userId: "u_01" } },
+						response: {
+							data: {
+								measuredAt: "2026-11-10T00:00:00.000Z",
+								activities: []
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "partner",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
 			deleteUser: defineHttpOperation({
 				...gscdumpV1OperationRoute("partner.users.delete"),
 				visibility: "public",
@@ -6423,6 +6482,80 @@ function createGscdumpV1Protocol() {
 	const analytics = defineHttpSurface({
 		...gscdumpV1Surface("analytics"),
 		operations: {
+			runReport: defineHttpOperation({
+				...gscdumpV1OperationRoute("analytics.reports.run"),
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["analytics:execute"],
+					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: runReportV1RequestSchema
+				},
+				responses: { 200: runReportResponse },
+				errors: analyticsRowsErrors,
+				errorResponse: errorEnvelopeSchemas(analyticsRowsErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [{
+						type: "site.analytics",
+						idFrom: "params.siteId"
+					}],
+					changes: []
+				},
+				lifecycle: { introduced: "7.12.0" },
+				docs: {
+					summary: "Run a retained search evidence report",
+					description: "Returns deterministic report evidence, coverage, and capture clocks without advice or severity.",
+					tags: ["Analytics reports"],
+					examples: {
+						request: {
+							params: { siteId: "s_01" },
+							body: { reportId: "health" }
+						},
+						response: {
+							data: {
+								site: "https://example.com/",
+								generatedAt: "2026-11-10T00:00:00.000Z",
+								cached: false,
+								window: {
+									start: "2026-10-01",
+									end: "2026-10-28",
+									days: 28
+								},
+								meta: {
+									durationMs: 1,
+									rowsScanned: 0,
+									degraded: false,
+									steps: []
+								},
+								sections: []
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "analytics",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
 			queryRows: defineHttpOperation({
 				...gscdumpV1OperationRoute("analytics.rows.query"),
 				visibility: "public",

package/dist/v1/report.d.mts

@@ -0,0 +1,198 @@
+import { CompatibleResponseSchema } from "./http-core.mjs";
+import { z } from "zod";
+export declare const runReportV1RequestSchema: z.ZodObject<{
+  reportId: z.ZodEnum<{
+    health: "health";
+    risks: "risks";
+    opportunities: "opportunities";
+    movers: "movers";
+    growth: "growth";
+    triage: "triage";
+    brand: "brand";
+    "pre-publish": "pre-publish";
+  }>;
+  period: z.ZodOptional<z.ZodEnum<{
+    custom: "custom";
+    "last-7d": "last-7d";
+    "last-28d": "last-28d";
+    "last-30d": "last-30d";
+    "last-90d": "last-90d";
+    "last-180d": "last-180d";
+    "last-365d": "last-365d";
+    mtd: "mtd";
+    qtd: "qtd";
+    ytd: "ytd";
+    "last-quarter": "last-quarter";
+  }>>;
+  comparison: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    "prev-period": "prev-period";
+    yoy: "yoy";
+  }>>;
+  start: z.ZodOptional<z.ZodISODate>;
+  end: z.ZodOptional<z.ZodISODate>;
+  target: z.ZodOptional<z.ZodString>;
+  targetKind: z.ZodOptional<z.ZodEnum<{
+    page: "page";
+    query: "query";
+  }>>;
+  brandTerms: z.ZodOptional<z.ZodString>;
+  topic: z.ZodOptional<z.ZodString>;
+  maxFindings: z.ZodOptional<z.ZodNumber>;
+  minClicksChange: z.ZodOptional<z.ZodNumber>;
+  force: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Evidence only. Advice and severity are intentionally outside the hosted data contract. */
+export declare const runReportV1DataSchemas: CompatibleResponseSchema<z.ZodObject<{
+  readonly site: z.ZodString;
+  readonly generatedAt: z.ZodISODateTime;
+  readonly cached: z.ZodBoolean;
+  readonly window: z.ZodObject<{
+    start: z.ZodISODate;
+    end: z.ZodISODate;
+    days: z.ZodNumber;
+    comparison: z.ZodOptional<z.ZodObject<{
+      start: z.ZodISODate;
+      end: z.ZodISODate;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  readonly meta: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    rowsScanned: z.ZodNumber;
+    degraded: z.ZodBoolean;
+    steps: z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      type: z.ZodString;
+      status: z.ZodEnum<{
+        error: "error";
+        skipped: "skipped";
+        pending: "pending";
+        done: "done";
+        running: "running";
+      }>;
+      error: z.ZodOptional<z.ZodString>;
+      coverage: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"complete">;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"truncated">;
+        fetched: z.ZodNumber;
+      }, z.core.$strict>], "kind">>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  readonly sections: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodObject<{
+      delta: z.ZodOptional<z.ZodNumber>;
+      direction: z.ZodOptional<z.ZodEnum<{
+        flat: "flat";
+        up: "up";
+        down: "down";
+      }>>;
+      magnitudeLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    coverage: z.ZodEnum<{
+      partial: "partial";
+      full: "full";
+    }>;
+    truncated: z.ZodOptional<z.ZodObject<{
+      kept: z.ZodNumber;
+      total: z.ZodNumber;
+    }, z.core.$strict>>;
+    dataUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    findings: z.ZodArray<z.ZodObject<{
+      entity: z.ZodObject<{
+        kind: z.ZodEnum<{
+          page: "page";
+          query: "query";
+        }>;
+        value: z.ZodString;
+      }, z.core.$strict>;
+      metrics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+      delta: z.ZodOptional<z.ZodObject<{
+        metric: z.ZodString;
+        prior: z.ZodNumber;
+        current: z.ZodNumber;
+        pct: z.ZodNumber;
+      }, z.core.$strict>>;
+      why: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+}, z.core.$strip>, z.ZodObject<{
+  readonly site: z.ZodString;
+  readonly generatedAt: z.ZodISODateTime;
+  readonly cached: z.ZodBoolean;
+  readonly window: z.ZodObject<{
+    start: z.ZodISODate;
+    end: z.ZodISODate;
+    days: z.ZodNumber;
+    comparison: z.ZodOptional<z.ZodObject<{
+      start: z.ZodISODate;
+      end: z.ZodISODate;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  readonly meta: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    rowsScanned: z.ZodNumber;
+    degraded: z.ZodBoolean;
+    steps: z.ZodArray<z.ZodObject<{
+      key: z.ZodString;
+      type: z.ZodString;
+      status: z.ZodEnum<{
+        error: "error";
+        skipped: "skipped";
+        pending: "pending";
+        done: "done";
+        running: "running";
+      }>;
+      error: z.ZodOptional<z.ZodString>;
+      coverage: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"complete">;
+      }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"truncated">;
+        fetched: z.ZodNumber;
+      }, z.core.$strict>], "kind">>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  readonly sections: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    summary: z.ZodObject<{
+      delta: z.ZodOptional<z.ZodNumber>;
+      direction: z.ZodOptional<z.ZodEnum<{
+        flat: "flat";
+        up: "up";
+        down: "down";
+      }>>;
+      magnitudeLabel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    coverage: z.ZodEnum<{
+      partial: "partial";
+      full: "full";
+    }>;
+    truncated: z.ZodOptional<z.ZodObject<{
+      kept: z.ZodNumber;
+      total: z.ZodNumber;
+    }, z.core.$strict>>;
+    dataUnavailable: z.ZodOptional<z.ZodLiteral<true>>;
+    findings: z.ZodArray<z.ZodObject<{
+      entity: z.ZodObject<{
+        kind: z.ZodEnum<{
+          page: "page";
+          query: "query";
+        }>;
+        value: z.ZodString;
+      }, z.core.$strict>;
+      metrics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+      delta: z.ZodOptional<z.ZodObject<{
+        metric: z.ZodString;
+        prior: z.ZodNumber;
+        current: z.ZodNumber;
+        pct: z.ZodNumber;
+      }, z.core.$strict>>;
+      why: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+}, z.core.$strip>>;
+export type RunReportV1Request = z.input<typeof runReportV1RequestSchema>;
+export type RunReportV1Data = z.infer<typeof runReportV1DataSchemas.client>;

package/dist/v1/report.mjs

@@ -0,0 +1,137 @@
+import { defineResponseObject } from "./http-core.mjs";
+import { z } from "zod";
+const runReportV1RequestSchema = z.strictObject({
+	reportId: z.enum([
+		"health",
+		"risks",
+		"opportunities",
+		"movers",
+		"growth",
+		"triage",
+		"brand",
+		"pre-publish"
+	]),
+	period: z.enum([
+		"last-7d",
+		"last-28d",
+		"last-30d",
+		"last-90d",
+		"last-180d",
+		"last-365d",
+		"mtd",
+		"qtd",
+		"ytd",
+		"last-quarter",
+		"custom"
+	]).optional(),
+	comparison: z.enum([
+		"none",
+		"prev-period",
+		"yoy"
+	]).optional(),
+	start: z.iso.date().optional(),
+	end: z.iso.date().optional(),
+	target: z.string().min(1).max(2048).optional(),
+	targetKind: z.enum(["page", "query"]).optional(),
+	brandTerms: z.string().min(1).max(2e3).optional(),
+	topic: z.string().min(1).max(2e3).optional(),
+	maxFindings: z.number().int().min(1).max(1e3).optional(),
+	minClicksChange: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+	force: z.boolean().default(false)
+}).superRefine((value, context) => {
+	if (Boolean(value.start) !== Boolean(value.end) || value.period === "custom" && !value.start) context.addIssue({
+		code: "custom",
+		path: ["start"],
+		message: "Custom windows require both start and end."
+	});
+	if (value.start && value.end && value.start > value.end) context.addIssue({
+		code: "custom",
+		path: ["end"],
+		message: "The end must be on or after the start."
+	});
+	if (value.reportId === "triage" && (!value.target || !value.targetKind)) context.addIssue({
+		code: "custom",
+		path: ["target"],
+		message: "Triage requires target and targetKind."
+	});
+	if (value.reportId === "pre-publish" && !value.topic) context.addIssue({
+		code: "custom",
+		path: ["topic"],
+		message: "Pre-publish requires topic."
+	});
+	if (value.reportId !== "movers" && value.minClicksChange !== void 0) context.addIssue({
+		code: "custom",
+		path: ["minClicksChange"],
+		message: "minClicksChange applies to movers."
+	});
+});
+const range = z.strictObject({
+	start: z.iso.date(),
+	end: z.iso.date()
+});
+const finding = z.strictObject({
+	entity: z.strictObject({
+		kind: z.enum(["page", "query"]),
+		value: z.string()
+	}),
+	metrics: z.record(z.string(), z.number().finite()),
+	delta: z.strictObject({
+		metric: z.string(),
+		prior: z.number().finite(),
+		current: z.number().finite(),
+		pct: z.number().finite()
+	}).optional(),
+	why: z.string().optional()
+});
+const section = z.strictObject({
+	id: z.string(),
+	title: z.string(),
+	summary: z.strictObject({
+		delta: z.number().finite().optional(),
+		direction: z.enum([
+			"up",
+			"down",
+			"flat"
+		]).optional(),
+		magnitudeLabel: z.string().optional()
+	}),
+	coverage: z.enum(["full", "partial"]),
+	truncated: z.strictObject({
+		kept: z.number().int().nonnegative(),
+		total: z.number().int().nonnegative()
+	}).optional(),
+	dataUnavailable: z.literal(true).optional(),
+	findings: z.array(finding)
+});
+const runReportV1DataSchemas = defineResponseObject({
+	site: z.string().min(1),
+	generatedAt: z.iso.datetime(),
+	cached: z.boolean(),
+	window: range.extend({
+		days: z.number().int().positive(),
+		comparison: range.optional()
+	}),
+	meta: z.strictObject({
+		durationMs: z.number().nonnegative(),
+		rowsScanned: z.number().nonnegative(),
+		degraded: z.boolean(),
+		steps: z.array(z.strictObject({
+			key: z.string(),
+			type: z.string(),
+			status: z.enum([
+				"pending",
+				"running",
+				"done",
+				"skipped",
+				"error"
+			]),
+			error: z.string().optional(),
+			coverage: z.discriminatedUnion("kind", [z.strictObject({ kind: z.literal("complete") }), z.strictObject({
+				kind: z.literal("truncated"),
+				fetched: z.number().int().nonnegative()
+			})]).optional()
+		}))
+	}),
+	sections: z.array(section)
+});
+export { runReportV1DataSchemas, runReportV1RequestSchema };

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

@@ -61,6 +61,11 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "GET";
       readonly template: "/users/{userId}/lifecycle";
     };
+    readonly 'partner.users.integration_activity.get': {
+      readonly surface: "partner";
+      readonly method: "GET";
+      readonly template: "/users/{userId}/integration-activity";
+    };
     readonly 'partner.users.entitlements.get': {
       readonly surface: "partner";
       readonly method: "GET";
@@ -441,6 +446,11 @@ export declare const GSCDUMP_V1_ROUTE_CATALOG: {
       readonly method: "POST";
       readonly template: "/sites/{siteId}/reports";
     };
+    readonly 'analytics.reports.run': {
+      readonly surface: "analytics";
+      readonly method: "POST";
+      readonly template: "/sites/{siteId}/reports/run";
+    };
     readonly 'analytics.reports.detail.query': {
       readonly surface: "analytics";
       readonly method: "POST";

package/dist/v1/route-catalog.mjs

@@ -48,6 +48,11 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "GET",
 			template: "/users/{userId}/lifecycle"
 		},
+		"partner.users.integration_activity.get": {
+			surface: "partner",
+			method: "GET",
+			template: "/users/{userId}/integration-activity"
+		},
 		"partner.users.entitlements.get": {
 			surface: "partner",
 			method: "GET",
@@ -428,6 +433,11 @@ const GSCDUMP_V1_ROUTE_CATALOG = {
 			method: "POST",
 			template: "/sites/{siteId}/reports"
 		},
+		"analytics.reports.run": {
+			surface: "analytics",
+			method: "POST",
+			template: "/sites/{siteId}/reports/run"
+		},
 		"analytics.reports.detail.query": {
 			surface: "analytics",
 			method: "POST",

package/package.json

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