@huoye/app-ship 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 /**
  * 上传配置接口
- */
-interface UploadConfig {
+ */ interface UploadConfig {
     /** 应用 ID */
     appId?: string;
     /** 版本号 */
@@ -10,15 +9,62 @@ interface UploadConfig {
     build?: {
         /** Android 构建配置 */
         android?: {
-            /** 构建产物类型：apk 或 appbundle */
+            /**
+             * 构建类型: apk 或 appbundle (aab)
+             * @default 'apk'
+             */
             type?: 'apk' | 'appbundle';
-            /** 构建风味（Flavor） */
+            /**
+             * 是否按 CPU 架构分开打包 (--split-per-abi)
+             * 将生成多个 APK (如 arm64 和 arm32)，自动适配多包上传
+             */
+            splitPerAbi?: boolean;
+            /**
+             * 是否开启 Dart 代码混淆 (--obfuscate)
+             */
+            obfuscate?: boolean;
+            /**
+             * 调试符号导出路径，开启混淆时必须配合使用
+             * @default 'build/debug-info'
+             */
+            splitDebugInfo?: string;
+            /**
+             * Dart 编译期环境变量注入 (-d)
+             */
+            dartDefines?: Record<string, string>;
+            /**
+             * 专家模式附加参数扩展（自动拼接到命令末尾）
+             */
+            extraArgs?: string[];
+            /**
+             * 完全自定义构建命令，配置此项后以上所有构建参数均失效
+             * 仅供具有极特殊构建场景的专家用户使用
+             */
+            customCommand?: string;
+            /** Product Flavor (--flavor) */
             flavor?: string;
-            /** 构建目标 */
+            /** Target platform/lib (--target) */
             target?: string;
-            /** 构建名称 */
+            /**
+             * 注入系统环境变量 (process.env)
+             */
+            envs?: Record<string, string>;
+            /**
+             * 构建前执行脚本
+             */
+            preBuild?: string;
+            /**
+             * 构建后执行脚本
+             */
+            postBuild?: string;
+            /**
+             * 是否在构建前执行 flutter clean
+             * @default false
+             */
+            clean?: boolean;
+            /** 版本名称 (覆盖 pubspec.yaml) */
             buildName?: string;
-            /** 构建号 */
+            /** 构建号 (覆盖 pubspec.yaml) */
             buildNumber?: string;
         };
         /** iOS 构建配置 */
@@ -31,6 +77,77 @@ interface UploadConfig {
             teamId?: string;
             /** 构建配置：Debug 或 Release */
             configuration?: string;
+            /** 是否使用 exportOptions.plist (默认自动生成命令) */
+            useExportOptions?: boolean;
+            /** 自定义导出配置文件路径 */
+            exportOptionsPlist?: string;
+            /**
+             * 是否开启 Dart 代码混淆 (--obfuscate)
+             */
+            obfuscate?: boolean;
+            /**
+             * 调试符号导出路径，开启混淆时必须配合使用
+             * @default 'build/debug-info'
+             */
+            splitDebugInfo?: string;
+            /**
+             * Dart 编译期环境变量注入 (-d)
+             */
+            dartDefines?: Record<string, string>;
+            /**
+             * 专家模式附加参数扩展（自动拼接到命令末尾）
+             */
+            extraArgs?: string[];
+            /**
+             * 完全自定义构建命令，配置此项后以上所有构建参数均失效
+             */
+            customCommand?: string;
+            /** Target platform/lib (--target) */
+            target?: string;
+            /**
+             * 注入系统环境变量 (process.env)
+             */
+            envs?: Record<string, string>;
+            /**
+             * 构建前执行脚本
+             */
+            preBuild?: string;
+            /**
+             * 构建后执行脚本
+             */
+            postBuild?: string;
+            /**
+             * 是否在构建前执行 flutter clean
+             * @default false
+             */
+            clean?: boolean;
+            /** 版本名称 (覆盖 pubspec.yaml) */
+            buildName?: string;
+            /** 构建号 (覆盖 pubspec.yaml) */
+            buildNumber?: string;
+        };
+        /** HarmonyOS 构建配置 */
+        harmony?: {
+            /** 构建类型: hap (调试/安装) 或 app (发布/应用) */
+            type?: 'hap' | 'app';
+            /** Dart 编译期环境变量注入 (-d) */
+            dartDefines?: Record<string, string>;
+            /** 注入系统环境变量 (process.env) */
+            envs?: Record<string, string>;
+            /** 构建前执行脚本 */
+            preBuild?: string;
+            /** 构建后执行脚本 */
+            postBuild?: string;
+            /** 是否在构建前执行 flutter clean */
+            clean?: boolean;
+            /** 附加参数 */
+            extraArgs?: string[];
+            /** 完全自定义构建命令 */
+            customCommand?: string;
+            /** 版本名称 */
+            buildName?: string;
+            /** 构建号 */
+            buildNumber?: string;
         };
     };
     /** 所有上传操作的重试配置 */
@@ -288,8 +405,8 @@ interface UploadConfig {
             };
             /** 包名 */
             packageName?: string;
-            /** 发布轨道：internal | alpha | beta | production */
-            track?: 'internal' | 'alpha' | 'beta' | 'production';
+            /** 发布轨道；首版只支持 internal */
+            track?: 'internal';
         };
         /** 未来扩展的其他平台 */
         [key: string]: any;
@@ -297,8 +414,7 @@ interface UploadConfig {
 }
 /**
  * 应用元数据接口
- */
-interface AppMetadata {
+ */ interface AppMetadata {
     /** 版本号 */
     version: string;
     /** 应用名称 */
@@ -309,8 +425,10 @@ interface AppMetadata {
     changelog: string;
     /** 本次要上传到的平台列表 */
     platform?: string[];
-    /** 构建产物路径（apk/ipa） */
-    artifactPath?: string;
+    /** 构建产物路径（apk/ipa，支持 Record<ABI, Path> 形式以适配多架构） */
+    artifactPath?: string | Record<string, string>;
+    /** 按平台保留的产物集合，供上传调度层选择单包或多架构组合 */
+    platformArtifacts?: Record<string, string | Record<string, string>>;
     /** 全局工具链设置 */
     globalSettings?: {
         /** Android SDK 路径 */
@@ -319,8 +437,7 @@ interface AppMetadata {
 }
 /**
  * 上传结果接口
- */
-interface UploadResult {
+ */ interface UploadResult {
     /** 平台名称 */
     platform: string;
     /** 是否成功 */
@@ -349,8 +466,7 @@ interface UploadResult {
 }
 /**
  * 上传器接口
- */
-interface IUploader {
+ */ interface IUploader {
     /** 上传器名称 */
     name: string;
     /**
@@ -371,16 +487,19 @@ interface IUploader {
 }
 /**
  * 构建结果接口
- */
-interface BuildResult {
+ */ interface BuildResult {
     /** 是否成功 */
     success: boolean;
-    /** 构建产物路径 */
-    artifactPath: string;
+    /**
+     * 产物路径
+     * - 单包时返回路径字符串
+     * - 多架构分包时返回字典映射，如 { 'arm64-v8a': 'path/to/apk64', 'armeabi-v7a': 'path/to/apk32' }
+     */
+    artifactPath: string | Record<string, string>;
     /** 构建耗时（毫秒） */
     buildTime: number;
-    /** 平台：android | ios */
-    platform: 'android' | 'ios';
+    /** 平台：android | ios | harmony */
+    platform: 'android' | 'ios' | 'harmony';
 }
 
 declare class EnvValidator {
@@ -397,6 +516,12 @@ declare class ConfigValidator {
      * @param filePath 配置文件路径
      */
     static loadAndValidate(filePath: string): UploadConfig | null;
+    /**
+     * 只收集本次实际启用配置中的环境变量，避免禁用平台阻塞其它上传任务。
+     */
+    private static collectRequiredEnvVars;
+    /** 在内存中递归解析环境变量，不重新拼接 YAML，避免密钥字符破坏 YAML 结构。 */
+    private static resolveEnvVars;
     /**
      * 验证配置 Schema
      * @param config 配置对象
@@ -580,9 +705,6 @@ declare class XiaomiUploader implements IUploader {
         categoryName: string;
     }[] | null>;
     upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
-    /**
-     * 执行实际的上传操作
-     */
     private performUpload;
     /**
      * 解析公钥: 优先使用内容字段, 其次从文件路径读取
@@ -983,45 +1105,18 @@ declare class OppoUploader implements IUploader {
  *
  * 基于 vivo 开放平台「应用分发 API」实现 (协议与腾讯开放平台 Open-QQ 规范一致)
  * 文档: https://dev.vivo.com.cn/documentCenter/doc/326
- *
- * 上传流程:
- * 1. 使用 access_key + access_secret 生成签名
- * 2. 获取上传地址 (分段上传或直传)
- * 3. 上传 APK 文件
- * 4. 提交版本更新信息
- *
- * 签名方式: HMAC-SHA256(params_sorted, access_secret) → 16进制字符串
  */
 declare class VivoUploader implements IUploader {
     name: string;
     /** vivo 开放 API 基础地址 */
     private static readonly API_BASE;
-    /**
-     * vivo API 签名生成
-     * 规则: 所有参数按 ASCII 码排序后拼接为 key=val&... 字符串，
-     *       以 accessSecret 为密钥进行 HMAC-SHA256 加密，结果转为小写 16 进制字符串
-     */
     private generateSign;
     validateConfig(config: any): boolean;
     canHandle(filePath: string): boolean;
     upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
-    /**
-     * 计算文件 MD5
-     */
     private calculateFileMD5;
-    /**
-     * 上传 APK 文件并获取流水号
-     * 将公共参数与业务参数放入一个 multipart 请求中直接上传至 API_BASE
-     */
     private uploadApk;
-    /**
-     * 提交版本更新信息
-     */
     private submitVersion;
-    /**
-     * 格式化错误信息
-     */
-    private formatError;
 }
 
 /**
@@ -1068,6 +1163,44 @@ declare class TencentUploader implements IUploader {
     private submitModifyAppInfo;
 }
 
+interface GooglePlayHttpResponse<T = any> {
+    data: T;
+}
+interface GooglePlayHttpClient {
+    post<T = any>(url: string, data?: any, config?: any): Promise<GooglePlayHttpResponse<T>>;
+    put<T = any>(url: string, data?: any, config?: any): Promise<GooglePlayHttpResponse<T>>;
+    delete<T = any>(url: string, config?: any): Promise<GooglePlayHttpResponse<T>>;
+}
+interface GooglePlayAuthConfig {
+    serviceAccountJsonPath?: string;
+    serviceAccountJsonContent?: string;
+}
+interface GooglePlayUploaderDependencies {
+    httpClient?: GooglePlayHttpClient;
+    getAccessToken?: (auth: GooglePlayAuthConfig) => Promise<string>;
+}
+/**
+ * Google Play 上传器。
+ *
+ * 首版能力刻意限制为：上传一个 AAB 到内部测试轨道并保留为 draft。
+ * 配置层与 Google Play API 都使用 internal 作为内部测试轨道标识。
+ * 创建应用、填写商店资料、提交审核和生产发布均不在此适配器范围内。
+ */
+declare class GooglePlayUploader implements IUploader {
+    name: string;
+    private readonly httpClient;
+    private readonly getAccessToken;
+    constructor(dependencies?: GooglePlayUploaderDependencies);
+    validateConfig(config: any): boolean;
+    canHandle(filePath: string): boolean;
+    upload(filePath: string, config: any, _metadata: AppMetadata): Promise<UploadResult>;
+    private createAccessToken;
+    private deleteEditBestEffort;
+    private describeError;
+    private redactAndTruncate;
+    private failure;
+}
+
 interface RetryConfig {
     maxRetries?: number;
     initialDelayMs?: number;
@@ -1187,6 +1320,12 @@ declare class UploadManager {
      * 上传到单个平台
      */
     private uploadToPlatform;
+    private shouldGroupArtifacts;
+    private resolveArtifactSelection;
+    private buildArtifactMapFromFiles;
+    private inferArtifactKey;
+    private getRepresentativeFilePath;
+    private validateArtifactSelection;
     /**
      * 聚合上传结果
      */
@@ -1206,7 +1345,7 @@ declare class UploadManager {
     /**
      * 重试失败的平台
      */
-    retryFailedPlatforms(failedPlatforms: string[], filePath: string, config: any, metadata: AppMetadata): Promise<UploadReport>;
+    retryFailedPlatforms(failedPlatforms: string[], filePath: string | string[], config: any, metadata: AppMetadata): Promise<UploadReport>;
 }
 /**
  * 创建上传管理器实例
@@ -1301,4 +1440,88 @@ interface ParseOptions {
  */
 declare function parsePackageInfo(filePath: string, options?: ParseOptions): Promise<PackageInfo | null>;
 
-export { AdHocUploader, type AppMetadata, AppleJWTGenerator, AppleStoreUploader, type BuildResult, ConfigValidator, DEFAULT_RETRY_CONFIG, EnvValidator, ErrorCategory, HarmonyUploader, HuaweiUploader, type IUploader, OppoUploader, type PackageInfo, type ParseOptions, PgyerUploader, type RetryConfig, type RetryResult, RetryStrategy, TencentUploader, TestFlightUploader, type UploadConfig, UploadManager, type UploadManagerConfig, type UploadReport, type UploadResult, VivoUploader, XiaomiUploader, createUploadManager, createUploadRetryStrategy, parsePackageInfo };
+declare const RELEASE_RECEIPT_SCHEMA_VERSION: 1;
+declare const DEFAULT_RELEASE_RECEIPT_LIMIT = 100;
+type ReleaseReceiptKind = 'build' | 'upload';
+type ReleaseReceiptOutcome = 'success' | 'partial' | 'failed' | 'cancelled';
+type ReleaseReceiptState = 'built' | 'uploaded' | 'draft_created' | 'review_submitted' | 'reviewing' | 'approved' | 'rejected' | 'released' | 'failed' | 'cancelled';
+interface ReleaseArtifactReceipt {
+    path: string;
+    name: string;
+    sizeBytes?: number;
+    sha256?: string;
+    available: boolean;
+}
+interface ReleaseRemoteReceipt {
+    consoleUrl?: string;
+    downloadUrl?: string;
+    identifiers?: Record<string, string | number | boolean>;
+}
+interface ReleaseTargetReceipt {
+    platform: string;
+    state: ReleaseReceiptState;
+    outcome: ReleaseReceiptOutcome;
+    message: string;
+    remote?: ReleaseRemoteReceipt;
+    lastKnownRemoteStatus?: string;
+    checkedAt?: string;
+}
+interface ReleaseReceipt {
+    schemaVersion: typeof RELEASE_RECEIPT_SCHEMA_VERSION;
+    id: string;
+    projectKey: string;
+    projectRoot: string;
+    kind: ReleaseReceiptKind;
+    appName?: string;
+    packageName?: string;
+    versionName?: string;
+    buildNumber?: string;
+    changelog?: string;
+    artifacts: ReleaseArtifactReceipt[];
+    targets: ReleaseTargetReceipt[];
+    outcome: ReleaseReceiptOutcome;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+}
+interface ReleaseReceiptInput {
+    projectRoot: string;
+    kind: ReleaseReceiptKind;
+    appName?: string;
+    packageName?: string;
+    versionName?: string;
+    buildNumber?: string | number;
+    changelog?: string;
+    artifactPaths?: unknown;
+    targets: ReleaseTargetReceipt[];
+    startedAt?: string | number | Date;
+    finishedAt?: string | number | Date;
+    outcome?: ReleaseReceiptOutcome;
+}
+interface ReleaseReceiptStoreOptions {
+    storageRoot?: string;
+    maxEntries?: number;
+}
+/** 解析发布回执所属项目；显式项目目录优先，未提供时才使用配置文件目录。 */
+declare function resolveReleaseProjectRoot(projectRoot: string | undefined, configPath: string): string;
+/** 将可能包含凭据的错误信息压缩为可安全持久化的短文本。 */
+declare function sanitizeReleaseMessage(value: unknown, maxLength?: number): string;
+/** 将上传结果转换为稳定、可公开展示的渠道状态。 */
+declare function createUploadTargets(results: UploadResult[]): ReleaseTargetReceipt[];
+/** 创建回执；只接受已经挑选过的业务字段，不接受完整配置或原始响应。 */
+declare function createReleaseReceipt(input: ReleaseReceiptInput): Promise<ReleaseReceipt>;
+/** 将回执转换为适合复制给客户或 AI 的纯文本摘要。 */
+declare function formatReleaseReceipt(receipt: ReleaseReceipt): string;
+declare class ReleaseReceiptStore {
+    private readonly storageRoot;
+    private readonly maxEntries;
+    constructor(options?: ReleaseReceiptStoreOptions);
+    append(receipt: ReleaseReceipt): Promise<void>;
+    list(projectRoot: string, limit?: number): Promise<ReleaseReceipt[]>;
+    save(input: ReleaseReceiptInput): Promise<ReleaseReceipt>;
+    private getFilePath;
+    private readFile;
+}
+declare function createProjectKey(projectRoot: string): string;
+
+export { AdHocUploader, type AppMetadata, AppleJWTGenerator, AppleStoreUploader, type BuildResult, ConfigValidator, DEFAULT_RELEASE_RECEIPT_LIMIT, DEFAULT_RETRY_CONFIG, EnvValidator, ErrorCategory, GooglePlayUploader, type GooglePlayUploaderDependencies, HarmonyUploader, HuaweiUploader, type IUploader, OppoUploader, type PackageInfo, type ParseOptions, PgyerUploader, RELEASE_RECEIPT_SCHEMA_VERSION, type ReleaseArtifactReceipt, type ReleaseReceipt, type ReleaseReceiptInput, type ReleaseReceiptKind, type ReleaseReceiptOutcome, type ReleaseReceiptState, ReleaseReceiptStore, type ReleaseReceiptStoreOptions, type ReleaseRemoteReceipt, type ReleaseTargetReceipt, type RetryConfig, type RetryResult, RetryStrategy, TencentUploader, TestFlightUploader, type UploadConfig, UploadManager, type UploadManagerConfig, type UploadReport, type UploadResult, VivoUploader, XiaomiUploader, createProjectKey, createReleaseReceipt, createUploadManager, createUploadRetryStrategy, createUploadTargets, formatReleaseReceipt, parsePackageInfo, resolveReleaseProjectRoot, sanitizeReleaseMessage };