@gscdump/contracts 1.4.0 → 1.4.1

package/dist/v1/realtime.mjs

@@ -0,0 +1,447 @@
+import { z } from "zod";
+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
+		])
+	};
+}
+export { 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, REALTIME_V1_EVENT_NAMES, REALTIME_V1_EVENT_SEMANTICS, REALTIME_V1_RESOURCE_TYPES, createRealtimeV1Schemas };

package/dist/webhook-constants.mjs

@@ -0,0 +1,16 @@
+const WEBHOOK_CONTRACT_VERSION = "2026-05-11";
+const WEBHOOK_SIGNATURE_HEADER = "X-GSCDump-Signature";
+const WEBHOOK_EVENT_HEADER = "X-GSCDump-Event";
+const WEBHOOK_DELIVERY_HEADER = "X-GSCDump-Delivery";
+const WEBHOOK_CONTRACT_VERSION_HEADER = "X-GSCDump-Contract-Version";
+const WEBHOOK_TIMESTAMP_HEADER = "X-GSCDump-Timestamp";
+const CANONICAL_WEBHOOK_EVENTS = [
+	"user.lifecycle.changed",
+	"site.lifecycle.changed",
+	"site.analytics.ready",
+	"site.indexing.ready",
+	"site.auth.failed",
+	"job.failed"
+];
+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": "1.4.0",
+  "version": "1.4.1",
   "description": "Shared gscdump.com API, webhook, realtime, and lifecycle contracts.",
   "author": {
     "name": "Harlan Wilton",

package/dist/{_chunks/endpoints.mjs → endpoints.mjs}

@@ -1,5 +1,5 @@
-import { analyticsEndpointSchemas, partnerControlEndpointSchemas } from "./schemas.mjs";
 import { analyticsRoutes, partnerRoutes } from "./routes.mjs";
+import { analyticsEndpointSchemas, partnerControlEndpointSchemas } from "./schemas.mjs";
 function defineEndpoint(method, path, schema) {
 	return {
 		method,