@gscdump/contracts 0.37.7 → 0.38.0

package/dist/v1/index.mjs

@@ -0,0 +1,1440 @@
+import { accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, indexingNextActions, indexingStatuses, lifecycleErrorCodes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "../_chunks/onboarding.mjs";
+import { z } from "zod";
+const HTTP_V1_SURFACES = [
+	"partner",
+	"analytics",
+	"realtime"
+];
+const HTTP_V1_METHODS = [
+	"DELETE",
+	"GET",
+	"PATCH",
+	"POST"
+];
+const HTTP_V1_CREDENTIALS = ["user_key", "partner_key"];
+const HTTP_V1_USER_KEY_SCOPES = [
+	"users:read",
+	"users:write",
+	"sites:read",
+	"sites:write",
+	"analytics:read",
+	"analytics:execute",
+	"indexing:read",
+	"indexing:write",
+	"sitemaps:read",
+	"sitemaps:write",
+	"settings:read",
+	"settings:write",
+	"realtime:connect"
+];
+const HTTP_V1_SCOPES = [
+	...HTTP_V1_USER_KEY_SCOPES,
+	"teams:read",
+	"teams:write"
+];
+const HTTP_V1_CREDENTIAL_SCOPES = {
+	user_key: HTTP_V1_USER_KEY_SCOPES,
+	partner_key: HTTP_V1_SCOPES
+};
+const HTTP_V1_ERROR_CODES = [
+	"invalid_request",
+	"unauthorized",
+	"forbidden",
+	"user_not_found",
+	"site_not_found",
+	"rate_limited",
+	"realtime_unavailable",
+	"internal_error",
+	"contract_violation"
+];
+function pathParameterNames(path) {
+	return [...path.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]);
+}
+function isSafePathTemplate(path) {
+	return /^\/(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?|\{[a-z][A-Za-z0-9]*\})(?:\/(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?|\{[a-z][A-Za-z0-9]*\}))*$/.test(path);
+}
+function objectSchemaKeys(schema) {
+	return schema instanceof z.ZodObject ? Object.keys(schema.shape) : null;
+}
+function assertRequestLocations(request, operationId) {
+	for (const location of [
+		"params",
+		"query",
+		"headers",
+		"body"
+	]) if (!(location in request) || request[location] === void 0) throw new TypeError(`${operationId}: request.${location} must be a schema or null`);
+}
+function assertPathContract(operation) {
+	const names = pathParameterNames(operation.path);
+	if (new Set(names).size !== names.length) throw new TypeError(`${operation.id}: path parameters must be unique`);
+	if (names.length === 0) {
+		if (operation.request.params !== null) throw new TypeError(`${operation.id}: params must be null when the path has no parameters`);
+		return;
+	}
+	if (operation.request.params === null) throw new TypeError(`${operation.id}: path parameters require a params schema`);
+	const schemaKeys = objectSchemaKeys(operation.request.params);
+	if (!schemaKeys) throw new TypeError(`${operation.id}: params must be an object schema`);
+	if (names.join("\0") !== schemaKeys.join("\0")) throw new TypeError(`${operation.id}: params schema keys (${schemaKeys.join(", ")}) must match path order (${names.join(", ")})`);
+}
+function assertOperation(operation) {
+	if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/.test(operation.id)) throw new TypeError(`${operation.id}: operation ID must be a stable dotted lowercase identifier`);
+	if (!isSafePathTemplate(operation.path)) throw new TypeError(`${operation.id}: path must be a safe literal surface-relative template`);
+	assertRequestLocations(operation.request, operation.id);
+	assertPathContract(operation);
+	if (operation.semantics.kind === "query") {
+		if (operation.semantics.sideEffects !== "none") throw new TypeError(`${operation.id}: query operations cannot declare state side effects`);
+		if (!operation.semantics.idempotent) throw new TypeError(`${operation.id}: query operations must be idempotent`);
+		if (operation.semantics.readConsistency === null) throw new TypeError(`${operation.id}: query operations must declare read consistency`);
+	} else {
+		if (operation.semantics.sideEffects !== "state") throw new TypeError(`${operation.id}: mutation operations must declare state side effects`);
+		if (operation.semantics.readConsistency !== null) throw new TypeError(`${operation.id}: mutations cannot declare read consistency`);
+	}
+	if (operation.auth.credentials.includes("user_key") && operation.semantics.kind === "query" && operation.semantics.readConsistency !== "primary") throw new TypeError(`${operation.id}: user_key queries must use primary consistency`);
+	if (operation.semantics.idempotent && operation.semantics.retry !== "idempotent") throw new TypeError(`${operation.id}: idempotent operations must use the idempotent retry policy`);
+	if (!operation.semantics.idempotent && operation.semantics.retry !== "never") throw new TypeError(`${operation.id}: non-idempotent operations cannot be retried automatically`);
+	if (operation.auth.credentials.length === 0 || operation.auth.scopes.length === 0) throw new TypeError(`${operation.id}: auth credentials and scopes are required`);
+	for (const credential of operation.auth.credentials) {
+		const availableScopes = HTTP_V1_CREDENTIAL_SCOPES[credential];
+		const unavailableScope = operation.auth.scopes.find((scope) => !availableScopes.includes(scope));
+		if (unavailableScope) throw new TypeError(`${operation.id}: ${credential} does not grant the ${unavailableScope} scope`);
+	}
+	const ownershipCredentials = operation.auth.ownership.map((ownership) => ownership.credential);
+	if (ownershipCredentials.length !== operation.auth.credentials.length || new Set(ownershipCredentials).size !== ownershipCredentials.length || operation.auth.credentials.some((credential) => !ownershipCredentials.includes(credential))) throw new TypeError(`${operation.id}: every credential requires exactly one ownership rule`);
+	if (operation.errors.length === 0) throw new TypeError(`${operation.id}: declared stable errors are required`);
+	if (!operation.errorResponse?.producer || !operation.errorResponse.client) throw new TypeError(`${operation.id}: an operation-specific error response schema is required`);
+	if (Object.keys(operation.responses).length === 0) throw new TypeError(`${operation.id}: at least one response is required`);
+	const pathParameters = new Set(pathParameterNames(operation.path));
+	for (const reference of [...operation.resources.reads, ...operation.resources.changes]) if (reference.idFrom.startsWith("params.") && !pathParameters.has(reference.idFrom.slice(7))) throw new TypeError(`${operation.id}: resource reference ${reference.idFrom} is not a declared path parameter`);
+	if (operation.docs.summary.length === 0 || operation.docs.description.length === 0 || operation.docs.tags.length === 0) throw new TypeError(`${operation.id}: public documentation metadata is incomplete`);
+}
+function defineHttpOperation(operation) {
+	assertOperation(operation);
+	return operation;
+}
+function defineHttpSurface(surface) {
+	if (surface.prefix !== `/api/${surface.name}/v1`) throw new TypeError(`${surface.name}: prefix must retain the surface and v1 major`);
+	if (surface.version !== "1.0") throw new TypeError(`${surface.name}: wire version must be 1.0`);
+	const ids = /* @__PURE__ */ new Set();
+	const routes = /* @__PURE__ */ new Set();
+	for (const [key, operation] of Object.entries(surface.operations)) {
+		assertOperation(operation);
+		if (!operation.id.startsWith(`${surface.name}.`)) throw new TypeError(`${surface.name}: operation ID ${operation.id} must use the surface namespace`);
+		if (ids.has(operation.id)) throw new TypeError(`${surface.name}: duplicate operation ID ${operation.id}`);
+		ids.add(operation.id);
+		const route = `${operation.method} ${operation.path}`;
+		if (routes.has(route)) throw new TypeError(`${surface.name}: duplicate method/path ${route}`);
+		routes.add(route);
+		if (key.length === 0) throw new TypeError(`${surface.name}: operation registry keys cannot be empty`);
+	}
+	return surface;
+}
+function defineResponseObject(producerShape, clientShape) {
+	return {
+		producer: z.strictObject(producerShape),
+		client: z.looseObject(clientShape ?? producerShape)
+	};
+}
+function defineSuccessResponse(data, meta) {
+	return defineResponseObject({
+		data: data.producer,
+		meta: meta.producer
+	}, {
+		data: data.client,
+		meta: meta.client
+	});
+}
+function buildHttpOperationPath(surface, operation, params) {
+	if (!operation.id.startsWith(`${surface.name}.`)) throw new TypeError(`${operation.id}: operation does not belong to the ${surface.name} surface`);
+	if (pathParameterNames(operation.path).length === 0) {
+		if (params !== void 0 && params !== null && (typeof params !== "object" || Object.keys(params).length > 0)) throw new TypeError(`${operation.id}: this operation has no path parameters`);
+		return `${surface.prefix}${operation.path}`;
+	}
+	if (operation.request.params === null) throw new TypeError(`${operation.id}: operation has an invalid path contract`);
+	const parsed = operation.request.params.parse(params);
+	const relativePath = operation.path.replace(/\{([^{}]+)\}/g, (_match, name) => {
+		const value = parsed[name];
+		if (typeof value !== "string" && typeof value !== "number") throw new TypeError(`${operation.id}: path parameter ${name} must serialize as a string or number`);
+		const serialized = String(value);
+		if (serialized.length === 0 || serialized === "." || serialized === "..") throw new TypeError(`${operation.id}: path parameter ${name} cannot serialize as an empty or dot segment`);
+		return encodeURIComponent(serialized);
+	});
+	return `${surface.prefix}${relativePath}`;
+}
+const GSCDUMP_REALTIME_PROTOCOL_VERSION = 1;
+const GSCDUMP_REALTIME_SUBPROTOCOL = "gscdump.v1";
+const GSCDUMP_REALTIME_TICKET_PREFIX = "gscdump.ticket.v1";
+const GSCDUMP_REALTIME_TICKET_ISSUER = "https://gscdump.com";
+const GSCDUMP_REALTIME_TICKET_AUDIENCE = "https://gscdump.com/ws/v1";
+const GSCDUMP_REALTIME_PING = "ping";
+const GSCDUMP_REALTIME_PONG = "pong";
+const GSCDUMP_REALTIME_TICKET_TTL_SECONDS = 60;
+const GSCDUMP_REALTIME_MAX_CONNECTION_SECONDS = 900;
+const GSCDUMP_REALTIME_TICKET_POLICY = {
+	algorithm: "HMAC-SHA-256",
+	minimumSigningKeyBytes: 32,
+	jtiRandomBits: 128,
+	maxVerificationKeys: 2,
+	futureIssuedAtToleranceMs: 5e3,
+	expiryToleranceMs: 0,
+	rotationOverlapMs: 9e4,
+	maxBytes: 2048,
+	singleUse: true
+};
+const GSCDUMP_REALTIME_CONNECTION_POLICY = {
+	helloDeadlineMs: 1e4,
+	maxLifetimeMs: 9e5,
+	connectionRefreshBeforeExpiryMs: 3e4,
+	heartbeatIntervalMs: 25e3,
+	staleAfterMs: 75e3,
+	reconnectBaseDelayMs: 1e3,
+	reconnectMaxDelayMs: 3e4,
+	reconnectJitter: "equal"
+};
+const GSCDUMP_REALTIME_REPLAY_POLICY = {
+	maxAgeMs: 864e5,
+	maxEventsPerStream: 1e4
+};
+const GSCDUMP_REALTIME_LIMITS = {
+	clientFrameMaxBytes: 16384,
+	durableEventMaxBytes: 65536,
+	ephemeralEventMaxBytes: 16384,
+	outboundFrameMaxBytes: 262144,
+	batchMaxEvents: 20,
+	batchMaxBytes: 262144,
+	connectionAttachmentMaxBytes: 2048
+};
+const GSCDUMP_REALTIME_ACK_POLICY = {
+	softLagEvents: 100,
+	softLagBytes: 1048576,
+	hardLagEvents: 500,
+	hardLagBytes: 4194304,
+	hardLagCloseCode: 1013,
+	effectRetryBeforeUnsafeResync: 3
+};
+const GSCDUMP_REALTIME_CLOSE_CODES = {
+	normal: 1e3,
+	protocolError: 1002,
+	policyViolation: 1008,
+	internalError: 1011,
+	serviceRestart: 1012,
+	overloadedOrAckLag: 1013,
+	maximumLifetime: 4001
+};
+const REALTIME_V1_RESOURCE_TYPES = [
+	"partner.user",
+	"partner.team",
+	"user.sites",
+	"site.registration",
+	"site.lifecycle",
+	"site.analytics",
+	"site.sitemaps",
+	"site.indexing",
+	"site.auth"
+];
+const REALTIME_V1_EVENT_NAMES = [
+	"user.lifecycle.changed",
+	"site.lifecycle.changed",
+	"site.lifecycle.progress",
+	"site.analytics.ready",
+	"site.sitemaps.ready",
+	"site.indexing.ready",
+	"site.auth.failed",
+	"site.lifecycle.failed",
+	"site.registration.changed"
+];
+const REALTIME_V1_EVENT_SEMANTICS = {
+	"user.lifecycle.changed": {
+		delivery: "durable",
+		baseChanges: ["partner.user", "user.sites"]
+	},
+	"site.lifecycle.changed": {
+		delivery: "durable",
+		baseChanges: ["site.lifecycle"]
+	},
+	"site.lifecycle.progress": {
+		delivery: "ephemeral",
+		baseChanges: []
+	},
+	"site.analytics.ready": {
+		delivery: "durable",
+		baseChanges: ["site.analytics", "site.lifecycle"]
+	},
+	"site.sitemaps.ready": {
+		delivery: "durable",
+		baseChanges: ["site.sitemaps", "site.lifecycle"]
+	},
+	"site.indexing.ready": {
+		delivery: "durable",
+		baseChanges: ["site.indexing", "site.lifecycle"]
+	},
+	"site.auth.failed": {
+		delivery: "durable",
+		baseChanges: ["site.auth", "site.lifecycle"]
+	},
+	"site.lifecycle.failed": {
+		delivery: "durable",
+		baseChanges: ["site.lifecycle"]
+	},
+	"site.registration.changed": {
+		delivery: "durable",
+		baseChanges: ["site.registration", "user.sites"]
+	}
+};
+function createRealtimeV1Schemas() {
+	const sequence = z.string().regex(/^(0|[1-9]\d*)$/);
+	const opaquePublicId = z.string().regex(/^[\w-]+$/);
+	const publicUserId = z.string().regex(/^u_[\w-]+$/);
+	const publicPartnerId = z.string().regex(/^p_[\w-]+$/);
+	const publicTeamId = z.string().regex(/^t_[\w-]+$/);
+	const publicSiteId = z.string().regex(/^s_[\w-]+$/);
+	const publicPrincipalId = z.union([publicUserId, publicPartnerId]);
+	const publicResourceId = z.union([
+		publicUserId,
+		publicPartnerId,
+		publicTeamId,
+		publicSiteId
+	]);
+	const publicRequestId = z.string().regex(/^req_[\w-]+$/);
+	const publicEventId = z.string().regex(/^evt_[\w-]+$/);
+	const userStreamId = z.string().regex(/^user:u_[\w-]+$/);
+	const partnerStreamId = z.string().regex(/^partner:p_[\w-]+$/);
+	const streamId = z.union([userStreamId, partnerStreamId]);
+	const origin = z.url().refine((value) => {
+		const parsed = new URL(value);
+		return (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.origin === value;
+	}, "origin must be an exact HTTP(S) origin without a path, query, or fragment.");
+	const cursor = z.strictObject({
+		streamId,
+		sequence
+	});
+	const streamHead = z.strictObject({
+		streamId,
+		sequence
+	});
+	const ticketRequest = z.strictObject({ origin: origin.optional() });
+	const ticketClaims = z.strictObject({
+		v: z.literal(1),
+		iss: z.literal(GSCDUMP_REALTIME_TICKET_ISSUER),
+		aud: z.literal(GSCDUMP_REALTIME_TICKET_AUDIENCE),
+		kid: z.string().regex(/^[\w-]{1,128}$/),
+		jti: z.string().regex(/^[\w-]{22,}$/),
+		iat: z.number().int().nonnegative(),
+		exp: z.number().int().positive(),
+		connectionExpiresAt: z.number().int().positive(),
+		principalClass: z.enum(["user_key", "partner_key"]),
+		principalPublicId: publicPrincipalId,
+		streamId,
+		origin: origin.nullable()
+	}).superRefine((claims, context) => {
+		if (claims.exp <= claims.iat || claims.exp - claims.iat > 60) context.addIssue({
+			code: "custom",
+			message: `exp must be after iat and no more than 60 seconds later.`,
+			path: ["exp"]
+		});
+		if (claims.connectionExpiresAt <= claims.iat || claims.connectionExpiresAt - claims.iat > 900) context.addIssue({
+			code: "custom",
+			message: `connectionExpiresAt must be after iat and no more than 900 seconds later.`,
+			path: ["connectionExpiresAt"]
+		});
+		if (claims.connectionExpiresAt < claims.exp) context.addIssue({
+			code: "custom",
+			message: "connectionExpiresAt cannot be earlier than exp.",
+			path: ["connectionExpiresAt"]
+		});
+		const expectedStream = claims.principalClass === "user_key" ? `user:${claims.principalPublicId}` : `partner:${claims.principalPublicId}`;
+		if (claims.streamId !== expectedStream) context.addIssue({
+			code: "custom",
+			message: "streamId must be the exact stream inferred from principalClass and principalPublicId.",
+			path: ["streamId"]
+		});
+		if (claims.principalClass === "user_key" && !claims.principalPublicId.startsWith("u_")) context.addIssue({
+			code: "custom",
+			message: "A user principal requires a user public ID.",
+			path: ["principalPublicId"]
+		});
+		if (claims.principalClass === "partner_key" && !claims.principalPublicId.startsWith("p_")) context.addIssue({
+			code: "custom",
+			message: "A partner principal requires a partner public ID.",
+			path: ["principalPublicId"]
+		});
+	});
+	const knownResourceType = z.enum(REALTIME_V1_RESOURCE_TYPES);
+	const resourceChange = z.strictObject({
+		type: z.string().regex(/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/),
+		id: opaquePublicId,
+		kind: z.enum([
+			"created",
+			"updated",
+			"deleted"
+		])
+	}).superRefine((change, context) => {
+		const prefix = change.type === "partner.user" || change.type === "user.sites" ? "u_" : change.type === "partner.team" ? "t_" : REALTIME_V1_RESOURCE_TYPES.includes(change.type) && change.type.startsWith("site.") ? "s_" : null;
+		if (prefix && !change.id.startsWith(prefix)) context.addIssue({
+			code: "custom",
+			message: `${change.type} requires an opaque ${prefix} public ID.`,
+			path: ["id"]
+		});
+	});
+	const subject = z.discriminatedUnion("type", [
+		z.strictObject({
+			type: z.literal("partner"),
+			id: publicPartnerId
+		}),
+		z.strictObject({
+			type: z.literal("team"),
+			id: publicTeamId
+		}),
+		z.strictObject({
+			type: z.literal("user"),
+			id: publicUserId
+		}),
+		z.strictObject({
+			type: z.literal("site"),
+			id: publicSiteId
+		})
+	]);
+	const eventBase = {
+		type: z.literal("event"),
+		protocolVersion: z.literal(1),
+		eventVersion: z.number().int().positive(),
+		id: publicEventId,
+		name: z.string().regex(/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/),
+		subject,
+		changes: z.array(resourceChange),
+		occurredAt: z.iso.datetime(),
+		correlationId: publicRequestId.nullable(),
+		data: z.json()
+	};
+	const durableEvent = z.strictObject({
+		...eventBase,
+		cursor,
+		changes: z.array(resourceChange).min(1),
+		delivery: z.literal("durable")
+	}).superRefine((event, context) => {
+		const semantics = REALTIME_V1_EVENT_SEMANTICS[event.name];
+		if (semantics?.delivery === "ephemeral") context.addIssue({
+			code: "custom",
+			message: `${event.name} must use ephemeral delivery.`,
+			path: ["delivery"]
+		});
+		if (semantics) {
+			for (const requiredType of semantics.baseChanges) if (!event.changes.some((change) => change.type === requiredType)) context.addIssue({
+				code: "custom",
+				message: `${event.name} requires a ${requiredType} base change.`,
+				path: ["changes"]
+			});
+		}
+	});
+	const ephemeralEvent = z.strictObject({
+		...eventBase,
+		cursor: z.null(),
+		changes: z.array(resourceChange).max(0),
+		delivery: z.literal("ephemeral")
+	}).superRefine((event, context) => {
+		if (REALTIME_V1_EVENT_SEMANTICS[event.name]?.delivery === "durable") context.addIssue({
+			code: "custom",
+			message: `${event.name} must use durable delivery.`,
+			path: ["delivery"]
+		});
+	});
+	const event = z.union([durableEvent, ephemeralEvent]);
+	const helloFrame = z.strictObject({
+		type: z.literal("hello"),
+		protocolVersion: z.literal(1),
+		sdkVersion: z.string().min(1),
+		resume: cursor.nullable()
+	});
+	const ackFrame = z.strictObject({
+		type: z.literal("ack"),
+		cursor
+	});
+	const readyFrame = z.strictObject({
+		type: z.literal("ready"),
+		protocolVersion: z.literal(1),
+		connectionId: z.string().regex(/^conn_[\w-]+$/),
+		streamId,
+		replayFloor: streamHead,
+		head: streamHead,
+		limits: z.strictObject({
+			maxBatchEvents: z.number().int().positive().max(GSCDUMP_REALTIME_LIMITS.batchMaxEvents),
+			maxUnackedEvents: z.number().int().positive().max(GSCDUMP_REALTIME_ACK_POLICY.hardLagEvents)
+		}),
+		heartbeat: z.strictObject({
+			ping: z.literal(GSCDUMP_REALTIME_PING),
+			pong: z.literal(GSCDUMP_REALTIME_PONG)
+		}),
+		expiresAt: z.iso.datetime()
+	}).superRefine((frame, context) => {
+		if (frame.head.streamId !== frame.streamId || frame.replayFloor.streamId !== frame.streamId) context.addIssue({
+			code: "custom",
+			message: "ready head and replayFloor must match streamId."
+		});
+		if (BigInt(frame.replayFloor.sequence) > BigInt(frame.head.sequence)) context.addIssue({
+			code: "custom",
+			message: "replayFloor cannot be ahead of head.",
+			path: ["replayFloor"]
+		});
+	});
+	const replayBeginFrame = z.strictObject({
+		type: z.literal("replay.begin"),
+		after: cursor.nullable(),
+		through: cursor
+	}).superRefine((frame, context) => {
+		if (!frame.after) return;
+		if (frame.after.streamId !== frame.through.streamId) context.addIssue({
+			code: "custom",
+			message: "Replay cursors must belong to one stream.",
+			path: ["through"]
+		});
+		if (BigInt(frame.after.sequence) > BigInt(frame.through.sequence)) context.addIssue({
+			code: "custom",
+			message: "Replay through cannot be behind after.",
+			path: ["through"]
+		});
+	});
+	const replayEndFrame = z.strictObject({
+		type: z.literal("replay.end"),
+		through: cursor
+	});
+	const batchFrame = z.strictObject({
+		type: z.literal("batch"),
+		events: z.array(durableEvent).min(1).max(GSCDUMP_REALTIME_LIMITS.batchMaxEvents)
+	}).superRefine((frame, context) => {
+		const first = frame.events[0];
+		if (!first) return;
+		for (const [index, current] of frame.events.entries()) {
+			if (current.cursor.streamId !== first.cursor.streamId) context.addIssue({
+				code: "custom",
+				message: "A batch must contain events from one exact stream.",
+				path: [
+					"events",
+					index,
+					"cursor",
+					"streamId"
+				]
+			});
+			const previous = frame.events[index - 1];
+			if (previous && BigInt(current.cursor.sequence) !== BigInt(previous.cursor.sequence) + 1n) context.addIssue({
+				code: "custom",
+				message: "Batch cursors must be contiguous and ordered.",
+				path: [
+					"events",
+					index,
+					"cursor",
+					"sequence"
+				]
+			});
+		}
+	});
+	const resyncRequiredFrame = z.strictObject({
+		type: z.literal("resync.required"),
+		reason: z.enum([
+			"cursor_expired",
+			"retention_gap",
+			"sequence_gap",
+			"stream_mismatch"
+		]),
+		scope: z.strictObject({
+			type: z.literal("stream"),
+			streamId
+		}),
+		resumeAfter: cursor
+	}).superRefine((frame, context) => {
+		if (frame.scope.streamId !== frame.resumeAfter.streamId) context.addIssue({
+			code: "custom",
+			message: "resync.required scope and resumeAfter must identify one exact stream.",
+			path: ["resumeAfter", "streamId"]
+		});
+	});
+	const realtimeErrorFrame = z.strictObject({
+		type: z.literal("error"),
+		error: z.strictObject({
+			code: z.enum([
+				"invalid_frame",
+				"protocol_mismatch",
+				"policy_violation",
+				"overloaded",
+				"internal_error"
+			]),
+			message: z.string().min(1),
+			retryable: z.boolean(),
+			retryAfter: z.number().int().nonnegative().optional()
+		})
+	});
+	return {
+		opaquePublicId,
+		userStreamId,
+		partnerStreamId,
+		publicUserId,
+		publicPartnerId,
+		publicTeamId,
+		publicSiteId,
+		publicPrincipalId,
+		publicResourceId,
+		publicRequestId,
+		publicEventId,
+		sequence,
+		streamId,
+		cursor,
+		streamHead,
+		ticketRequest,
+		ticketClaims,
+		knownResourceType,
+		resourceChange,
+		subject,
+		durableEvent,
+		ephemeralEvent,
+		event,
+		helloFrame,
+		ackFrame,
+		readyFrame,
+		replayBeginFrame,
+		replayEndFrame,
+		batchFrame,
+		resyncRequiredFrame,
+		realtimeErrorFrame,
+		clientFrame: z.union([helloFrame, ackFrame]),
+		serverFrame: z.union([
+			readyFrame,
+			replayBeginFrame,
+			replayEndFrame,
+			event,
+			batchFrame,
+			resyncRequiredFrame,
+			realtimeErrorFrame
+		])
+	};
+}
+const GSCDUMP_HTTP_V1_VERSION = "1.0";
+function errorEnvelopeSchemas(codes, publicRequestId) {
+	const errorDetails = z.record(z.string(), z.json());
+	const producer = z.strictObject({
+		code: z.enum(codes),
+		message: z.string().min(1),
+		requestId: publicRequestId,
+		retryable: z.boolean(),
+		details: errorDetails
+	});
+	const client = z.looseObject({
+		code: z.enum(codes),
+		message: z.string().min(1),
+		requestId: publicRequestId,
+		retryable: z.boolean(),
+		details: errorDetails
+	});
+	return defineResponseObject({ error: producer }, { error: client });
+}
+function lifecycleResponseSchemas(ids) {
+	const progress = defineResponseObject({
+		completed: z.number().int().nonnegative(),
+		failed: z.number().int().nonnegative(),
+		total: z.number().int().nonnegative(),
+		percent: z.number().min(0).max(100)
+	});
+	const latestError = defineResponseObject({
+		code: z.enum(lifecycleErrorCodes),
+		message: z.string(),
+		retryable: z.boolean()
+	});
+	const account = defineResponseObject({
+		status: z.enum(accountStatuses),
+		grantedScopes: z.array(z.string()),
+		missingScopes: z.array(z.string()),
+		nextAction: z.enum(accountNextActions)
+	});
+	const property = defineResponseObject({
+		status: z.enum(propertyStatuses),
+		nextAction: z.enum(propertyNextActions)
+	});
+	const syncedRange = defineResponseObject({
+		oldest: z.iso.date().nullable(),
+		newest: z.iso.date().nullable()
+	});
+	const analytics = defineResponseObject({
+		status: z.enum(analyticsStatuses),
+		progress: progress.producer,
+		queryable: z.boolean(),
+		sourceMode: z.enum(querySourceModes),
+		syncedRange: syncedRange.producer,
+		nextAction: z.enum(analyticsNextActions)
+	}, {
+		status: z.enum(analyticsStatuses),
+		progress: progress.client,
+		queryable: z.boolean(),
+		sourceMode: z.enum(querySourceModes),
+		syncedRange: syncedRange.client,
+		nextAction: z.enum(analyticsNextActions)
+	});
+	const sitemaps = defineResponseObject({
+		status: z.enum(sitemapStatuses),
+		discoveredCount: z.number().int().nonnegative(),
+		nextAction: z.enum(sitemapNextActions)
+	});
+	const indexing = defineResponseObject({
+		status: z.enum(indexingStatuses),
+		eligible: z.boolean(),
+		reason: z.string().nullable(),
+		progress: progress.producer,
+		nextAction: z.enum(indexingNextActions)
+	}, {
+		status: z.enum(indexingStatuses),
+		eligible: z.boolean(),
+		reason: z.string().nullable(),
+		progress: progress.client,
+		nextAction: z.enum(indexingNextActions)
+	});
+	const site = defineResponseObject({
+		siteId: ids.publicSiteId,
+		externalSiteId: z.string().nullable(),
+		requestedUrl: z.string().min(1),
+		gscPropertyUrl: z.string().nullable(),
+		permissionLevel: z.string().nullable(),
+		property: property.producer,
+		analytics: analytics.producer,
+		sitemaps: sitemaps.producer,
+		indexing: indexing.producer,
+		latestError: latestError.producer.nullable(),
+		updatedAt: z.iso.datetime()
+	}, {
+		siteId: ids.publicSiteId,
+		externalSiteId: z.string().nullable(),
+		requestedUrl: z.string().min(1),
+		gscPropertyUrl: z.string().nullable(),
+		permissionLevel: z.string().nullable(),
+		property: property.client,
+		analytics: analytics.client,
+		sitemaps: sitemaps.client,
+		indexing: indexing.client,
+		latestError: latestError.client.nullable(),
+		updatedAt: z.iso.datetime()
+	});
+	return defineResponseObject({
+		userId: ids.publicUserId,
+		partnerId: ids.publicPartnerId.nullable(),
+		currentTeamId: ids.publicTeamId.nullable(),
+		account: account.producer,
+		sites: z.array(site.producer)
+	}, {
+		userId: ids.publicUserId,
+		partnerId: ids.publicPartnerId.nullable(),
+		currentTeamId: ids.publicTeamId.nullable(),
+		account: account.client,
+		sites: z.array(site.client)
+	});
+}
+function createGscdumpV1Protocol() {
+	const realtimeSchemas = createRealtimeV1Schemas();
+	const surfaceSchema = z.enum([
+		"partner",
+		"analytics",
+		"realtime"
+	]);
+	const responseMeta = defineResponseObject({
+		requestId: realtimeSchemas.publicRequestId,
+		surface: surfaceSchema,
+		version: z.literal("1.0")
+	});
+	const partnerResponseMeta = defineResponseObject({
+		requestId: realtimeSchemas.publicRequestId,
+		surface: z.literal("partner"),
+		version: z.literal("1.0")
+	});
+	const realtimeResponseMeta = defineResponseObject({
+		requestId: realtimeSchemas.publicRequestId,
+		surface: z.literal("realtime"),
+		version: z.literal("1.0")
+	});
+	const requestMetadata = z.strictObject({
+		requestId: realtimeSchemas.publicRequestId,
+		surface: surfaceSchema,
+		version: z.literal("1.0")
+	});
+	const requestHeaders = z.strictObject({ "x-request-id": realtimeSchemas.publicRequestId.optional() });
+	const errorEnvelope = errorEnvelopeSchemas(HTTP_V1_ERROR_CODES, realtimeSchemas.publicRequestId);
+	const lifecycleResponse = defineSuccessResponse(lifecycleResponseSchemas(realtimeSchemas), partnerResponseMeta);
+	const dimensions = [
+		"page",
+		"query",
+		"queryCanonical",
+		"country",
+		"device",
+		"date",
+		"searchAppearance",
+		"hour"
+	];
+	const metrics = [
+		"clicks",
+		"impressions",
+		"ctr",
+		"position"
+	];
+	const filterDimension = z.enum([
+		...dimensions,
+		...metrics,
+		"searchType"
+	]);
+	const normalizedFilterLeaf = z.union([z.strictObject({
+		dimension: filterDimension,
+		operator: z.enum([
+			"equals",
+			"notEquals",
+			"contains",
+			"notContains",
+			"includingRegex",
+			"excludingRegex",
+			"gte",
+			"gt",
+			"lte",
+			"lt",
+			"metricGte",
+			"metricGt",
+			"metricLte",
+			"metricLt",
+			"topLevel"
+		]),
+		expression: z.string()
+	}), z.strictObject({
+		dimension: filterDimension,
+		operator: z.enum(["between", "metricBetween"]),
+		expression: z.string(),
+		expression2: z.string()
+	})]);
+	const normalizedFilter = z.lazy(() => z.union([z.strictObject({
+		_filters: z.array(normalizedFilterLeaf).min(1),
+		_nestedGroups: z.array(normalizedFilter).optional(),
+		_groupType: z.enum(["and", "or"]).optional()
+	}), z.strictObject({
+		_filters: z.array(normalizedFilterLeaf).max(0),
+		_nestedGroups: z.array(normalizedFilter).min(1),
+		_groupType: z.enum(["and", "or"]).optional()
+	})]));
+	const analyticsRowsRequest = z.strictObject({
+		dimensions: z.array(z.enum(dimensions)).min(1),
+		metrics: z.array(z.enum(metrics)).optional(),
+		filter: normalizedFilter.optional(),
+		prefilter: normalizedFilter.optional(),
+		orderBy: z.strictObject({
+			column: z.enum([...metrics, "date"]),
+			dir: z.enum(["asc", "desc"])
+		}).optional(),
+		rowLimit: z.number().int().positive().max(25e3).optional(),
+		startRow: z.number().int().nonnegative().optional(),
+		dataState: z.enum([
+			"final",
+			"all",
+			"hourly_all"
+		]).optional(),
+		aggregationType: z.enum([
+			"auto",
+			"byPage",
+			"byProperty",
+			"byNewsShowcasePanel"
+		]).optional(),
+		searchType: z.enum([
+			"web",
+			"image",
+			"video",
+			"news",
+			"discover",
+			"googleNews"
+		]).optional()
+	});
+	const analyticsRowsResponse = defineSuccessResponse(defineResponseObject({ rows: z.array(z.record(z.string(), z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null()
+	]))) }), defineResponseObject({
+		requestId: realtimeSchemas.publicRequestId,
+		surface: z.literal("analytics"),
+		version: z.literal("1.0"),
+		sourceName: z.string().min(1),
+		sourceKind: z.enum(["row", "sql"]),
+		queryMs: z.number().nonnegative()
+	}));
+	const responseStreamHead = defineResponseObject({
+		streamId: realtimeSchemas.streamId,
+		sequence: realtimeSchemas.sequence
+	});
+	const headResponse = defineSuccessResponse(defineResponseObject({ head: responseStreamHead.producer }, { head: responseStreamHead.client }), realtimeResponseMeta);
+	const ticketDataProducerShape = {
+		socketUrl: z.url().refine((value) => value.startsWith("wss://"), "socketUrl must use wss."),
+		protocol: z.literal(GSCDUMP_REALTIME_SUBPROTOCOL),
+		protocolVersion: z.literal(1),
+		ticket: z.string().max(GSCDUMP_REALTIME_TICKET_POLICY.maxBytes).regex(/^gscdump\.ticket\.v1\.[\w-]+\.[\w-]+$/),
+		expiresAt: z.iso.datetime(),
+		head: responseStreamHead.producer,
+		maxConnectionSeconds: z.literal(900)
+	};
+	const ticketResponse = defineSuccessResponse(defineResponseObject(ticketDataProducerShape, {
+		...ticketDataProducerShape,
+		head: responseStreamHead.client
+	}), realtimeResponseMeta);
+	const partnerUserLifecycleErrors = [
+		"invalid_request",
+		"unauthorized",
+		"forbidden",
+		"user_not_found",
+		"rate_limited",
+		"internal_error",
+		"contract_violation"
+	];
+	const analyticsRowsErrors = [
+		"invalid_request",
+		"unauthorized",
+		"forbidden",
+		"site_not_found",
+		"rate_limited",
+		"internal_error",
+		"contract_violation"
+	];
+	const realtimeErrors = [
+		"invalid_request",
+		"unauthorized",
+		"forbidden",
+		"rate_limited",
+		"realtime_unavailable",
+		"internal_error",
+		"contract_violation"
+	];
+	const partner = defineHttpSurface({
+		name: "partner",
+		prefix: "/api/partner/v1",
+		version: "1.0",
+		operations: { getUserLifecycle: defineHttpOperation({
+			id: "partner.users.lifecycle.get",
+			method: "GET",
+			path: "/users/{userId}/lifecycle",
+			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: lifecycleResponse },
+			errors: partnerUserLifecycleErrors,
+			errorResponse: errorEnvelopeSchemas(partnerUserLifecycleErrors, realtimeSchemas.publicRequestId),
+			resources: {
+				reads: [{
+					type: "partner.user",
+					idFrom: "params.userId"
+				}, {
+					type: "user.sites",
+					idFrom: "params.userId"
+				}],
+				changes: []
+			},
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Get user lifecycle",
+				description: "Returns the authoritative lifecycle state for one visible user and their sites.",
+				tags: ["Users"],
+				examples: {
+					request: { params: { userId: "u_01" } },
+					response: {
+						data: {
+							userId: "u_01",
+							partnerId: "p_01",
+							currentTeamId: null,
+							account: {
+								status: "ready",
+								grantedScopes: ["https://www.googleapis.com/auth/webmasters.readonly"],
+								missingScopes: [],
+								nextAction: "none"
+							},
+							sites: []
+						},
+						meta: {
+							requestId: "req_01",
+							surface: "partner",
+							version: "1.0"
+						}
+					}
+				}
+			}
+		}) }
+	});
+	const analytics = defineHttpSurface({
+		name: "analytics",
+		prefix: "/api/analytics/v1",
+		version: "1.0",
+		operations: { queryRows: defineHttpOperation({
+			id: "analytics.rows.query",
+			method: "POST",
+			path: "/sites/{siteId}/rows",
+			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: analyticsRowsRequest
+			},
+			responses: { 200: analyticsRowsResponse },
+			errors: analyticsRowsErrors,
+			errorResponse: errorEnvelopeSchemas(analyticsRowsErrors, realtimeSchemas.publicRequestId),
+			resources: {
+				reads: [{
+					type: "site.analytics",
+					idFrom: "params.siteId"
+				}],
+				changes: []
+			},
+			lifecycle: { introduced: "1.0.0" },
+			docs: {
+				summary: "Query analytics rows",
+				description: "Executes an idempotent primary-consistent analytics row query.",
+				tags: ["Analytics rows"],
+				examples: {
+					request: {
+						params: { siteId: "s_01" },
+						body: {
+							dimensions: ["query"],
+							metrics: ["clicks", "impressions"],
+							rowLimit: 100
+						}
+					},
+					response: {
+						data: { rows: [] },
+						meta: {
+							requestId: "req_01",
+							surface: "analytics",
+							version: "1.0",
+							sourceName: "primary",
+							sourceKind: "sql",
+							queryMs: 12
+						}
+					}
+				}
+			}
+		}) }
+	});
+	const realtime = defineHttpSurface({
+		name: "realtime",
+		prefix: "/api/realtime/v1",
+		version: "1.0",
+		operations: {
+			getStreamHead: defineHttpOperation({
+				id: "realtime.stream.head.get",
+				method: "GET",
+				path: "/stream/head",
+				visibility: "public",
+				semantics: {
+					kind: "query",
+					sideEffects: "none",
+					idempotent: true,
+					retry: "idempotent",
+					readConsistency: "primary"
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["realtime:connect"],
+					ownership: [{
+						credential: "user_key",
+						rule: "principal_stream"
+					}, {
+						credential: "partner_key",
+						rule: "principal_stream"
+					}]
+				},
+				request: {
+					params: null,
+					query: null,
+					headers: requestHeaders,
+					body: null
+				},
+				responses: { 200: headResponse },
+				errors: realtimeErrors,
+				errorResponse: errorEnvelopeSchemas(realtimeErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [],
+					changes: []
+				},
+				lifecycle: { introduced: "1.0.0" },
+				docs: {
+					summary: "Get the inferred stream head",
+					description: "Returns the current durable head for the credential's one exact stream.",
+					tags: ["Realtime"],
+					examples: {
+						request: {},
+						response: {
+							data: { head: {
+								streamId: "user:u_01",
+								sequence: "142"
+							} },
+							meta: {
+								requestId: "req_01",
+								surface: "realtime",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			}),
+			createTicket: defineHttpOperation({
+				id: "realtime.tickets.create",
+				method: "POST",
+				path: "/tickets",
+				visibility: "public",
+				semantics: {
+					kind: "mutation",
+					sideEffects: "state",
+					idempotent: false,
+					retry: "never",
+					readConsistency: null
+				},
+				auth: {
+					credentials: ["user_key", "partner_key"],
+					scopes: ["realtime:connect"],
+					ownership: [{
+						credential: "user_key",
+						rule: "principal_stream"
+					}, {
+						credential: "partner_key",
+						rule: "principal_stream"
+					}]
+				},
+				request: {
+					params: null,
+					query: null,
+					headers: requestHeaders,
+					body: realtimeSchemas.ticketRequest
+				},
+				responses: { 201: ticketResponse },
+				errors: realtimeErrors,
+				errorResponse: errorEnvelopeSchemas(realtimeErrors, realtimeSchemas.publicRequestId),
+				resources: {
+					reads: [],
+					changes: []
+				},
+				lifecycle: { introduced: "1.0.0" },
+				docs: {
+					summary: "Create a realtime ticket",
+					description: "Creates a short-lived single-use ticket for the credential's inferred stream.",
+					tags: ["Realtime"],
+					examples: {
+						request: { body: { origin: "https://nuxtseo.com" } },
+						response: {
+							data: {
+								socketUrl: "wss://gscdump.com/ws/v1",
+								protocol: GSCDUMP_REALTIME_SUBPROTOCOL,
+								protocolVersion: 1,
+								ticket: "gscdump.ticket.v1.cGF5bG9hZA.c2lnbmF0dXJl",
+								expiresAt: "2026-07-14T08:01:00.000Z",
+								head: {
+									streamId: "user:u_01",
+									sequence: "142"
+								},
+								maxConnectionSeconds: 900
+							},
+							meta: {
+								requestId: "req_01",
+								surface: "realtime",
+								version: "1.0"
+							}
+						}
+					}
+				}
+			})
+		}
+	});
+	return {
+		constants: {
+			httpVersion: "1.0",
+			realtimeProtocolVersion: 1,
+			realtimeSubprotocol: GSCDUMP_REALTIME_SUBPROTOCOL,
+			realtimeTicketPrefix: GSCDUMP_REALTIME_TICKET_PREFIX,
+			realtimeTicketIssuer: GSCDUMP_REALTIME_TICKET_ISSUER,
+			realtimeTicketAudience: GSCDUMP_REALTIME_TICKET_AUDIENCE,
+			ping: GSCDUMP_REALTIME_PING,
+			pong: GSCDUMP_REALTIME_PONG,
+			ticketTtlSeconds: 60,
+			maxConnectionSeconds: 900,
+			ticketPolicy: GSCDUMP_REALTIME_TICKET_POLICY,
+			connectionPolicy: GSCDUMP_REALTIME_CONNECTION_POLICY,
+			replayPolicy: GSCDUMP_REALTIME_REPLAY_POLICY,
+			limits: GSCDUMP_REALTIME_LIMITS,
+			ackPolicy: GSCDUMP_REALTIME_ACK_POLICY,
+			closeCodes: GSCDUMP_REALTIME_CLOSE_CODES,
+			eventSemantics: REALTIME_V1_EVENT_SEMANTICS
+		},
+		schemas: {
+			requestMetadata,
+			requestHeaders,
+			responseMeta,
+			errorEnvelope,
+			analyticsRowsRequest,
+			analyticsRowsResponse,
+			lifecycleResponse,
+			streamHeadResponse: headResponse,
+			ticketResponse,
+			...realtimeSchemas
+		},
+		surfaces: {
+			partner,
+			analytics,
+			realtime
+		}
+	};
+}
+function compareStrings(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+function orderedJson(value) {
+	if (Array.isArray(value)) return value.map(orderedJson);
+	if (value === null || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).sort(([left], [right]) => compareStrings(left, right)).map(([key, item]) => [key, orderedJson(item)]));
+}
+function serializeContractDocument(document) {
+	return `${JSON.stringify(orderedJson(document), null, 2)}\n`;
+}
+function jsonSchema(schema) {
+	const { $schema: _schema, ...body } = z.toJSONSchema(schema);
+	return orderedJson(body);
+}
+function rewriteDefinitionRefs(value, references) {
+	if (Array.isArray(value)) return value.map((item) => rewriteDefinitionRefs(item, references));
+	if (value === null || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+		if (key === "$ref" && typeof item === "string" && item.startsWith("#/$defs/")) {
+			const name = item.slice(8);
+			const reference = references[name];
+			if (!reference) throw new TypeError(`JSON Schema references an unknown definition: ${name}`);
+			return [key, reference];
+		}
+		return [key, rewriteDefinitionRefs(item, references)];
+	}));
+}
+function registerComponentSchema(schema, prefix, components) {
+	const { $defs, ...body } = jsonSchema(schema);
+	if (!$defs) return body;
+	const definitions = $defs;
+	const safePrefix = prefix.replace(/[^\w.-]/g, "_");
+	const references = Object.fromEntries(Object.keys(definitions).map((name) => {
+		return [name, `#/components/schemas/${safePrefix}.${name}`];
+	}));
+	for (const [name, definition] of Object.entries(definitions)) {
+		const componentName = `${safePrefix}.${name}`;
+		if (componentName in components) throw new TypeError(`Duplicate generated component schema: ${componentName}`);
+		components[componentName] = rewriteDefinitionRefs(definition, references);
+	}
+	return rewriteDefinitionRefs(body, references);
+}
+function objectSchemaProperties(schema) {
+	const document = jsonSchema(schema);
+	return {
+		properties: document.properties ?? {},
+		required: new Set(document.required ?? [])
+	};
+}
+function requestParameters(operation) {
+	const parameters = [];
+	if (operation.request.params) {
+		const { properties } = objectSchemaProperties(operation.request.params);
+		for (const name of operation.path.matchAll(/\{([^{}]+)\}/g)) parameters.push({
+			name: name[1],
+			in: "path",
+			required: true,
+			schema: properties[name[1]] ?? {}
+		});
+	}
+	for (const location of ["query", "headers"]) {
+		const schema = operation.request[location];
+		if (!schema) continue;
+		const { properties, required } = objectSchemaProperties(schema);
+		for (const [name, property] of Object.entries(properties)) parameters.push({
+			name,
+			in: location === "headers" ? "header" : "query",
+			required: required.has(name),
+			schema: property
+		});
+	}
+	return parameters;
+}
+function operationDocument(operation, components) {
+	const errorComponentName = `${operation.id}.error`;
+	if (errorComponentName in components) throw new TypeError(`Duplicate generated component schema: ${errorComponentName}`);
+	components[errorComponentName] = registerComponentSchema(operation.errorResponse.producer, errorComponentName, components);
+	const errorSchema = { $ref: `#/components/schemas/${errorComponentName}` };
+	const responses = Object.fromEntries(Object.entries(operation.responses).sort(([left], [right]) => Number(left) - Number(right)).map(([status, response]) => [status, {
+		description: status.startsWith("2") ? "Successful response" : "Documented response",
+		content: { "application/json": { schema: registerComponentSchema(response.producer, `${operation.id}.response.${status}`, components) } }
+	}]));
+	responses.default = {
+		description: "Stable error envelope",
+		content: { "application/json": { schema: errorSchema } }
+	};
+	responses["4XX"] = {
+		description: "Declared client error",
+		content: { "application/json": { schema: errorSchema } }
+	};
+	responses["5XX"] = {
+		description: "Safe internal or contract error",
+		content: { "application/json": { schema: errorSchema } }
+	};
+	const document = {
+		"operationId": operation.id,
+		"summary": operation.docs.summary,
+		"description": operation.docs.description,
+		"tags": operation.docs.tags,
+		"security": operation.auth.credentials.map((credential) => ({ [credential]: [] })),
+		"parameters": requestParameters(operation),
+		responses,
+		"x-gscdump-errors": operation.errors,
+		"x-gscdump-examples": operation.docs.examples,
+		"x-gscdump-lifecycle": operation.lifecycle,
+		"x-gscdump-resources": operation.resources,
+		"x-gscdump-scopes": operation.auth.scopes,
+		"x-gscdump-ownership": operation.auth.ownership,
+		"x-gscdump-semantics": operation.semantics,
+		"x-gscdump-visibility": operation.visibility
+	};
+	if (operation.request.body) document.requestBody = {
+		required: true,
+		content: { "application/json": { schema: registerComponentSchema(operation.request.body, `${operation.id}.request.body`, components) } }
+	};
+	return document;
+}
+function openApiDocument(surface) {
+	const paths = {};
+	const schemas = {};
+	for (const operation of Object.values(surface.operations).sort((left, right) => {
+		return compareStrings(`${left.path}\0${left.method}\0${left.id}`, `${right.path}\0${right.method}\0${right.id}`);
+	})) {
+		const path = `${surface.prefix}${operation.path}`;
+		paths[path] ??= {};
+		paths[path][operation.method.toLowerCase()] = operationDocument(operation, schemas);
+	}
+	return {
+		openapi: "3.1.0",
+		jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema",
+		info: {
+			title: `gscdump ${surface.name} API`,
+			version: surface.version,
+			license: {
+				name: "MIT",
+				identifier: "MIT"
+			}
+		},
+		servers: [{ url: "https://gscdump.com" }],
+		paths,
+		components: {
+			schemas,
+			securitySchemes: {
+				user_key: {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "gscdump user key"
+				},
+				partner_key: {
+					type: "http",
+					scheme: "bearer",
+					bearerFormat: "gscdump partner key"
+				}
+			}
+		}
+	};
+}
+function asyncApiDocument(protocol) {
+	const schemas = {};
+	const clientFrameSchema = registerComponentSchema(protocol.schemas.clientFrame, "clientFrame", schemas);
+	const serverFrameSchema = registerComponentSchema(protocol.schemas.serverFrame, "serverFrame", schemas);
+	return {
+		"asyncapi": "3.1.0",
+		"info": {
+			title: "gscdump realtime API",
+			version: "1.0"
+		},
+		"servers": { production: {
+			"host": "gscdump.com",
+			"pathname": "/ws/v1",
+			"protocol": "wss",
+			"x-websocket-subprotocol": protocol.constants.realtimeSubprotocol
+		} },
+		"channels": { notifications: {
+			address: "/",
+			messages: {
+				clientFrame: { $ref: "#/components/messages/clientFrame" },
+				serverFrame: { $ref: "#/components/messages/serverFrame" }
+			}
+		} },
+		"operations": {
+			receiveServerFrame: {
+				action: "receive",
+				channel: { $ref: "#/channels/notifications" },
+				messages: [{ $ref: "#/channels/notifications/messages/serverFrame" }]
+			},
+			sendClientFrame: {
+				action: "send",
+				channel: { $ref: "#/channels/notifications" },
+				messages: [{ $ref: "#/channels/notifications/messages/clientFrame" }]
+			}
+		},
+		"components": {
+			messages: {
+				clientFrame: {
+					name: "clientFrame",
+					contentType: "application/json",
+					payload: clientFrameSchema
+				},
+				serverFrame: {
+					name: "serverFrame",
+					contentType: "application/json",
+					payload: serverFrameSchema
+				}
+			},
+			schemas
+		},
+		"x-heartbeat-text-frames": {
+			ping: protocol.constants.ping,
+			pong: protocol.constants.pong
+		},
+		"x-gscdump-event-semantics": protocol.constants.eventSemantics
+	};
+}
+function createGscdumpV1Documents() {
+	const protocol = createGscdumpV1Protocol();
+	return {
+		"openapi.partner.v1.json": openApiDocument(protocol.surfaces.partner),
+		"openapi.analytics.v1.json": openApiDocument(protocol.surfaces.analytics),
+		"openapi.realtime.v1.json": openApiDocument(protocol.surfaces.realtime),
+		"asyncapi.realtime.v1.json": asyncApiDocument(protocol)
+	};
+}
+export { GSCDUMP_HTTP_V1_VERSION, GSCDUMP_REALTIME_ACK_POLICY, GSCDUMP_REALTIME_CLOSE_CODES, GSCDUMP_REALTIME_CONNECTION_POLICY, GSCDUMP_REALTIME_LIMITS, GSCDUMP_REALTIME_MAX_CONNECTION_SECONDS, GSCDUMP_REALTIME_PING, GSCDUMP_REALTIME_PONG, GSCDUMP_REALTIME_PROTOCOL_VERSION, GSCDUMP_REALTIME_REPLAY_POLICY, GSCDUMP_REALTIME_SUBPROTOCOL, GSCDUMP_REALTIME_TICKET_AUDIENCE, GSCDUMP_REALTIME_TICKET_ISSUER, GSCDUMP_REALTIME_TICKET_POLICY, GSCDUMP_REALTIME_TICKET_PREFIX, GSCDUMP_REALTIME_TICKET_TTL_SECONDS, HTTP_V1_CREDENTIALS, HTTP_V1_CREDENTIAL_SCOPES, HTTP_V1_ERROR_CODES, HTTP_V1_METHODS, HTTP_V1_SCOPES, HTTP_V1_SURFACES, REALTIME_V1_EVENT_NAMES, REALTIME_V1_EVENT_SEMANTICS, REALTIME_V1_RESOURCE_TYPES, buildHttpOperationPath, createGscdumpV1Documents, createGscdumpV1Protocol, createRealtimeV1Schemas, defineHttpOperation, defineHttpSurface, defineResponseObject, defineSuccessResponse, serializeContractDocument };