@kubb/adapter-oas 5.0.0-beta.107 → 5.0.0-beta.108

package/dist/index.cjs

@@ -247,6 +247,20 @@ function pascalCase(text, { prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/errors.ts
+/**
+* Extracts a human-readable message from any thrown value.
+*
+* @example
+* ```ts
+* getErrorMessage(new Error('oops')) // 'oops'
+* getErrorMessage('plain string')    // 'plain string'
+* ```
+*/
+function getErrorMessage(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+//#endregion
 //#region ../../internals/utils/src/runtime.ts
 /**
 * Detects the JavaScript runtime executing the current process and exposes its name and version.
@@ -349,11 +363,50 @@ async function read(path) {
 //#endregion
 //#region src/load/source.ts
 const urlRegExp = /^https?:\/+/i;
+/**
+* Node reports every connection failure as `TypeError: fetch failed` and keeps the useful part
+* (`connect ECONNREFUSED 127.0.0.1:8000`) on `cause`, one level deeper again when a host resolves
+* to several addresses and the attempts collect into an `AggregateError`.
+*/
+function describeFetchFailure(error) {
+	if (error instanceof AggregateError && error.errors.length > 0) return describeFetchFailure(error.errors[0]);
+	if (error instanceof Error && error.cause instanceof Error) return describeFetchFailure(error.cause) || error.message;
+	return getErrorMessage(error);
+}
+function helpForStatus(status) {
+	if (status === 401 || status === 403) return "The server refused the request. Kubb sends no credentials, so serve the document without authentication or download it and set `input` to the local file.";
+	if (status === 404) return "Check the URL. Open it in a browser or with `curl` to confirm it serves the OpenAPI document.";
+	if (status >= 500) return "The server failed while serving the document. Check that it is healthy, then run Kubb again.";
+	return "Open the URL in a browser or with `curl` to see what the server returns, then point `input` at a URL that serves the OpenAPI document.";
+}
+async function fetchSource(url) {
+	try {
+		return await fetch(url);
+	} catch (error) {
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.inputUnreachable,
+			severity: "error",
+			message: `Cannot reach ${url.href}: ${describeFetchFailure(error)}`,
+			help: "Check that the host is running and reachable from this machine. For a local server, start it and confirm the port matches the one in `input`.",
+			location: { kind: "config" },
+			cause: error instanceof Error ? error : void 0
+		});
+	}
+}
 async function readSource(sourcePath) {
 	if (urlRegExp.test(sourcePath)) {
 		const url = new URL(sourcePath);
-		const response = await fetch(url);
-		if (!response.ok) throw new Error(`Cannot fetch the OAS document at ${url.href} (HTTP ${response.status})`);
+		const response = await fetchSource(url);
+		if (!response.ok) {
+			const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+			throw new _kubb_core.Diagnostics.Error({
+				code: _kubb_core.Diagnostics.code.inputRequestFailed,
+				severity: "error",
+				message: `The server at ${url.href} answered with HTTP ${status} instead of the OpenAPI document.`,
+				help: helpForStatus(response.status),
+				location: { kind: "config" }
+			});
+		}
 		return response.text();
 	}
 	return read(sourcePath);
@@ -369,7 +422,8 @@ async function resolveSource(sourcePath) {
 }
 /**
 * Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
-* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* URLs are skipped: a remote input reports `KUBB_INPUT_REQUEST_FAILED` or `KUBB_INPUT_UNREACHABLE`
+* from the request itself. A malformed but readable file is left for `parseDocument` to surface
 * its parse error instead.
 */
 async function assertInputExists(input) {