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

package/types/miniapp-publish/index.d.ts

@@ -51,3 +51,80 @@ export interface ValidateUploadTotalSizeOptions {
 }
 export declare function validateUploadTotalSize(items: UploadSizeItem[], options?: ValidateUploadTotalSizeOptions): "构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy" | undefined;
 export declare function shouldUploadDistFile(relativePath: string): boolean;
+/** 参与整包签名和上传会话映射的构建产物文件。 */
+export interface MiniappArtifactFile {
+    /** 使用 `/` 分隔的构建产物相对路径。 */
+    relativePath: string;
+    /** 文件字节数。 */
+    size: number;
+}
+/** 服务端上传会话返回的文件映射。 */
+export interface MiniappUploadSessionFile {
+    /** 与创建会话时提交值一致的相对路径。 */
+    relative_path: string;
+    /** 服务端签发的完整上传 key。 */
+    key: string;
+    /** 服务端记录的文件字节数。 */
+    size: number;
+}
+/**
+ * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ *
+ * @param files 待处理的构建产物文件。
+ * @returns 保留输入附加字段的有序文件列表。
+ * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ */
+export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFile>(files: readonly T[]): (T & {
+    relativePath: string;
+})[];
+/**
+ * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
+ *
+ * @param files 待上传的构建产物文件。
+ * @param options 小程序和长度限制配置。
+ * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ */
+export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
+    miniProgramId: string;
+    maxLength?: number;
+}): string | undefined;
+/**
+ * 创建 v1 整包签名头。
+ *
+ * @param fileCount 参与签名的文件数量。
+ * @returns 包含协议标识和文件数量的字节数组。
+ * @throws 文件数量超出协议范围时抛出错误。
+ */
+export declare function createMiniappArtifactSignatureHeader(fileCount: number): Uint8Array<ArrayBuffer>;
+/**
+ * 创建单个文件的 v1 framing header。
+ *
+ * @param file 已规范化或待校验的构建产物文件。
+ * @returns 包含路径长度、路径和文件大小的字节数组。
+ * @throws 文件路径或大小非法时抛出错误。
+ */
+export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFile): Uint8Array<ArrayBuffer>;
+/**
+ * 校验服务端 session 文件映射，并计算仍需上传的文件。
+ *
+ * @param localFiles 本地构建产物文件。
+ * @param serverFiles 服务端签发的文件映射。
+ * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @returns 完整映射、待上传文件和已确认 key。
+ * @throws 服务端映射与本地产物不一致时抛出错误。
+ */
+export declare function resolveMiniappUploadSessionFiles<T extends MiniappArtifactFile>(localFiles: readonly T[], serverFiles: readonly MiniappUploadSessionFile[], uploadedKeys: readonly string[]): {
+    files: {
+        file: T & {
+            relativePath: string;
+        };
+        key: string;
+    }[];
+    missingFiles: {
+        file: T & {
+            relativePath: string;
+        };
+        key: string;
+    }[];
+    uploadedKeys: string[];
+};

package/types/modules/network/index.d.ts

@@ -1,5 +1,7 @@
 import type { MiniProgramRequester } from '../../core/client';
 export { NETWORK_REQUEST_METHOD } from '../../protocol/capabilities';
