@gscdump/sdk 1.4.0 → 1.4.2

package/dist/v1/http.mjs

@@ -0,0 +1,427 @@
+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(buildOperationPath, surface, operation, input, options) {
+	let path;
+	if (operation.request.params === null) {
+		assertAbsentLocation(operation.id, "params", input.params);
+		path = buildOperationPath(surface, operation);
+	} else try {
+		path = buildOperationPath(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 retryOptions = resolveRetryOptions(options.retry);
+	const apiRoot = options.apiRoot ?? DEFAULT_API_ROOT;
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	let runtimePromise;
+	if (typeof fetchImpl !== "function") throw new TypeError("createGscdumpV1Client requires a fetch implementation in this runtime.");
+	function getRuntime() {
+		return runtimePromise ??= import("@gscdump/contracts/v1/http").then(({ buildHttpOperationPath: buildOperationPath, createGscdumpV1Protocol }) => {
+			const protocol = createGscdumpV1Protocol();
+			return {
+				buildOperationPath,
+				operations: operationLookup(protocol),
+				protocol
+			};
+		});
+	}
+	const execute = executeUntyped;
+	async function executeUntyped(operationId, input, executeOptions = {}) {
+		const { buildOperationPath, operations, protocol } = await getRuntime();
+		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(buildOperationPath, 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 };