@cnbcool/cnb-api-generate 2.21.3 → 2.21.4

package/client/core.ts

@@ -5,6 +5,8 @@ import { fetchResponseHandler } from "./fetch-response-handler";
 import { generateUniqueId } from './utils/generate-unique-id';
 import { resolveToken } from './utils/resolve-token';
 import { resolveApiDomain } from './utils/resolve-api-domain';
+import { wrapFetchError } from './utils/wrap-fetch-error';
+import { describeFetchError, isNetworkError } from './utils/fetch-error';
 
 /**
  * 将 buffer 写入临时文件并返回文件路径
@@ -128,6 +130,27 @@ async function formatResponse(data: any, response: any) {
   return responseData;
 }
 
+/**
+ * 网络层失败时给出一条能定位问题的错误响应，而不是把 `TypeError: fetch failed` 抛出去。
+ * 输出结构与正常响应保持一致（含 status / data.error），下游退出码逻辑照常生效。
+ * 错误文案直接用底层原始信息，不另做翻译。
+ */
+function buildNetworkErrorResponse(err: any, url: string) {
+  return {
+    status: 0,
+    error: {
+      reason: describeFetchError(err),
+      message: err?.message || String(err),
+      url,
+    },
+    data: {
+      error: describeFetchError(err),
+      message: err?.message || String(err),
+      request_url: url,
+    },
+  };
+}
+
 async function clientFetch(data: any): Promise<any> {
   const token = await resolveToken();
   const domain = resolveApiDomain()
@@ -140,17 +163,24 @@ async function clientFetch(data: any): Promise<any> {
     }
   }
 
-  const response = await fetch(urlParse.href, {
-    method: data.method.toUpperCase(),
-    body: data.data ? JSON.stringify(data.data) : undefined,
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: 'application/vnd.cnb.api+json',
-      // 当请求体存在时，附加 Content-Type，避免后端无法识别 JSON body
-      ...(data.data ? { 'Content-Type': 'application/json' } : {}),
-      ...(data?.header || {}),
-    },
-  });
+  let response: Response;
+  try {
+    response = await wrapFetchError(fetch)(urlParse.href, {
+      method: data.method.toUpperCase(),
+      body: data.data ? JSON.stringify(data.data) : undefined,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.cnb.api+json',
+        // 当请求体存在时，附加 Content-Type，避免后端无法识别 JSON body
+        ...(data.data ? { 'Content-Type': 'application/json' } : {}),
+        ...(data?.header || {}),
+      },
+    });
+  } catch (err) {
+    if (!isNetworkError(err)) throw err;
+    // 不打印到 stderr（避免与格式化输出混在一起），直接把原因放进响应体
+    return buildNetworkErrorResponse(err, urlParse.href);
+  }
 
   return await formatResponse(data, response);
 }

package/client/lib/build-helpers.ts

@@ -8,6 +8,7 @@
 
 import { resolveToken } from '../utils/resolve-token';
 import { resolveApiDomain } from '../utils/resolve-api-domain';
+import { wrapFetchError } from '../utils/wrap-fetch-error';
 
 /** CNB 构建号格式：cnb-xxx-xxxxxxxxx（字母/数字组成的两段） */
 export const SN_PATTERN = /^cnb-[a-z0-9]+-[a-z0-9]+$/i;
