backport 8750 (add documentation_url to error messages) (#8751)

* add documentation_url

* changeset

* fix nested indenting

Author: emily-shen

.changeset/lovely-lemons-count.md

@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+fix: include documentation_url in API Errors if provided

packages/wrangler/src/__tests__/cfetch-utils.test.ts

@@ -47,18 +47,30 @@ describe("throwFetchError", () => {
 	mockAccountId();
 	mockApiToken();
 	runInTempDir();
-	mockConsoleMethods();
+	const std = mockConsoleMethods();
 
-	it("should include api errors and messages in error", async () => {
+	it("should include api errors, messages and documentation_url in error", async () => {
 		msw.use(
 			http.get("*/user", () => {
 				return HttpResponse.json(
 					createFetchResult(
 						null,
 						false,
 						[
-							{ code: 10001, message: "error one" },
-							{ code: 10002, message: "error two" },
+							{
+								code: 10001,
+								message: "error one",
+								documentation_url: "https://example.com/1",
+							},
+							{
+								code: 10002,
+								message: "error two",
+								documentation_url: "https://example.com/2",
+							},
+							{
+								code: 10003,
+								message: "error three",
+							},
 						],
 						["message one", "message two"]
 					)
@@ -68,8 +80,15 @@ describe("throwFetchError", () => {
 		await expect(runWrangler("whoami")).rejects.toMatchObject({
 			text: "A request to the Cloudflare API (/user) failed.",
 			notes: [
-				{ text: "error one [code: 10001]" },
-				{ text: "error two [code: 10002]" },
+				{
+					text: "error one [code: 10001]\nTo learn more about this error, visit: https://example.com/1",
+				},
+				{
+					text: "error two [code: 10002]\nTo learn more about this error, visit: https://example.com/2",
+				},
+				{
+					text: "error three [code: 10003]",
+				},
 				{ text: "message one" },
 				{ text: "message two" },
 				{
@@ -79,19 +98,100 @@ describe("throwFetchError", () => {
 		});
 	});
 
+	it("nested", async () => {
+		msw.use(
+			http.get("*/user", () => {
+				return HttpResponse.json(
+					createFetchResult(
+						null,
+						false,
+						[
+							{
+								code: 10001,
+								message: "error one",
+								documentation_url: "https://example.com/1",
+								error_chain: [
+									{
+										code: 10002,
+										message: "error two",
+										error_chain: [
+											{
+												code: 10003,
+												message: "error three",
+												documentation_url: "https://example.com/3",
+												error_chain: [
+													{
+														code: 10004,
+														message: "error 4",
+														documentation_url: "https://example.com/4",
+													},
+												],
+											},
+										],
+									},
+								],
+							},
+						],
+						["message one", "message two"]
+					)
+				);
+			})
+		);
+		await expect(runWrangler("whoami")).rejects.toMatchInlineSnapshot(
+			`[APIError: A request to the Cloudflare API (/user) failed.]`
+		);
+
+		expect(std.out).toMatchInlineSnapshot(`
+			"Getting User settings...
+
+			X [ERROR] A request to the Cloudflare API (/user) failed.
+
+			  error one [code: 10001]
+			  To learn more about this error, visit: https://example.com/1
+
+			  - error two [code: 10002]
+
+			    - error three [code: 10003]
+			      To learn more about this error, visit: https://example.com/3
+
+			      - error 4 [code: 10004]
+			        To learn more about this error, visit: https://example.com/4
+
+			  message one
+			  message two
+
+			  If you think this is a bug, please open an issue at:
+			  https://github.com/cloudflare/workers-sdk/issues/new/choose
+
+			"
+		`);
+	});
+
 	it("should include api errors without messages", async () => {
 		msw.use(
 			http.get("*/user", () => {
 				return HttpResponse.json({
 					result: null,
 					success: false,
-					errors: [{ code: 10000, message: "error" }],
+					errors: [
+						{
+							code: 10000,
+							message: "error",
+							documentation_url: "https://example.com/1",
+						},
+						{ code: 10001, message: "error 1" },
+					],
 				});
 			})
 		);
 		await expect(runWrangler("whoami")).rejects.toMatchObject({
 			text: "A request to the Cloudflare API (/user) failed.",
-			notes: [{ text: "error [code: 10000]" }],
+			notes: [
+				{
+					text: "error [code: 10000]\nTo learn more about this error, visit: https://example.com/1",
+				},
+				{ text: "error 1 [code: 10001]" },
+			],
 		});
 	});
 });

packages/wrangler/src/cfetch/errors.ts

@@ -2,6 +2,7 @@ import { ParseError } from "../parse";
 
 export interface FetchError {
 	code: number;
+	documentation_url?: string;
 	message: string;
 	error_chain?: FetchError[];
 }

packages/wrangler/src/cfetch/index.ts

@@ -198,15 +198,19 @@ function hasCursor(result_info: unknown): result_info is { cursor: string } {
 }
 
 function renderError(err: FetchError, level = 0): string {
+	const indent = "  ".repeat(level);
 	const chainedMessages =
 		err.error_chain
 			?.map(
 				(chainedError) =>
-					`\n${"  ".repeat(level)}- ${renderError(chainedError, level + 1)}`
+					`\n\n${indent}- ${renderError(chainedError, level + 1)}`
 			)
 			.join("\n") ?? "";
 	return (
 		(err.code ? `${err.message} [code: ${err.code}]` : err.message) +
+		(err.documentation_url
+			? `\n${indent}To learn more about this error, visit: ${err.documentation_url}`
+			: "") +
 		chainedMessages
 	);
 }