@heybox/hb-sdk 0.6.8-alpha.2 → 0.6.9-alpha.0

package/dist/index.cjs.js

@@ -2,6 +2,277 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+/**
+ * network.request 请求体形态校验与宿主失败诊断文案。
+ *
+ * @remarks
+ * App Host 的 heybox 客户端代发 transport 仅声明 form/json，不支持 multipart。
+ * 本地 Mock 若直接走 fetch 会“能通”，上线后却变成难以理解的 500 network_error。
+ * 因此在 SDK 侧统一提前拒绝 multipart，并在宿主伪装 HTTP 失败时给出可操作提示。
+ */
+/** multipart 不被 App Host 支持时的稳定说明（开发者可见）。 */
+const NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE = 'network.request 不支持 multipart/form-data。App Host 客户端代发仅支持 application/x-www-form-urlencoded（form）与 application/json；请将 data 编码为 form 字符串（例如 new URLSearchParams({...}).toString()）并设置 Content-Type: application/x-www-form-urlencoded。文件上传请使用专用上传能力，勿手写 multipart boundary。';
+/**
+ * 读取请求头中的 Content-Type（大小写不敏感）。
+ */
+function readNetworkContentType(headers) {
+    if (!headers) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.trim().toLowerCase() === 'content-type' && typeof value === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * 判断 Content-Type 是否声明为 multipart/form-data。
+ */
+function isMultipartContentType(contentType) {
+    return typeof contentType === 'string' && contentType.toLowerCase().includes('multipart/form-data');
+}
+/**
+ * 判断字符串 body 是否像手写 multipart 实体。
+ */
+function looksLikeMultipartBody(data) {
+    if (typeof data !== 'string') {
+        return false;
+    }
+    const trimmed = data.trimStart();
+    return trimmed.startsWith('--') && /content-disposition\s*:\s*form-data/i.test(data);
+}
+/**
+ * 判断公开请求配置是否使用了 Host 不支持的 multipart 形态。
+ */
+function isUnsupportedMultipartNetworkRequest(config) {
+    return isMultipartContentType(readNetworkContentType(config.headers)) || looksLikeMultipartBody(config.data);
+}
+function isPlainObject$2(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+/**
+ * 从宿主返回的“完成态”响应中提取更清晰的失败原因。
+ *
+ * @remarks
+ * Host 可能把 transport 不支持等内部错误包装成 HTTP 500 + `{ status: 'network_error', msg }`。
+ * 此时 `status=500` 并不代表目标站点返回了 500。
+ */
+function describeHostNetworkFailure(response) {
+    const data = response.data;
+    const hostStatus = isPlainObject$2(data) && typeof data.status === 'string' ? data.status : undefined;
+    const hostMsg = isPlainObject$2(data) && typeof data.msg === 'string'
+        ? data.msg
+        : isPlainObject$2(data) && typeof data.message === 'string'
+            ? data.message
+            : undefined;
+    const isHostNetworkError = hostStatus === 'network_error';
+    const mentionsUnsupportedShape = typeof hostMsg === 'string' &&
+        (hostMsg.includes('unsupported-request-shape') || hostMsg.includes('unsupported_request_shape'));
+    const requestLooksMultipart = isUnsupportedMultipartNetworkRequest(response.config || {});
+    if (!isHostNetworkError && !mentionsUnsupportedShape && !(requestLooksMultipart && response.status >= 500)) {
+        return undefined;
+    }
+    const lines = [
+        '原因: 这是宿主网络层失败，不是目标 URL 的业务 HTTP 响应。',
+    ];
+    if (hostMsg) {
+        lines.push(`宿主信息: ${hostMsg}`);
+    }
+    if (requestLooksMultipart || mentionsUnsupportedShape) {
+        lines.push(NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
+    }
+    else if (isHostNetworkError) {
+        lines.push('请检查请求 URL、headers、body 编码与 Host 网络权限；本地 Mock 与 App Host 能力并不完全一致。');
+    }
+    return lines.join(' ');
+}
+
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Mock Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+const DATA_PREVIEW_MAX_CHARS = 500;
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'proxy-authorization',
+    'set-cookie',
+    'token',
+    'x-pkey',
+    'api-key',
+    'apikey',
+    'x-api-key',
+    'x-auth-token',
+    'x-access-token',
+    'session',
+    'session-id',
+    'jwt',
+    'refresh-token',
+    'x-csrf-token',
+]);
+/** 敏感字段名：header / query / body key 共用。 */
+const SENSITIVE_KEY_PATTERN = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+function sanitizeNetworkRequestUrl(url) {
+    if (!url) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        redactUrlSearchParams(parsed.searchParams);
+        if (parsed.hash && parsed.hash.length > 1) {
+            const hashBody = parsed.hash.slice(1);
+            if (hashBody.includes('=')) {
+                const hashParams = new URLSearchParams(hashBody);
+                if (redactUrlSearchParams(hashParams)) {
+                    parsed.hash = hashParams.toString();
+                }
+            }
+        }
+        return parsed.toString();
+    }
+    catch {
+        return redactSensitivePairsInRawText(url);
+    }
+}
+/**
+ * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
+ */
+function sanitizeNetworkHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+        key,
+        isSensitiveNetworkHeaderName(key) ? '[redacted]' : value,
+    ]));
+}
+/**
+ * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
+ */
+function previewNetworkData(data) {
+    if (data === undefined) {
+        return undefined;
+    }
+    if (typeof data === 'string') {
+        return previewNetworkStringData(data);
+    }
+    if (typeof data === 'number' || typeof data === 'boolean' || data === null) {
+        return data;
+    }
+    try {
+        const sanitized = sanitizeNetworkDataValue(data);
+        const serialized = JSON.stringify(sanitized);
+        if (serialized === undefined) {
+            return '[unserializable]';
+        }
+        if (serialized.length <= DATA_PREVIEW_MAX_CHARS) {
+            return sanitized;
+        }
+        return truncateText(serialized, DATA_PREVIEW_MAX_CHARS);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+function sanitizeDiagnosticMessage(message) {
+    if (!message) {
+        return message;
+    }
+    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+}
+function isSensitiveNetworkHeaderName(headerName) {
+    const normalized = headerName.trim().toLowerCase();
+    return (SENSITIVE_HEADER_NAMES.has(normalized) ||
+        isSensitiveNetworkKey(normalized) ||
+        normalized.startsWith('x-heybox-') ||
+        normalized.startsWith('x-xhh-'));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key.trim());
+}
+function previewNetworkStringData(data) {
+    const trimmed = data.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+        try {
+            return previewNetworkData(JSON.parse(trimmed));
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (trimmed.includes('=') && !trimmed.includes('\n') && trimmed.length <= DATA_PREVIEW_MAX_CHARS * 2) {
+        try {
+            const params = new URLSearchParams(trimmed);
+            if ([...params.keys()].length > 0) {
+                const redacted = Object.fromEntries([...params.entries()].map(([key, value]) => [
+                    key,
+                    isSensitiveNetworkKey(key) ? '[redacted]' : value,
+                ]));
+                return previewNetworkData(redacted);
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return truncateText(redactSensitivePairsInRawText(data), DATA_PREVIEW_MAX_CHARS);
+}
+function sanitizeNetworkDataValue(value) {
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map(item => sanitizeNetworkDataValue(item));
+    }
+    if (!isPlainObject$1(value)) {
+        if (typeof value === 'string') {
+            return truncateText(value, DATA_PREVIEW_MAX_CHARS);
+        }
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        isSensitiveNetworkKey(key) ? '[redacted]' : sanitizeNetworkDataValue(item),
+    ]));
+}
+function redactUrlSearchParams(params) {
+    let changed = false;
+    for (const key of [...params.keys()]) {
+        if (isSensitiveNetworkKey(key)) {
+            params.set(key, '[redacted]');
+            changed = true;
+        }
+    }
+    return changed;
+}
+function redactSensitivePairsInRawText(text) {
+    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
+        if (!isSensitiveNetworkKey(key)) {
+            return full;
+        }
+        return `${prefix}${key}=[redacted]`;
+    });
+}
+function truncateText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, maxChars)}…(truncated, total=${value.length})`;
+}
+function isPlainObject$1(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+
 /**
  * SDK 对外抛出的标准 bridge / runtime 错误类型。
  *
@@ -64,7 +335,14 @@ class HbMiniProgramNetworkError extends Error {
      * @param response 已完成请求的标准化网络响应。
      */
     constructor(response) {
-        super(`network.request failed with status ${response.status}`);
+        const method = (response.config.method || 'GET').toUpperCase();
+        // 诊断文案使用脱敏 URL，避免 query 中的 token 等经 error.message 泄漏。
+        const url = sanitizeNetworkRequestUrl(response.config.url || '');
+        const statusText = response.statusText ? ` ${response.statusText}` : '';
+        const baseMessage = `network.request failed with status ${response.status}${statusText}: ${method} ${url}`;
+        // 宿主可能把 transport 不支持等内部错误伪装成 HTTP 500；补充可操作提示。
+        const hostHint = describeHostNetworkFailure(response);
+        super(hostHint ? `${baseMessage}\n${hostHint}` : baseMessage);
         this.name = 'HbMiniProgramNetworkError';
         this.status = response.status;
         this.data = response.data;
@@ -325,7 +603,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8-alpha.2';
+    : '0.6.9-alpha.0';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。
@@ -892,6 +1170,77 @@ function createStorageModule(requester) {
     };
 }
 
+const LOG_PREFIX = '[hb-sdk][network.request]';
+/**
+ * 记录 `network.request` 失败，保证异常路径在开发者控制台可观测。
+ *
+ * @remarks
+ * - 仅用于诊断，不改变错误抛出语义。
+ * - 会脱敏 token/cookie 等敏感头与字段，并截断 body 预览。
+ * - detail 构造与 logger 调用均包在 try 内，日志失败不得影响业务错误抛出。
+ */
+function logNetworkRequestFailure(config, error, extras) {
+    try {
+        const consoleRef = typeof console === 'undefined' ? undefined : console;
+        const logger = consoleRef?.warn || consoleRef?.error || consoleRef?.log;
+        if (!logger) {
+            return;
+        }
+        const detail = createNetworkRequestFailureLog(config, error, extras);
+        logger.call(consoleRef, LOG_PREFIX, formatNetworkRequestFailureMessage(detail), detail);
+    }
+    catch {
+        // 日志失败不得影响业务错误抛出。
+    }
+}
+function createNetworkRequestFailureLog(config, error, extras) {
+    const method = (config.method || 'GET').toUpperCase();
+    const detail = {
+        kind: extras.kind,
+        method,
+        url: sanitizeNetworkRequestUrl(config.url),
+    };
+    if (typeof extras.status === 'number') {
+        detail.status = extras.status;
+    }
+    else if (error instanceof HbMiniProgramNetworkError) {
+        detail.status = error.status;
+    }
+    if (typeof extras.statusText === 'string' && extras.statusText) {
+        detail.statusText = extras.statusText;
+    }
+    // NetworkError 已有 method/url/status 结构化字段；不再回写 message，避免 raw URL 二次泄漏。
+    if (!(error instanceof HbMiniProgramNetworkError)) {
+        if (error instanceof HbMiniProgramSDKError) {
+            detail.code = error.code;
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+        else if (error instanceof Error) {
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+    }
+    if (config.timeout !== undefined) {
+        detail.timeout = config.timeout;
+    }
+    if (config.withCredentials !== undefined) {
+        detail.withCredentials = config.withCredentials;
+    }
+    const headers = sanitizeNetworkHeaders(extras.headers || config.headers);
+    if (Object.keys(headers).length > 0) {
+        detail.headers = headers;
+    }
+    const dataPreview = previewNetworkData(extras.data !== undefined ? extras.data : config.data);
+    if (dataPreview !== undefined) {
+        detail.dataPreview = dataPreview;
+    }
+    return detail;
+}
+function formatNetworkRequestFailureMessage(detail) {
+    const statusPart = detail.status === undefined ? '' : ` status=${detail.status}`;
+    const codePart = detail.code ? ` code=${detail.code}` : '';
+    return `${detail.kind} ${detail.method} ${detail.url}${statusPart}${codePart}`;
+}
+
 const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
@@ -935,6 +1284,9 @@ function normalizeHeaders(headers) {
     return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => (typeof value === 'string' ? [[key, value]] : [])));
 }
 function toNetworkResponse(payload, config) {
+    if (payload == null || typeof payload !== 'object') {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的响应', payload);
+    }
     if (typeof payload.status !== 'number' || Number.isNaN(payload.status)) {
         throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的 status', payload);
     }
@@ -969,12 +1321,56 @@ function toNetworkResponse(payload, config) {
  */
 async function request(requester, config) {
     const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
-    const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
-    const response = toNetworkResponse(responsePayload, config);
-    if (!validateStatus(response.status)) {
-        throw new HbMiniProgramNetworkError(response);
+    try {
+        assertSupportedPublicNetworkRequest(config);
+        const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+        const response = toNetworkResponse(responsePayload, config);
+        if (!validateStatus(response.status)) {
+            const error = new HbMiniProgramNetworkError(response);
+            logNetworkRequestFailure(config, error, {
+                kind: 'http_status',
+                status: response.status,
+                statusText: response.statusText,
+                data: response.data,
+                headers: response.headers,
+            });
+            throw error;
+        }
+        return response;
+    }
+    catch (error) {
+        if (error instanceof HbMiniProgramNetworkError) {
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_PARAMS') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'bridge_error',
+            });
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_NETWORK_RESPONSE') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'invalid_response',
+                data: error.data,
+            });
+            throw error;
+        }
+        logNetworkRequestFailure(config, error, {
+            kind: error instanceof HbMiniProgramSDKError ? 'bridge_error' : 'unknown',
+        });
+        throw error;
+    }
+}
+/**
+ * 在进入 bridge 前拒绝 Host 能力明确不支持的公开请求形态。
+ *
+ * @remarks
+ * 提前失败可避免本地 Mock（fetch）与 App Host（heybox）能力差造成“本地成功、上线 500”。
+ */
+function assertSupportedPublicNetworkRequest(config) {
+    if (isUnsupportedMultipartNetworkRequest(config)) {
+        throw createSDKError('INVALID_PARAMS', NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
     }
-    return response;
 }
 /**
  * 创建 network 模块。