@@ -26,7 +27,7 @@ export function invalidSnMessage(sn: string): string {
 }
 
 export async function apiRequest(url: string, headers: Record<string, string>): Promise<any> {
-  const res = await fetch(url, { headers });
+  const res = await wrapFetchError(fetch)(url, { headers });
   if (!res.ok) {
     // 注意：错误消息中暴露 URL 是有意的，便于调试。
     // 本项目所有 API 凭证通过 Authorization header 传递，不走 query string，
@@ -37,7 +38,7 @@ export async function apiRequest(url: string, headers: Record<string, string>):
 }
 
 export async function apiRequestText(url: string, headers: Record<string, string>): Promise<string> {
-  const res = await fetch(url, { headers });
+  const res = await wrapFetchError(fetch)(url, { headers });
   if (!res.ok) {
     // 见 apiRequest 注释
     throw new Error(`请求失败: ${res.status} ${res.statusText} — ${url}`);

package/client/lib/login.ts

@@ -10,6 +10,7 @@ import {
 } from '../utils/device-auth';
 import { tryOpenBrowser } from '../utils/open-browser';
 import { resolvePlatformUrl } from '../utils/resolve-platform-host';
+import { isNetworkError, printFetchError } from '../utils/fetch-error';
 
 export function registerLoginCommand(program: Command): void {
   program
@@ -98,7 +99,14 @@ export function registerLoginCommand(program: Command): void {
           console.log(`Token 已保存到 ${getTokenPath()}`);
         }
       } catch (err: any) {
-        console.error(`\n登录失败: ${err.message}`);
+        console.error('');
+        if (isNetworkError(err)) {
+          // 网络层失败（DNS / 连接 / 证书 / 超时等），原样输出底层错误信息，不做翻译
+          printFetchError(err, '登录失败');
+          console.error('提示：若网络需要代理，请先设置 HTTPS_PROXY 后重试；也可用 --debug 查看请求详情。');
+        } else {
+          console.error(`登录失败: ${err?.message || err}`);
+        }
         process.exit(1);
       }
     });

package/client/utils/do-token-request.ts

@@ -1,4 +1,5 @@
 import type { LoginConfig, TokenResponse, TokenErrorResponse } from './types';
+import { wrapFetchError } from './wrap-fetch-error';
 
 const GRANT_TYPE_DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code';
 
@@ -24,7 +25,7 @@ export async function doTokenRequest(
     console.log(`[DEBUG] POST ${tokenURL} body=${form.toString()}`);
   }
 
-  const resp = await fetch(tokenURL, {
+  const resp = await wrapFetchError(fetch)(tokenURL, {
     method: 'POST',
     headers,
     body: form.toString(),

package/client/utils/fetch-error.ts

@@ -0,0 +1,71 @@
+import type { FetchErrorLike } from './wrap-fetch-error';
+
+/**
+ * fetch 抛出的 `TypeError: fetch failed` 本身没有信息量，
+ * 真正的原因（ENOTFOUND / ECONNREFUSED / 证书 / 超时…）藏在 err.cause 里。
+ *
+ * 这里只做「把底层原始信息摊平」，不做翻译：错误文案由 Node / undici 提供，
+ * 随版本更新自动同步，也不会因为自造措辞与真实原因对不上而误导排查。
+ */
+
+/** 错误对象的宽松视图（Node 的 err.cause / err.code 不在标准 Error 类型里） */
+type AnyError = FetchErrorLike & {
+  code?: string;
+  cause?: any;
+};
+
+/** 从 aggregate error（Node 双栈连接失败时常见）里挑一个最能说明问题的子错误 */
+function pickCauseError(cause: any): any {
+  if (!cause) return undefined;
+  if (Array.isArray(cause.errors) && cause.errors.length > 0) {
+    // 优先选非 ECONNREFUSED 的错误：双栈下 IPv4 被拒、IPv6 缺路由，后者更贴近真实原因
+    const meaningful = cause.errors.find((e: any) => e && e.code && e.code !== 'ECONNREFUSED');
+    return meaningful || cause.errors[0];
+  }
+  return cause;
+}
+
+/**
+ * 判断是否为网络层失败（fetch 抛出的 TypeError / 超时 / 被中断）。
+ * HTTP 4xx/5xx 不会走到这里——那是响应，不是异常。
+ */
+export function isNetworkError(err: any): boolean {
+  if (!err) return false;
+  return err.name === 'TypeError' || err.name === 'AbortError' || err.name === 'TimeoutError' || !!err.cause;
+}
+
+/**
+ * 生成错误描述：优先用底层原始信息，并附上错误码。
+ * HTTP 状态码层面的错误（4xx/5xx）不走这里，由调用方自行拼装。
+ *
+ * @param err 捕获到的错误
+ * @returns 形如 `getaddrinfo ENOTFOUND abc.invalid.cool（ENOTFOUND）`
+ */
+export function describeFetchError(err: AnyError | undefined): string {
+  // new Error('') 的 message 为空串但不是 falsy，需显式判空
+  const rawMessage = err?.message || (err ? String(err) : '');
+  const cause = pickCauseError(err?.cause);
+  const code = cause?.code || err?.code;
+  const causeMessage = cause?.message || '';
+  // `fetch failed` 是 fetch 的兜底文案，有错误码时只给码和底层信息，免得输出「fetch failed（ENOTFOUND）」
+  const hasDetail = !!causeMessage || !!code;
+  const usableRaw = rawMessage && rawMessage !== 'Error' && !(hasDetail && rawMessage === 'fetch failed') ? rawMessage : '';
+  const reason = causeMessage || usableRaw || code || '未知错误';
+  // 底层 message 有时已含错误码（如 getaddrinfo ENOTFOUND x），避免重复追加
+  return code && !reason.includes(code) ? `${reason}（${code}）` : reason;
+}
+
+/**
+ * 直接打印网络错误提示到 stderr。
+ * 保留 `错误：` / `Error:` 双语的仓库惯例，两行都输出原始信息。
+ *
+ * @param err 捕获到的错误
+ * @param context 可选的上下文描述，如「请求 API 失败」「获取 device code 失败」
+ */
+export function printFetchError(err: AnyError | undefined, context?: string): void {
+  const head = context ? `${context}：` : '';
+  console.error(`错误：${head}${describeFetchError(err)}`);
+  console.error(`Error: ${head}${err?.message || err}`);
+  const url = err?.requestURL;
+  if (url) console.error(`请求地址: ${url}`);
+}

package/client/utils/refresh-token.ts

@@ -1,5 +1,6 @@
 import { saveToken } from './save-token';
 import type { TokenStore, TokenResponse } from './types';
+import { wrapFetchError } from './wrap-fetch-error';
 
 /**
  * 使用 refresh_token 刷新 access_token。
@@ -20,7 +21,7 @@ export async function refreshAccessToken(store: TokenStore): Promise<string> {
   form.set('client_id', clientID);
 
   const nowSec = Math.floor(Date.now() / 1000);
-  const resp = await fetch(tokenURL, {
+  const resp = await wrapFetchError(fetch)(tokenURL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
     body: form.toString(),

package/client/utils/request-device-code.ts

@@ -1,4 +1,5 @@
 import type { LoginConfig, DeviceAuthResponse } from './types';
+import { wrapFetchError } from './wrap-fetch-error';
 
 /**
  * 调用 /oauth2/device/auth 端点获取 device_code / user_code 等。
@@ -17,7 +18,7 @@ export async function requestDeviceCode(cfg: LoginConfig, signal?: AbortSignal):
     console.log(`[DEBUG] POST ${endpoint} body=${form.toString()}`);
   }
 
-  const resp = await fetch(endpoint, {
+  const resp = await wrapFetchError(fetch)(endpoint, {
     method: 'POST',
     headers,
     body: form.toString(),

package/client/utils/upload.ts

@@ -9,6 +9,7 @@
 import fs from 'fs';
 import nodePath from 'path';
 import type { ResolvedShortcut } from '../shortcuts';
+import { wrapFetchError } from './wrap-fetch-error';
 
 /** 常见文件扩展名 → MIME 类型映射（仅用于上传场景，不引入外部依赖） */
 const MIME_MAP: Record<string, string> = {
@@ -199,7 +200,7 @@ async function putFileStream(
   const fileStream = fs.createReadStream(filePath);
   let putResponse: Response;
   try {
-    putResponse = await fetch(uploadUrl, {
+    putResponse = await wrapFetchError(fetch)(uploadUrl, {
       method: 'PUT',
       headers: { 'Content-Type': contentType, 'Content-Length': String(fileSize) },
       body: fileStream as any,

package/client/utils/wrap-fetch-error.ts

@@ -0,0 +1,42 @@
+/**
+ * fetch 失败时抛出的 `TypeError: fetch failed` 丢掉了真正的原因，
+ * 这里统一补上请求地址（err.requestURL），供上层拼装可读的错误提示。
+ */
+
+/** 带请求地址的 fetch 错误 */
+export interface FetchErrorLike extends Error {
+  requestURL?: string;
+}
+
+/**
+ * 给 fetch 错误挂上请求地址，方便上层说明「哪个地址失败了」。
+ * 不修改原始 message，避免影响既有日志与测试断言。
+ */
+export function createFetchError(err: unknown, url?: string): FetchErrorLike {
+  const error: FetchErrorLike = err instanceof Error ? err : new Error(String(err));
+  if (url && !error.requestURL) {
+    try {
+      error.requestURL = url;
+    } catch {
+      // 只读属性等异常场景直接忽略，不影响主流程
+    }
+  }
+  return error;
+}
+
+/**
+ * 包装 fetch 函数：仅在请求抛错（网络层失败）时附加 requestURL。
+ * 用法：`const wrappedFetch = wrapFetchError(fetch); await wrappedFetch(url, init)`
+ */
+export function wrapFetchError(
+  fetchImpl: typeof fetch,
+): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response> {
+  return async function wrappedFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const url = typeof input === 'string' ? input : (input as any)?.url || String(input);
+    try {
+      return await fetchImpl(input, init);
+    } catch (err) {
+      throw createFetchError(err, url);
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "2.21.3",
+  "version": "2.21.4",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",