@gscdump/sdk 1.4.0 → 1.4.1

package/dist/v1/http.mjs

@@ -0,0 +1,418 @@
+import { buildHttpOperationPath, createGscdumpV1Protocol } from "@gscdump/contracts/v1";
+var GscdumpV1Error = class extends Error {
+	tag = "GscdumpV1Error";
+	code;
+	status;
+	requestId;
+	retryable;
+	details;
+	cause;
+	constructor(options) {
+		super(options.message);
+		this.name = "GscdumpV1Error";
+		this.code = options.code;
+		this.status = options.status;
+		this.requestId = options.requestId;
+		this.retryable = options.retryable;
+		this.details = options.details;
+		this.cause = options.cause;
+	}
+};
+function isGscdumpV1Error(error) {
+	return error instanceof GscdumpV1Error;
+}
+const DEFAULT_API_ROOT = "https://gscdump.com/api";
+const API_PREFIX_RE = /^\/api(?=\/)/;
+const TRAILING_SLASH_RE = /\/+$/;
+const LEADING_SLASH_RE = /^\/+/;
+function validationDetails(cause) {
+	if (typeof cause === "object" && cause !== null && "issues" in cause) return { issues: cause.issues };
+	return {};
+}
+function requestValidationError(operationId, location, cause) {
+	return new GscdumpV1Error({
+		code: "request_validation",
+		message: `${operationId}: invalid request ${location}`,
+		retryable: false,
+		details: {
+			location,
+			...validationDetails(cause)
+		},
+		cause
+	});
+}
+function responseValidationError(operationId, status, requestId, cause) {
+	return new GscdumpV1Error({
+		code: "response_validation",
+		message: `${operationId}: response ${status} did not match the v1 contract`,
+		status,
+		requestId,
+		retryable: false,
+		details: validationDetails(cause),
+		cause
+	});
+}
+function clampInteger(value, fallback, min, max) {
+	if (value === void 0) return fallback;
+	if (!Number.isFinite(value)) throw new TypeError("Retry configuration values must be finite numbers.");
+	return Math.min(max, Math.max(min, Math.trunc(value)));
+}
+function resolveRetryOptions(options) {
+	const baseDelayMs = clampInteger(options?.baseDelayMs, 250, 0, 6e4);
+	const maxDelayMs = clampInteger(options?.maxDelayMs, 2e3, baseDelayMs, 3e5);
+	return {
+		maxAttempts: clampInteger(options?.maxAttempts, 3, 1, 5),
+		baseDelayMs,
+		maxDelayMs
+	};
+}
+function resolveApiUrl(apiRoot, contractPath) {
+	const relative = contractPath.replace(API_PREFIX_RE, "").replace(LEADING_SLASH_RE, "");
+	return `${apiRoot.replace(TRAILING_SLASH_RE, "")}/${relative}`;
+}
+function appendQueryValue(search, key, value) {
+	if (value === void 0) return;
+	if (Array.isArray(value)) {
+		for (const item of value) appendQueryValue(search, key, item);
+		return;
+	}
+	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		search.append(key, value === null ? "null" : String(value));
+		return;
+	}
+	search.append(key, JSON.stringify(value));
+}
+function appendQuery(url, query) {
+	if (query === void 0 || query === null) return url;
+	if (typeof query !== "object" || Array.isArray(query)) throw new TypeError("A query schema must produce an object.");
+	const search = new URLSearchParams();
+	for (const key of Object.keys(query).sort()) appendQueryValue(search, key, query[key]);
+	const serialized = search.toString();
+	return serialized ? `${url}?${serialized}` : url;
+}
+function assertAbsentLocation(operationId, location, value) {
+	if (value !== void 0) throw requestValidationError(operationId, location, /* @__PURE__ */ new TypeError(`${location} is not accepted by this operation.`));
+}
+function parseLocation(operation, location, value) {
+	const schema = operation.request[location];
+	if (schema === null) {
+		assertAbsentLocation(operation.id, location, value);
+		return;
+	}
+	try {
+		return schema.parse(location === "headers" && value === void 0 ? {} : value);
+	} catch (cause) {
+		throw requestValidationError(operation.id, location, cause);
+	}
+}
+function prepareRequest(surface, operation, input, options) {
+	let path;
+	if (operation.request.params === null) {
+		assertAbsentLocation(operation.id, "params", input.params);
+		path = buildHttpOperationPath(surface, operation);
+	} else try {
+		path = buildHttpOperationPath(surface, operation, input.params);
+	} catch (cause) {
+		throw requestValidationError(operation.id, "params", cause);
+	}
+	const inputHeaders = input.headers;
+	const headerRequestId = inputHeaders?.["x-request-id"];
+	if (options.requestId && headerRequestId && options.requestId !== headerRequestId) throw requestValidationError(operation.id, "headers", /* @__PURE__ */ new TypeError("requestId conflicts with headers.x-request-id."));
+	const requestHeaders = options.requestId ? {
+		...inputHeaders ?? {},
+		"x-request-id": options.requestId
+	} : input.headers;
+	return {
+		path,
+		query: parseLocation(operation, "query", input.query),
+		headers: parseLocation(operation, "headers", requestHeaders),
+		body: parseLocation(operation, "body", input.body)
+	};
+}
+async function resolveCredential(resolver) {
+	let credential;
+	try {
+		credential = typeof resolver === "function" ? await resolver() : resolver;
+	} catch (cause) {
+		throw new GscdumpV1Error({
+			code: "credential_resolution",
+			message: "Could not resolve the v1 Bearer credential.",
+			retryable: false,
+			details: {},
+			cause
+		});
+	}
+	if (typeof credential !== "string" || !credential.trim()) throw new GscdumpV1Error({
+		code: "credential_resolution",
+		message: "The v1 Bearer credential cannot be empty.",
+		retryable: false,
+		details: {}
+	});
+	return credential;
+}
+async function resolveBaseHeaders(resolver) {
+	return typeof resolver === "function" ? await resolver() : resolver;
+}
+async function buildRequestHeaders(options, operation, prepared, executeOptions) {
+	try {
+		const [baseHeaders, credential] = await Promise.all([resolveBaseHeaders(options.headers), resolveCredential(options.credential)]);
+		const headers = new Headers(baseHeaders);
+		for (const [key, value] of Object.entries(prepared.headers)) if (value !== void 0) headers.set(key, String(value));
+		headers.delete("x-api-key");
+		headers.set("accept", "application/json");
+		headers.set("authorization", `Bearer ${credential}`);
+		if (executeOptions.idempotencyKey) headers.set("idempotency-key", executeOptions.idempotencyKey);
+		if (prepared.body !== void 0) headers.set("content-type", "application/json");
+		return headers;
+	} catch (cause) {
+		if (cause instanceof GscdumpV1Error) throw cause;
+		throw requestValidationError(operation.id, "headers", cause);
+	}
+}
+function isAbortError(error, signal) {
+	return signal?.aborted === true || typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+function abortedRequestError(operation, executeOptions, cause = executeOptions.signal?.reason) {
+	return new GscdumpV1Error({
+		code: "aborted",
+		message: `${operation.id}: request aborted`,
+		requestId: executeOptions.requestId,
+		retryable: false,
+		details: {},
+		cause
+	});
+}
+async function waitForRetry(ms, operation, executeOptions) {
+	try {
+		await sleep(ms, executeOptions.signal);
+	} catch (cause) {
+		if (isAbortError(cause, executeOptions.signal)) throw abortedRequestError(operation, executeOptions, cause);
+		throw cause;
+	}
+}
+function awaitWithAbort(promise, operation, executeOptions) {
+	const signal = executeOptions.signal;
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(abortedRequestError(operation, executeOptions));
+	return new Promise((resolve, reject) => {
+		function onAbort() {
+			reject(abortedRequestError(operation, executeOptions));
+		}
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (cause) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(cause);
+		});
+	});
+}
+function parseRetryAfter(value, now) {
+	if (value === null) return void 0;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.ceil(seconds * 1e3);
+	const date = Date.parse(value);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, date - now);
+}
+function retryDelay(attempt, retryAfter, options) {
+	const exponential = Math.min(options.maxDelayMs, options.baseDelayMs * 2 ** Math.max(0, attempt - 1));
+	return Math.max(exponential, parseRetryAfter(retryAfter, Date.now()) ?? 0);
+}
+function sleep(ms, signal) {
+	if (signal?.aborted) return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+	return new Promise((resolve, reject) => {
+		const handle = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(handle);
+			reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+async function readJson(response) {
+	const text = await response.text();
+	if (!text) return null;
+	return JSON.parse(text);
+}
+function requestIdFrom(response) {
+	return response.headers.get("x-request-id") ?? void 0;
+}
+function operationLookup(protocol) {
+	const operations = /* @__PURE__ */ new Map();
+	for (const surface of Object.values(protocol.surfaces)) for (const operation of Object.values(surface.operations)) operations.set(operation.id, {
+		operation,
+		surface
+	});
+	return operations;
+}
+function createGscdumpV1Client(options) {
+	const protocol = createGscdumpV1Protocol();
+	const operations = operationLookup(protocol);
+	const retryOptions = resolveRetryOptions(options.retry);
+	const apiRoot = options.apiRoot ?? DEFAULT_API_ROOT;
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	if (typeof fetchImpl !== "function") throw new TypeError("createGscdumpV1Client requires a fetch implementation in this runtime.");
+	const execute = executeUntyped;
+	async function executeUntyped(operationId, input, executeOptions = {}) {
+		const entry = operations.get(operationId);
+		if (!entry) throw new GscdumpV1Error({
+			code: "request_validation",
+			message: `Unknown gscdump v1 operation: ${operationId}`,
+			retryable: false,
+			details: { operationId }
+		});
+		const { operation, surface } = entry;
+		if (typeof input !== "object" || input === null || Array.isArray(input)) throw requestValidationError(operation.id, "input", /* @__PURE__ */ new TypeError("input must be an object."));
+		const prepared = prepareRequest(surface, operation, input, executeOptions);
+		let url;
+		try {
+			url = appendQuery(resolveApiUrl(apiRoot, prepared.path), prepared.query);
+		} catch (cause) {
+			throw requestValidationError(operation.id, "query", cause);
+		}
+		const canRetry = operation.semantics.retry === "idempotent";
+		for (let attempt = 1; attempt <= retryOptions.maxAttempts; attempt++) {
+			if (executeOptions.signal?.aborted) throw abortedRequestError(operation, executeOptions);
+			const headers = await awaitWithAbort(buildRequestHeaders(options, operation, prepared, executeOptions), operation, executeOptions);
+			if (executeOptions.signal?.aborted) throw abortedRequestError(operation, executeOptions);
+			let response;
+			try {
+				response = await fetchImpl(url, {
+					method: operation.method,
+					headers,
+					body: prepared.body === void 0 ? void 0 : JSON.stringify(prepared.body),
+					signal: executeOptions.signal
+				});
+			} catch (cause) {
+				if (isAbortError(cause, executeOptions.signal)) throw abortedRequestError(operation, executeOptions, cause);
+				if (canRetry && attempt < retryOptions.maxAttempts) {
+					await waitForRetry(retryDelay(attempt, null, retryOptions), operation, executeOptions);
+					continue;
+				}
+				throw new GscdumpV1Error({
+					code: "network_error",
+					message: `${operation.id}: network request failed`,
+					requestId: executeOptions.requestId,
+					retryable: canRetry,
+					details: { attempts: attempt },
+					cause
+				});
+			}
+			const requestId = requestIdFrom(response) ?? executeOptions.requestId;
+			let payload;
+			try {
+				payload = await readJson(response);
+			} catch (cause) {
+				if (isAbortError(cause, executeOptions.signal)) throw abortedRequestError(operation, executeOptions, cause);
+				throw responseValidationError(operation.id, response.status, requestId, cause);
+			}
+			if (executeOptions.signal?.aborted) throw abortedRequestError(operation, executeOptions);
+			const responseContract = operation.responses[response.status];
+			if (responseContract) try {
+				return responseContract.client.parse(payload);
+			} catch (cause) {
+				throw responseValidationError(operation.id, response.status, requestId, cause);
+			}
+			if (response.ok) throw new GscdumpV1Error({
+				code: "protocol_error",
+				message: `${operation.id}: undeclared success status ${response.status}`,
+				status: response.status,
+				requestId,
+				retryable: false,
+				details: { status: response.status }
+			});
+			let envelope;
+			try {
+				envelope = protocol.schemas.errorEnvelope.client.parse(payload);
+			} catch (cause) {
+				throw responseValidationError(operation.id, response.status, requestId, cause);
+			}
+			if (!operation.errors.includes(envelope.error.code)) throw new GscdumpV1Error({
+				code: "protocol_error",
+				message: `${operation.id}: undeclared error code ${envelope.error.code}`,
+				status: response.status,
+				requestId: envelope.error.requestId,
+				retryable: false,
+				details: { code: envelope.error.code }
+			});
+			const apiError = new GscdumpV1Error({
+				code: envelope.error.code,
+				message: envelope.error.message,
+				status: response.status,
+				requestId: envelope.error.requestId,
+				retryable: envelope.error.retryable,
+				details: envelope.error.details ?? {}
+			});
+			if (canRetry && apiError.retryable && attempt < retryOptions.maxAttempts) {
+				await waitForRetry(retryDelay(attempt, response.headers.get("retry-after"), retryOptions), operation, executeOptions);
+				continue;
+			}
+			throw apiError;
+		}
+		throw new GscdumpV1Error({
+			code: "network_error",
+			message: `${operationId}: retry budget exhausted`,
+			retryable: false,
+			details: {}
+		});
+	}
+	return {
+		execute,
+		getUserLifecycle: (input, executeOptions) => execute("partner.users.lifecycle.get", input, executeOptions),
+		listAvailableSites: (input, executeOptions) => execute("partner.users.sites.available.list", input, executeOptions),
+		createSite: (input, executeOptions) => execute("partner.users.sites.create", input, executeOptions),
+		createUser: (input, executeOptions) => execute("partner.users.create", input, executeOptions),
+		updateUserTokens: (input, executeOptions) => execute("partner.users.tokens.update", input, executeOptions),
+		getSiteIndexing: (input, executeOptions) => execute("partner.sites.indexing.get", input, executeOptions),
+		listSiteIndexingUrls: (input, executeOptions) => execute("partner.sites.indexing.urls.list", input, executeOptions),
+		getSiteIndexingDiagnostics: (input, executeOptions) => execute("partner.sites.indexing.diagnostics.get", input, executeOptions),
+		getSiteSitemaps: (input, executeOptions) => execute("partner.sites.sitemaps.get", input, executeOptions),
+		getSiteSitemapChanges: (input, executeOptions) => execute("partner.sites.sitemaps.changes.get", input, executeOptions),
+		getSiteAnalysis: (input, executeOptions) => execute("partner.sites.analysis.get", input, executeOptions),
+		getSiteAnalysisBundle: (input, executeOptions) => execute("partner.sites.analysis.bundle.get", input, executeOptions),
+		deleteSite: (input, executeOptions) => execute("partner.sites.delete", input, executeOptions),
+		getCanonicalMismatches: (input, executeOptions) => execute("partner.sites.canonical.mismatches.get", input, executeOptions),
+		inspectSiteUrls: (input, executeOptions) => execute("partner.sites.indexing.inspect.create", input, executeOptions),
+		recoverSitePermission: (input, executeOptions) => execute("partner.sites.permission.recover", input, executeOptions),
+		queryKeywordSparklines: (input, executeOptions) => execute("partner.sites.keyword.sparklines.query", input, executeOptions),
+		getQueryTrend: (input, executeOptions) => execute("partner.sites.query.trend.get", input, executeOptions),
+		getPageTrend: (input, executeOptions) => execute("partner.sites.page.trend.get", input, executeOptions),
+		getContentVelocity: (input, executeOptions) => execute("partner.sites.content.velocity.get", input, executeOptions),
+		getCtrCurve: (input, executeOptions) => execute("partner.sites.ctr.curve.get", input, executeOptions),
+		getDarkTraffic: (input, executeOptions) => execute("partner.sites.dark.traffic.get", input, executeOptions),
+		getDeviceGap: (input, executeOptions) => execute("partner.sites.device.gap.get", input, executeOptions),
+		getKeywordBreadth: (input, executeOptions) => execute("partner.sites.keyword.breadth.get", input, executeOptions),
+		getPositionDistribution: (input, executeOptions) => execute("partner.sites.position.distribution.get", input, executeOptions),
+		getTopAssociation: (input, executeOptions) => execute("partner.sites.top.association.get", input, executeOptions),
+		getIndexPercent: (input, executeOptions) => execute("partner.sites.index.percent.get", input, executeOptions),
+		createSitemapAction: (input, executeOptions) => execute("partner.sites.sitemaps.action.create", input, executeOptions),
+		querySitemapMembership: (input, executeOptions) => execute("partner.sites.sitemaps.membership.query", input, executeOptions),
+		createTeam: (input, executeOptions) => execute("partner.teams.create", input, executeOptions),
+		renameTeam: (input, executeOptions) => execute("partner.teams.rename", input, executeOptions),
+		deleteTeam: (input, executeOptions) => execute("partner.teams.delete", input, executeOptions),
+		listTeamMembers: (input, executeOptions) => execute("partner.teams.members.list", input, executeOptions),
+		addTeamMember: (input, executeOptions) => execute("partner.teams.members.add", input, executeOptions),
+		updateTeamMemberRole: (input, executeOptions) => execute("partner.teams.members.role.update", input, executeOptions),
+		removeTeamMember: (input, executeOptions) => execute("partner.teams.members.remove", input, executeOptions),
+		updateSiteTeam: (input, executeOptions) => execute("partner.sites.team.update", input, executeOptions),
+		getTeamCatalog: (input, executeOptions) => execute("partner.teams.catalog.get", input, executeOptions),
+		bindTeamCatalog: (input, executeOptions) => execute("partner.teams.catalog.bind", input, executeOptions),
+		getSiteIntIdCrosswalk: (input, executeOptions) => execute("partner.users.sites.crosswalk.get", input, executeOptions),
+		deleteUser: (input, executeOptions) => execute("partner.users.delete", input, executeOptions),
+		createVerificationToken: (input, executeOptions) => execute("partner.users.verification.token.create", input, executeOptions),
+		addAndVerifySite: (input, executeOptions) => execute("partner.users.sites.verify.create", input, executeOptions),
+		queryCrossSource: (input, executeOptions) => execute("partner.sites.cross.source.query", input, executeOptions),
+		enrichKeywords: (input, executeOptions) => execute("partner.keywords.enrich.query", input, executeOptions),
+		queryAnalyticsRows: (input, executeOptions) => execute("analytics.rows.query", input, executeOptions),
+		queryAnalyticsReport: (input, executeOptions) => execute("analytics.reports.query", input, executeOptions),
+		queryAnalyticsReportDetail: (input, executeOptions) => execute("analytics.reports.detail.query", input, executeOptions),
+		getRealtimeStreamHead: (input = {}, executeOptions) => execute("realtime.stream.head.get", input, executeOptions),
+		createRealtimeTicket: (input, executeOptions) => execute("realtime.tickets.create", input, executeOptions)
+	};
+}
+export { GscdumpV1Error, createGscdumpV1Client, isGscdumpV1Error };

package/dist/v1/index.d.mts

@@ -1,233 +1,3 @@
-import { GscdumpV1ErrorEnvelope, RealtimeV1Cursor, RealtimeV1Event, RealtimeV1StreamHead, RealtimeV1StreamId, createGscdumpV1Protocol } from "@gscdump/contracts/v1";
-import { ZodTypeAny, z } from "zod";
-type MaybePromise$1<T> = T | Promise<T>;
-type ValueOf<T> = T[keyof T];
-type ValueOfUnion<T> = T extends unknown ? ValueOf<T> : never;
-type GscdumpV1ProtocolShape = ReturnType<typeof createGscdumpV1Protocol>;
-type GscdumpV1Surface = ValueOf<GscdumpV1ProtocolShape['surfaces']>;
-type GscdumpV1OperationRegistry = GscdumpV1Surface['operations'];
-type GscdumpV1Operation = ValueOfUnion<GscdumpV1OperationRegistry>;
-type GscdumpV1OperationId = GscdumpV1Operation['id'];
-type OperationById<TId extends GscdumpV1OperationId> = Extract<GscdumpV1Operation, {
-  id: TId;
-}>;
-type SchemaInput<TSchema> = TSchema extends ZodTypeAny ? z.input<TSchema> : never;
-type SchemaOutput<TSchema> = TSchema extends ZodTypeAny ? z.output<TSchema> : never;
-type RequiredLocation<TKey extends string, TSchema> = TSchema extends ZodTypeAny ? { [K in TKey]: SchemaInput<TSchema>; } : { [K in TKey]?: never; };
-type OptionalLocation<TKey extends string, TSchema> = TSchema extends ZodTypeAny ? { [K in TKey]?: SchemaInput<TSchema>; } : { [K in TKey]?: never; };
-type GscdumpV1OperationInput<TId extends GscdumpV1OperationId> = RequiredLocation<'params', OperationById<TId>['request']['params']> & RequiredLocation<'query', OperationById<TId>['request']['query']> & OptionalLocation<'headers', OperationById<TId>['request']['headers']> & RequiredLocation<'body', OperationById<TId>['request']['body']>;
-type OperationResponseSchema<TId extends GscdumpV1OperationId> = ValueOf<OperationById<TId>['responses']> extends (infer TResponse) ? TResponse extends {
-  client: infer TClient extends ZodTypeAny;
-} ? TClient : never : never;
-type GscdumpV1OperationResponse<TId extends GscdumpV1OperationId> = SchemaOutput<OperationResponseSchema<TId>>;
-type GscdumpV1CredentialResolver = string | (() => MaybePromise$1<string>);
-type GscdumpV1HeadersResolver = HeadersInit | (() => MaybePromise$1<HeadersInit>);
-interface GscdumpV1RetryOptions {
-  /** Total attempts, including the initial request. Defaults to 3 and is capped at 5. */
-  maxAttempts?: number;
-  /** Deterministic exponential-backoff base. Defaults to 250 ms. */
-  baseDelayMs?: number;
-  /** Backoff ceiling. Defaults to 2 seconds. Retry-After can exceed this ceiling. */
-  maxDelayMs?: number;
-}
-interface CreateGscdumpV1ClientOptions {
-  /**
-   * Root replacing the contract's `/api` segment. Direct calls default to
-   * `https://gscdump.com/api`; a same-origin proxy can use `/api/_gscdump`.
-   */
-  apiRoot?: string;
-  credential: GscdumpV1CredentialResolver;
-  fetch?: typeof fetch;
-  headers?: GscdumpV1HeadersResolver;
-  retry?: GscdumpV1RetryOptions;
-}
-interface GscdumpV1ExecuteOptions {
-  signal?: AbortSignal;
-  requestId?: string;
-  idempotencyKey?: string;
-}
-type GscdumpV1SdkErrorCode = GscdumpV1ErrorEnvelope['error']['code'] | 'aborted' | 'credential_resolution' | 'network_error' | 'protocol_error' | 'request_validation' | 'response_validation';
-interface GscdumpV1ErrorOptions {
-  code: GscdumpV1SdkErrorCode;
-  message: string;
-  status?: number;
-  requestId?: string;
-  retryable: boolean;
-  details: Record<string, unknown>;
-  cause?: unknown;
-}
-/** One stable, tagged failure shape for validation, transport, and API errors. */
-declare class GscdumpV1Error extends Error {
-  readonly tag: 'GscdumpV1Error';
-  readonly code: GscdumpV1SdkErrorCode;
-  readonly status?: number;
-  readonly requestId?: string;
-  readonly retryable: boolean;
-  readonly details: Record<string, unknown>;
-  readonly cause?: unknown;
-  constructor(options: GscdumpV1ErrorOptions);
-}
-declare function isGscdumpV1Error(error: unknown): error is GscdumpV1Error;
-interface GscdumpV1Client {
-  execute: <TId extends GscdumpV1OperationId>(operation: TId, input: NoInfer<GscdumpV1OperationInput<TId>>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<TId>>;
-  getUserLifecycle: (input: GscdumpV1OperationInput<'partner.users.lifecycle.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.lifecycle.get'>>;
-  listAvailableSites: (input: GscdumpV1OperationInput<'partner.users.sites.available.list'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.sites.available.list'>>;
-  createSite: (input: GscdumpV1OperationInput<'partner.users.sites.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.sites.create'>>;
-  createUser: (input: GscdumpV1OperationInput<'partner.users.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.create'>>;
-  updateUserTokens: (input: GscdumpV1OperationInput<'partner.users.tokens.update'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.tokens.update'>>;
-  getSiteIndexing: (input: GscdumpV1OperationInput<'partner.sites.indexing.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.indexing.get'>>;
-  listSiteIndexingUrls: (input: GscdumpV1OperationInput<'partner.sites.indexing.urls.list'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.indexing.urls.list'>>;
-  getSiteIndexingDiagnostics: (input: GscdumpV1OperationInput<'partner.sites.indexing.diagnostics.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.indexing.diagnostics.get'>>;
-  getSiteSitemaps: (input: GscdumpV1OperationInput<'partner.sites.sitemaps.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.sitemaps.get'>>;
-  getSiteSitemapChanges: (input: GscdumpV1OperationInput<'partner.sites.sitemaps.changes.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.sitemaps.changes.get'>>;
-  getSiteAnalysis: (input: GscdumpV1OperationInput<'partner.sites.analysis.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.analysis.get'>>;
-  getSiteAnalysisBundle: (input: GscdumpV1OperationInput<'partner.sites.analysis.bundle.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.analysis.bundle.get'>>;
-  deleteSite: (input: GscdumpV1OperationInput<'partner.sites.delete'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.delete'>>;
-  getCanonicalMismatches: (input: GscdumpV1OperationInput<'partner.sites.canonical.mismatches.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.canonical.mismatches.get'>>;
-  inspectSiteUrls: (input: GscdumpV1OperationInput<'partner.sites.indexing.inspect.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.indexing.inspect.create'>>;
-  recoverSitePermission: (input: GscdumpV1OperationInput<'partner.sites.permission.recover'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.permission.recover'>>;
-  queryKeywordSparklines: (input: GscdumpV1OperationInput<'partner.sites.keyword.sparklines.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.keyword.sparklines.query'>>;
-  getQueryTrend: (input: GscdumpV1OperationInput<'partner.sites.query.trend.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.query.trend.get'>>;
-  getPageTrend: (input: GscdumpV1OperationInput<'partner.sites.page.trend.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.page.trend.get'>>;
-  getContentVelocity: (input: GscdumpV1OperationInput<'partner.sites.content.velocity.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.content.velocity.get'>>;
-  getCtrCurve: (input: GscdumpV1OperationInput<'partner.sites.ctr.curve.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.ctr.curve.get'>>;
-  getDarkTraffic: (input: GscdumpV1OperationInput<'partner.sites.dark.traffic.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.dark.traffic.get'>>;
-  getDeviceGap: (input: GscdumpV1OperationInput<'partner.sites.device.gap.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.device.gap.get'>>;
-  getKeywordBreadth: (input: GscdumpV1OperationInput<'partner.sites.keyword.breadth.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.keyword.breadth.get'>>;
-  getPositionDistribution: (input: GscdumpV1OperationInput<'partner.sites.position.distribution.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.position.distribution.get'>>;
-  getTopAssociation: (input: GscdumpV1OperationInput<'partner.sites.top.association.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.top.association.get'>>;
-  getIndexPercent: (input: GscdumpV1OperationInput<'partner.sites.index.percent.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.index.percent.get'>>;
-  createSitemapAction: (input: GscdumpV1OperationInput<'partner.sites.sitemaps.action.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.sitemaps.action.create'>>;
-  querySitemapMembership: (input: GscdumpV1OperationInput<'partner.sites.sitemaps.membership.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.sitemaps.membership.query'>>;
-  createTeam: (input: GscdumpV1OperationInput<'partner.teams.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.create'>>;
-  renameTeam: (input: GscdumpV1OperationInput<'partner.teams.rename'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.rename'>>;
-  deleteTeam: (input: GscdumpV1OperationInput<'partner.teams.delete'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.delete'>>;
-  listTeamMembers: (input: GscdumpV1OperationInput<'partner.teams.members.list'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.members.list'>>;
-  addTeamMember: (input: GscdumpV1OperationInput<'partner.teams.members.add'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.members.add'>>;
-  updateTeamMemberRole: (input: GscdumpV1OperationInput<'partner.teams.members.role.update'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.members.role.update'>>;
-  removeTeamMember: (input: GscdumpV1OperationInput<'partner.teams.members.remove'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.members.remove'>>;
-  updateSiteTeam: (input: GscdumpV1OperationInput<'partner.sites.team.update'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.team.update'>>;
-  getTeamCatalog: (input: GscdumpV1OperationInput<'partner.teams.catalog.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.catalog.get'>>;
-  bindTeamCatalog: (input: GscdumpV1OperationInput<'partner.teams.catalog.bind'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.teams.catalog.bind'>>;
-  getSiteIntIdCrosswalk: (input: GscdumpV1OperationInput<'partner.users.sites.crosswalk.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.sites.crosswalk.get'>>;
-  deleteUser: (input: GscdumpV1OperationInput<'partner.users.delete'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.delete'>>;
-  createVerificationToken: (input: GscdumpV1OperationInput<'partner.users.verification.token.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.verification.token.create'>>;
-  addAndVerifySite: (input: GscdumpV1OperationInput<'partner.users.sites.verify.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.users.sites.verify.create'>>;
-  queryCrossSource: (input: GscdumpV1OperationInput<'partner.sites.cross.source.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.sites.cross.source.query'>>;
-  enrichKeywords: (input: GscdumpV1OperationInput<'partner.keywords.enrich.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'partner.keywords.enrich.query'>>;
-  queryAnalyticsRows: (input: GscdumpV1OperationInput<'analytics.rows.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'analytics.rows.query'>>;
-  queryAnalyticsReport: (input: GscdumpV1OperationInput<'analytics.reports.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'analytics.reports.query'>>;
-  queryAnalyticsReportDetail: (input: GscdumpV1OperationInput<'analytics.reports.detail.query'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'analytics.reports.detail.query'>>;
-  getRealtimeStreamHead: (input?: GscdumpV1OperationInput<'realtime.stream.head.get'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'realtime.stream.head.get'>>;
-  createRealtimeTicket: (input: GscdumpV1OperationInput<'realtime.tickets.create'>, options?: GscdumpV1ExecuteOptions) => Promise<GscdumpV1OperationResponse<'realtime.tickets.create'>>;
-}
-/** Create one framework-neutral client whose behavior is driven by the v1 registry. */
-declare function createGscdumpV1Client(options: CreateGscdumpV1ClientOptions): GscdumpV1Client;
-type MaybePromise<T> = T | Promise<T>;
-declare const GSCDUMP_REALTIME_V1_SDK_VERSION: '1.4.0';
-type GscdumpRealtimeV1TransportState = 'idle' | 'ticketing' | 'connecting' | 'handshaking' | 'replaying' | 'live' | 'waiting' | 'stopped' | 'terminal';
-type GscdumpRealtimeV1Freshness = 'unknown' | 'stale' | 'applying' | 'fresh' | 'resyncing' | 'degraded';
-type GscdumpRealtimeV1ErrorCode = 'cursor_store_failed' | 'effect_failed' | 'heartbeat_stale' | 'integration_failed' | 'protocol_error' | 'resync_failed' | 'runtime_unavailable' | 'socket_error' | 'ticket_invalid' | 'ticket_provider_failed' | 'upgrade_rejected';
-interface GscdumpRealtimeV1ErrorOptions {
-  code: GscdumpRealtimeV1ErrorCode;
-  message: string;
-  retryable: boolean;
-  terminal: boolean;
-  details?: Record<string, unknown>;
-  cause?: unknown;
-}
-declare class GscdumpRealtimeV1Error extends Error {
-  readonly tag: 'GscdumpRealtimeV1Error';
-  readonly code: GscdumpRealtimeV1ErrorCode;
-  readonly retryable: boolean;
-  readonly terminal: boolean;
-  readonly details: Record<string, unknown>;
-  readonly cause?: unknown;
-  constructor(options: GscdumpRealtimeV1ErrorOptions);
-}
-interface GscdumpRealtimeV1CursorStore {
-  load: () => MaybePromise<RealtimeV1Cursor | null>;
-  save: (cursor: RealtimeV1Cursor) => MaybePromise<void>;
-}
-interface GscdumpRealtimeV1SocketLike {
-  readonly readyState: number;
-  readonly protocol: string;
-  onopen: ((event: unknown) => void) | null;
-  onmessage: ((event: {
-    data: unknown;
-  }) => void) | null;
-  onerror: ((event: unknown) => void) | null;
-  onclose: ((event: {
-    code?: number;
-    reason?: string;
-    wasClean?: boolean;
-  }) => void) | null;
-  send: (data: string) => void;
-  close: (code?: number, reason?: string) => void;
-}
-interface GscdumpRealtimeV1Runtime {
-  createSocket: (url: string, protocols: readonly string[]) => GscdumpRealtimeV1SocketLike;
-  setTimeout: (handler: () => void, ms: number) => unknown;
-  clearTimeout: (handle: unknown) => void;
-  random: () => number;
-  now: () => number;
-}
-type GscdumpRealtimeV1ResyncReason = 'cursor_expired' | 'retention_gap' | 'sequence_gap' | 'stream_mismatch' | 'initial_cursor_missing' | 'effect_application_failed';
-interface GscdumpRealtimeV1ResyncRequest {
-  reason: GscdumpRealtimeV1ResyncReason;
-  source: 'server' | 'client';
-  streamId: RealtimeV1StreamId;
-  previousCursor: RealtimeV1Cursor | null;
-  resumeAfter: RealtimeV1Cursor;
-  failedEvent?: RealtimeV1Event;
-  cause?: unknown;
-}
-interface GscdumpRealtimeV1Snapshot {
-  transport: GscdumpRealtimeV1TransportState;
-  freshness: GscdumpRealtimeV1Freshness;
-  attempt: number;
-  streamId: RealtimeV1StreamId | null;
-  cursor: RealtimeV1Cursor | null;
-  head: RealtimeV1StreamHead | null;
-  error: GscdumpRealtimeV1Error | null;
-}
-type GscdumpRealtimeV1Observation = {
-  type: 'state';
-  state: GscdumpRealtimeV1Snapshot;
-} | {
-  type: 'event';
-  event: RealtimeV1Event;
-  cursor: RealtimeV1Cursor | null;
-} | {
-  type: 'error';
-  error: GscdumpRealtimeV1Error;
-  state: GscdumpRealtimeV1Snapshot;
-} | {
-  type: 'advisory';
-  code: 'unknown_event' | 'unknown_resource' | 'unsupported_event_version';
-  event: RealtimeV1Event;
-};
-interface CreateGscdumpRealtimeV1ClientOptions {
-  /** Called for every connection attempt. A ticket is never reused. */
-  ticketProvider: () => MaybePromise<unknown>;
-  /** Required correctness effect for each contiguous durable event. */
-  applyEvent: (event: RealtimeV1Event) => Promise<void>;
-  /** Required full authoritative reseed used whenever replay is unsafe. */
-  resync: (request: GscdumpRealtimeV1ResyncRequest) => Promise<void>;
-  cursorStore?: GscdumpRealtimeV1CursorStore;
-  /** One isolated callback for state, event, advisory, and error observations. */
-  onObservation?: (observation: GscdumpRealtimeV1Observation) => unknown;
-  runtime?: GscdumpRealtimeV1Runtime;
-  sdkVersion?: string;
-}
-interface GscdumpRealtimeV1Client {
-  start: () => Promise<void>;
-  stop: () => void;
-  getSnapshot: () => GscdumpRealtimeV1Snapshot;
-}
-/**
- * Own the v1 cursor/ACK correctness state machine. Framework adapters provide
- * required effects; they never need to reproduce transport ordering rules.
- */
-declare function createGscdumpRealtimeV1Client(options: CreateGscdumpRealtimeV1ClientOptions): GscdumpRealtimeV1Client;
+import { CreateGscdumpV1ClientOptions, GscdumpV1Client, GscdumpV1CredentialResolver, GscdumpV1Error, GscdumpV1ErrorOptions, GscdumpV1ExecuteOptions, GscdumpV1HeadersResolver, GscdumpV1Operation, GscdumpV1OperationId, GscdumpV1OperationInput, GscdumpV1OperationResponse, GscdumpV1RetryOptions, GscdumpV1SdkErrorCode, createGscdumpV1Client, isGscdumpV1Error } from "./http.mjs";
+import { CreateGscdumpRealtimeV1ClientOptions, GSCDUMP_REALTIME_V1_SDK_VERSION, GscdumpRealtimeV1Client, GscdumpRealtimeV1CursorStore, GscdumpRealtimeV1Error, GscdumpRealtimeV1ErrorCode, GscdumpRealtimeV1ErrorOptions, GscdumpRealtimeV1Freshness, GscdumpRealtimeV1Observation, GscdumpRealtimeV1ResyncReason, GscdumpRealtimeV1ResyncRequest, GscdumpRealtimeV1Runtime, GscdumpRealtimeV1Snapshot, GscdumpRealtimeV1SocketLike, GscdumpRealtimeV1TransportState, createGscdumpRealtimeV1Client } from "./realtime.mjs";
 export { type CreateGscdumpRealtimeV1ClientOptions, type CreateGscdumpV1ClientOptions, GSCDUMP_REALTIME_V1_SDK_VERSION, type GscdumpRealtimeV1Client, type GscdumpRealtimeV1CursorStore, GscdumpRealtimeV1Error, type GscdumpRealtimeV1ErrorCode, type GscdumpRealtimeV1ErrorOptions, type GscdumpRealtimeV1Freshness, type GscdumpRealtimeV1Observation, type GscdumpRealtimeV1ResyncReason, type GscdumpRealtimeV1ResyncRequest, type GscdumpRealtimeV1Runtime, type GscdumpRealtimeV1Snapshot, type GscdumpRealtimeV1SocketLike, type GscdumpRealtimeV1TransportState, type GscdumpV1Client, type GscdumpV1CredentialResolver, GscdumpV1Error, type GscdumpV1ErrorOptions, type GscdumpV1ExecuteOptions, type GscdumpV1HeadersResolver, type GscdumpV1Operation, type GscdumpV1OperationId, type GscdumpV1OperationInput, type GscdumpV1OperationResponse, type GscdumpV1RetryOptions, type GscdumpV1SdkErrorCode, createGscdumpRealtimeV1Client, createGscdumpV1Client, isGscdumpV1Error };