+export { createNetworkRequestFailureLog, formatNetworkRequestFailureMessage, logNetworkRequestFailure, previewNetworkData, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from './observability';
+export { describeHostNetworkFailure, isMultipartContentType, isUnsupportedMultipartNetworkRequest, looksLikeMultipartBody, NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE, readNetworkContentType, } from './request-shape';
 /** `network.request` 请求头。 */
 export type MiniProgramNetworkHeaders = Record<string, string>;
 /** `network.request` 查询参数。 */

package/types/modules/network/observability.d.ts

@@ -0,0 +1,39 @@
+import type { MiniProgramNetworkHeaders, MiniProgramNetworkRequestConfig } from './index';
+export { previewNetworkData, redactNetworkLogValue, sanitizeDiagnosticMessage, sanitizeNetworkHeaders, sanitizeNetworkRequestUrl, } from '../../core/network-sanitize';
+export type NetworkRequestFailureKind = 'http_status' | 'invalid_response' | 'bridge_error' | 'unknown';
+export interface NetworkRequestFailureLog {
+    kind: NetworkRequestFailureKind;
+    method: string;
+    url: string;
+    status?: number;
+    statusText?: string;
+    code?: string;
+    message?: string;
+    headers?: MiniProgramNetworkHeaders;
+    dataPreview?: unknown;
+    timeout?: number;
+    withCredentials?: boolean;
+}
+/**
+ * 记录 `network.request` 失败，保证异常路径在开发者控制台可观测。
+ *
+ * @remarks
+ * - 仅用于诊断，不改变错误抛出语义。
+ * - 会脱敏 token/cookie 等敏感头与字段，并截断 body 预览。
+ * - detail 构造与 logger 调用均包在 try 内，日志失败不得影响业务错误抛出。
+ */
+export declare function logNetworkRequestFailure(config: MiniProgramNetworkRequestConfig, error: unknown, extras: {
+    kind: NetworkRequestFailureKind;
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+    headers?: MiniProgramNetworkHeaders;
+}): void;
+export declare function createNetworkRequestFailureLog(config: MiniProgramNetworkRequestConfig, error: unknown, extras: {
+    kind: NetworkRequestFailureKind;
+    status?: number;
+    statusText?: string;
+    data?: unknown;
+    headers?: MiniProgramNetworkHeaders;
+}): NetworkRequestFailureLog;
+export declare function formatNetworkRequestFailureMessage(detail: NetworkRequestFailureLog): string;

package/types/modules/network/request-shape.d.ts

@@ -0,0 +1,44 @@
+/**
+ * network.request 请求体形态校验与宿主失败诊断文案。
+ *
+ * @remarks
+ * App Host 的 heybox 客户端代发 transport 仅声明 form/json，不支持 multipart。
+ * 本地 Mock 若直接走 fetch 会“能通”，上线后却变成难以理解的 500 network_error。
+ * 因此在 SDK 侧统一提前拒绝 multipart，并在宿主伪装 HTTP 失败时给出可操作提示。
+ */
+/** multipart 不被 App Host 支持时的稳定说明（开发者可见）。 */
+export declare const NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE = "network.request \u4E0D\u652F\u6301 multipart/form-data\u3002App Host \u5BA2\u6237\u7AEF\u4EE3\u53D1\u4EC5\u652F\u6301 application/x-www-form-urlencoded\uFF08form\uFF09\u4E0E application/json\uFF1B\u8BF7\u5C06 data \u7F16\u7801\u4E3A form \u5B57\u7B26\u4E32\uFF08\u4F8B\u5982 new URLSearchParams({...}).toString()\uFF09\u5E76\u8BBE\u7F6E Content-Type: application/x-www-form-urlencoded\u3002\u6587\u4EF6\u4E0A\u4F20\u8BF7\u4F7F\u7528\u4E13\u7528\u4E0A\u4F20\u80FD\u529B\uFF0C\u52FF\u624B\u5199 multipart boundary\u3002";
+/**
+ * 读取请求头中的 Content-Type（大小写不敏感）。
+ */
+export declare function readNetworkContentType(headers: Record<string, string> | undefined): string | undefined;
+/**
+ * 判断 Content-Type 是否声明为 multipart/form-data。
+ */
+export declare function isMultipartContentType(contentType: string | undefined): boolean;
+/**
+ * 判断字符串 body 是否像手写 multipart 实体。
+ */
+export declare function looksLikeMultipartBody(data: unknown): boolean;
+/**
+ * 判断公开请求配置是否使用了 Host 不支持的 multipart 形态。
+ */
+export declare function isUnsupportedMultipartNetworkRequest(config: {
+    data?: unknown;
+    headers?: Record<string, string>;
+}): boolean;
+/**
+ * 从宿主返回的“完成态”响应中提取更清晰的失败原因。
+ *
+ * @remarks
+ * Host 可能把 transport 不支持等内部错误包装成 HTTP 500 + `{ status: 'network_error', msg }`。
+ * 此时 `status=500` 并不代表目标站点返回了 500。
+ */
+export declare function describeHostNetworkFailure(response: {
+    config?: {
+        data?: unknown;
+        headers?: Record<string, string>;
+    };
+    data?: unknown;
+    status: number;
+}): string | undefined;

package/types/vite/html-policy.d.ts

@@ -1,4 +1,5 @@
 export declare const PRODUCTION_CSP: string;
 export declare function enforceMiniappHtmlPolicy(html: string, options?: {
     hmrWebSocketUrl?: string;
+    skipPlatformCsp?: boolean;
 }): string;

package/types/vite/runtime-permission-env.d.ts

@@ -0,0 +1,9 @@
+export declare const HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV = "HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN";
+export declare const HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV = "HB_SDK_RUNTIME_PERMISSION_CONTEXT";
+export declare function shouldSkipMiniappPlatformCspFromEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare function createMiniappPlatformCspEnv(env: NodeJS.ProcessEnv, skipPlatformCsp: boolean): {
+    HB_SDK_RUNTIME_PERMISSION_CONTEXT: string;
+    HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN: string;
+    TZ?: string | undefined;
+};
+export declare function withMiniappPlatformCspEnv<T>(skipPlatformCsp: boolean, action: () => Promise<T>, env?: NodeJS.ProcessEnv): Promise<T>;