@huoye/app-ship 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1304 @@
+/**
+ * 上传配置接口
+ */
+interface UploadConfig {
+    /** 应用 ID */
+    appId?: string;
+    /** 版本号 */
+    version?: string;
+    /** 构建相关配置 */
+    build?: {
+        /** Android 构建配置 */
+        android?: {
+            /** 构建产物类型：apk 或 appbundle */
+            type?: 'apk' | 'appbundle';
+            /** 构建风味（Flavor） */
+            flavor?: string;
+            /** 构建目标 */
+            target?: string;
+            /** 构建名称 */
+            buildName?: string;
+            /** 构建号 */
+            buildNumber?: string;
+        };
+        /** iOS 构建配置 */
+        ios?: {
+            /** 工程 Scheme */
+            scheme?: string;
+            /** 导出方式：app-store | development | ad-hoc | enterprise */
+            exportMethod?: 'app-store' | 'development' | 'ad-hoc' | 'enterprise';
+            /** Apple 团队 ID */
+            teamId?: string;
+            /** 构建配置：Debug 或 Release */
+            configuration?: string;
+        };
+    };
+    /** 所有上传操作的重试配置 */
+    retry?: {
+        /** 最大重试次数（默认：3） */
+        maxRetries?: number;
+        /** 初始延迟毫秒数（默认：1000） */
+        initialDelayMs?: number;
+        /** 指数退避乘数（默认：2） */
+        backoffMultiplier?: number;
+        /** 最大延迟毫秒数（默认：30000） */
+        maxDelayMs?: number;
+    };
+    /** 发布平台配置 */
+    publish?: {
+        /** 蒲公英平台配置 */
+        pgyer?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** API 密钥 */
+            apiKey: string;
+            /** 版本描述 */
+            description?: string;
+        };
+        /** 华为应用市场配置 */
+        huawei?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 客户端 ID */
+                clientId: string;
+                /** 客户端密钥 */
+                clientSecret: string;
+            };
+            /** 应用 ID */
+            appId: string;
+            /** 发布类型：草稿或提交审核 */
+            releaseType?: 'draft' | 'submit';
+            /**
+             * API 基础地址（可选）
+             * 默认为中国区：https://connect-api.cloud.huawei.com
+             * 欧洲区：https://connect-api-dre.cloud.huawei.com
+             * 亚太区：https://connect-api-dra.cloud.huawei.com
+             * 俄罗斯区：https://connect-api-dru.cloud.huawei.com
+             */
+            apiBaseUrl?: string;
+            /** 商店素材配置 */
+            assets?: {
+                /** 应用图标路径（png/jpg，216x216 推荐） */
+                icon?: string;
+                /** 商店截图路径列表（png/jpg/bmp，3-8张） */
+                screenshots?: string[];
+                /** 预览视频路径（mp4/mov，可选） */
+                video?: string;
+            };
+        };
+        /** 小米应用商店配置 */
+        xiaomi?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 开发者账号邮箱 */
+                userName: string;
+                /** API 访问密码 (非登录密码) */
+                privateKey: string;
+                /** 小米分配的 RSA 公钥文件路径 */
+                publicKeyPath?: string;
+            };
+            /** 应用包名 (可选, 不填则从 APK 推断) */
+            packageName?: string;
+            /** 应用名称 (可选, 不填则从包名推断, 小米 API 必需) */
+            appName?: string;
+            /** 版本描述 */
+            description?: string;
+            /**
+             * 上传类型 (可选)
+             * - 'auto': 自动查询应用是否存在 (默认)
+             * - 'new': 强制新增应用 (synchroType=0)
+             * - 'update': 强制更新应用 (synchroType=1)
+             */
+            uploadType?: 'auto' | 'new' | 'update';
+            /** 应用分类 ID (新增应用必填, 通过 /dev/category 接口获取) */
+            category?: number;
+            /** 搜索关键字, 空格分隔 (新增应用必填) */
+            keyWords?: string;
+            /** 应用介绍 (新增应用必填) */
+            desc?: string;
+            /** 一句话简介 (新增应用必填) */
+            brief?: string;
+            /** 隐私政策链接 (新增应用必填) */
+            privacyUrl?: string;
+            /** 商店素材配置 (新增应用需要 icon 和截图) */
+            assets?: {
+                /** 应用图标路径 */
+                icon?: string;
+                /** 手机截图路径列表 (新增应用至少 3 张) */
+                screenshots?: string[];
+            };
+        };
+        /** 鸿蒙应用市场配置 */
+        harmony?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 客户端 ID */
+                clientId: string;
+                /** 客户端密钥 */
+                clientSecret: string;
+            };
+            /** 应用 ID */
+            appId: string;
+            /** 发布类型：草稿或提交审核 */
+            releaseType?: 'draft' | 'submit';
+        };
+        /** App Store 配置 */
+        app_store?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 发布模式：app_store | testflight | adhoc */
+            mode?: 'app_store' | 'testflight' | 'adhoc';
+            /**
+             * App Store Connect 中的应用 ID（数字）
+             * 用于 API 自动更新发行说明，可在 App Store Connect 应用详情页 URL 中找到
+             * 例如: https://appstoreconnect.apple.com/apps/123456789 中的 123456789
+             */
+            appId?: string;
+            /** 认证信息（至少配置一种认证方式） */
+            auth: {
+                /**
+                 * CLI 上传凭据（Apple ID + App-specific Password）
+                 * 用于 Transporter / altool 上传 IPA
+                 * App-specific Password 需在 appleid.apple.com 生成
+                 */
+                /** Apple ID (邮箱) */
+                appleId?: string;
+                /** App-specific Password */
+                appPassword?: string;
+                /**
+                 * API Key 凭据（用于 App Store Connect API）
+                 * 用于自动更新发行说明（What's New）
+                 * 在 App Store Connect > 用户和访问 > 密钥 中生成
+                 */
+                /** API 密钥 ID */
+                apiKeyId?: string;
+                /** API 签发者 ID */
+                apiIssuerId?: string;
+                /** 私钥文件路径 (.p8) */
+                privateKeyPath?: string;
+                /** 私钥内容 (PEM 格式) */
+                privateKeyContent?: string;
+            };
+            /** TestFlight 配置 */
+            testflight?: {
+                /** 测试员邮箱列表 */
+                betaTesters?: string[];
+                /** 多语言测试信息 */
+                betaBuildLocalization?: {
+                    /** 语言代码，如 'en-US', 'zh-Hans' */
+                    locale: string;
+                    /** 描述文本 */
+                    description: string;
+                    /** 关键词列表 */
+                    keywords?: string[];
+                }[];
+                /** 自动通知测试员（默认：true） */
+                autoNotify?: boolean;
+            };
+            /** Ad Hoc 配置 */
+            adhoc?: {
+                /** Apple 团队 ID */
+                teamId?: string;
+                /** Provisioning Profile 名称 */
+                provisioningProfileSpecifier?: string;
+                /** 签名证书名称 */
+                signingIdentity?: string;
+                /** 导出选项 */
+                exportOptions?: {
+                    /** 导出方法：ad-hoc */
+                    method: 'ad-hoc';
+                    /** 签名风格：自动或手动 */
+                    signingStyle?: 'automatic' | 'manual';
+                    /** 是否裁剪 Swift 符号 */
+                    stripSwiftSymbols?: boolean;
+                    /** 瘦身配置 */
+                    thinning?: string;
+                };
+            };
+        };
+        /** OPPO 应用商店配置 */
+        oppo?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 客户端 ID (OPPO 开放平台分配) */
+                clientId: string;
+                /** 客户端密钥 */
+                clientSecret: string;
+            };
+            /** 应用包名 (可选, 不填则从 APK 推断) */
+            packageName?: string;
+            /**
+             * 发布类型 (可选)
+             * 1: 审核通过后立即发布 (默认)
+             * 2: 定时发布
+             */
+            onlineType?: '1' | '2';
+        };
+        /** vivo 应用商店配置 */
+        vivo?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** Access Key (vivo 开放平台分配) */
+                accessKey: string;
+                /** Access Secret */
+                accessSecret: string;
+            };
+            /** 应用包名 (可选, 不填则从 APK 推断) */
+            packageName?: string;
+        };
+        /**
+         * 腾讯应用宝配置 (腾讯开放平台)
+         * 使用 HMAC-SHA256 签名, 通用 API 路由: https://api.open.qq.com/router/rest
+         */
+        tencent?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 开发者用户 ID (分配给开发者的数字 ID) */
+                userId: string;
+                /** 应用 ID (应用宝分配的应用标识) */
+                appId: string;
+                /** Access Secret (接入密钥) */
+                accessSecret: string;
+            };
+            /** 应用包名 (可选, 不填则从 APK 推断) */
+            packageName?: string;
+        };
+        /** Google Play 配置 */
+        google_play?: {
+            /** 是否启用 */
+            enable: boolean;
+            /** 认证信息 */
+            auth: {
+                /** 服务账号 JSON 文件路径 */
+                serviceAccountJsonPath?: string;
+                /** 服务账号 JSON 内容 */
+                serviceAccountJsonContent?: string;
+            };
+            /** 包名 */
+            packageName?: string;
+            /** 发布轨道：internal | alpha | beta | production */
+            track?: 'internal' | 'alpha' | 'beta' | 'production';
+        };
+        /** 未来扩展的其他平台 */
+        [key: string]: any;
+    };
+}
+/**
+ * 应用元数据接口
+ */
+interface AppMetadata {
+    /** 版本号 */
+    version: string;
+    /** 应用名称 */
+    appName?: string;
+    /** 构建号 */
+    buildNumber: string;
+    /** 更新日志 */
+    changelog: string;
+    /** 本次要上传到的平台列表 */
+    platform?: string[];
+    /** 构建产物路径（apk/ipa） */
+    artifactPath?: string;
+    /** 全局工具链设置 */
+    globalSettings?: {
+        /** Android SDK 路径 */
+        androidSdkPath?: string;
+    };
+}
+/**
+ * 上传结果接口
+ */
+interface UploadResult {
+    /** 平台名称 */
+    platform: string;
+    /** 是否成功 */
+    success: boolean;
+    /**
+     * 提示信息 (必填)
+     * - 成功时：简短的成功提示
+     * - 失败时：必须是可读的错误描述，供 UI 直接展示
+     */
+    message: string;
+    /** 下载地址 */
+    url?: string;
+    /** 链接地址 */
+    link?: string;
+    /** 二维码地址 */
+    qrCode?: string;
+    /**
+     * 原始错误对象 (可选)
+     * 仅用于调试，UI 不应直接展示此字段
+     */
+    error?: Error | any;
+    /** 平台特有的响应数据 */
+    data?: any;
+    /** 商店后台管理链接（上传成功后用于快速跳转） */
+    consoleUrl?: string;
+}
+/**
+ * 上传器接口
+ */
+interface IUploader {
+    /** 上传器名称 */
+    name: string;
+    /**
+     * 验证平台相关配置
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 上传产物
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 判断该上传器是否能处理指定文件
+     * 用于多文件混合上传的智能分发
+     * @param filePath 文件路径
+     * @returns 是否支持该文件类型
+     */
+    canHandle(filePath: string): boolean;
+}
+/**
+ * 构建结果接口
+ */
+interface BuildResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 构建产物路径 */
+    artifactPath: string;
+    /** 构建耗时（毫秒） */
+    buildTime: number;
+    /** 平台：android | ios */
+    platform: 'android' | 'ios';
+}
+
+declare class EnvValidator {
+    /**
+     * 验证环境变量
+     * @param requiredVars 必需的环境变量列表
+     */
+    static validate(requiredVars: string[]): boolean;
+}
+
+declare class ConfigValidator {
+    /**
+     * 加载并验证配置文件
+     * @param filePath 配置文件路径
+     */
+    static loadAndValidate(filePath: string): UploadConfig | null;
+    /**
+     * 验证配置 Schema
+     * @param config 配置对象
+     */
+    private static validateSchema;
+}
+
+declare class PgyerUploader implements IUploader {
+    name: string;
+    private static UPLOAD_API;
+    /**
+     * 验证配置
+     * @param config 配置对象
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持该文件
+     * @param filePath 文件路径
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * 上传文件到蒲公英
+     * @param filePath 文件路径
+     * @param config 配置
+     * @param metadata 元数据
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 执行实际上传操作
+     * @param filePath 文件路径
+     * @param apiKey API Key
+     * @param desc 描述
+     */
+    private performUpload;
+}
+
+declare class HuaweiUploader implements IUploader {
+    name: string;
+    private static DEFAULT_API_BASE;
+    private static TOKEN_PATH;
+    private static PUBLISH_API_PATH;
+    /** 获取 API 基础地址 */
+    private getApiBase;
+    /** 获取 Token URL */
+    private getTokenUrl;
+    /** 获取 Publish API 根路径 */
+    private getApiRoot;
+    /** 创建 API 请求头（消除 7 处重复） */
+    private headers;
+    /** 检查 API 响应（消除 6 处重复） */
+    private checkResponse;
+    /**
+     * 验证配置
+     * @param config 配置对象
+     * @returns 是否有效
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持该文件
+     * @param filePath 文件路径
+     * @returns 是否支持
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * 执行上传
+     * @param filePath 文件路径
+     * @param config 配置
+     * @param metadata 元数据
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 查询审核状态
+     * @param clientId 客户端 ID
+     * @param clientSecret 客户端密钥
+     * @param appId 应用 ID
+     * @param apiBaseUrl API 基础地址（可选）
+     */
+    queryReviewStatus(clientId: string, clientSecret: string, appId: string, apiBaseUrl?: string): Promise<any>;
+    /**
+     * 获取 Access Token
+     * @param tokenUrl Token URL
+     * @param clientId 客户端 ID
+     * @param clientSecret 客户端密钥
+     */
+    private getAccessToken;
+    /** 获取上传 URL */
+    private getUploadUrl;
+    /** 通用文件上传（FormData 方式，无需 API 认证头） */
+    private executeUploadRequest;
+    /** 上传文件 (APK/AAB) */
+    private uploadFile;
+    /** 更新应用文件信息 */
+    private updateAppFileInfo;
+    /** 更新发布说明（支持多语言） */
+    private updateReleaseNotes;
+    /** 提交审核 */
+    private submitForReview;
+    /** 获取应用信息 */
+    private getAppInfo;
+    /** 上传商店素材（图标、截图、视频） */
+    private uploadStoreAssets;
+    /** 批量上传素材文件 */
+    private uploadAssetFiles;
+    /** 更新素材文件信息（关联到应用） */
+    private updateAssetFileInfo;
+}
+
+/**
+ * 小米应用商店上传器
+ *
+ * 基于小米官方「应用自动发布接口」实现
+ * 文档: https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1134
+ *
+ * 上传流程:
+ * 1. 构建 RequestData JSON (userName, appInfo, synchroType)
+ * 2. 计算所有参数的 MD5 (RequestData 字符串 + APK 文件)
+ * 3. 拼接 SIG JSON, 用 RSA 公钥加密
+ * 4. POST multipart/form-data 到 /dev/push
+ */
+declare class XiaomiUploader implements IUploader {
+    name: string;
+    private static readonly API_BASE;
+    private static readonly PUSH_API;
+    private static readonly QUERY_API;
+    private static readonly CATEGORY_API;
+    /**
+     * RSA 公钥分段加密 (PKCS1Padding)
+     *
+     * 小米要求: 使用平台分配的 RSA 公钥加密 SIG JSON,
+     * 输出小写十六进制字符串。RSA 1024-bit 密钥单次最多加密 117 字节,
+     * 超出需分段加密后拼接。
+     */
+    private rsaEncryptWithPublicKey;
+    /**
+     * 从 X.509 证书或 PEM 公钥中提取可用于加密的公钥
+     * 优先使用 crypto.X509Certificate，因为它能同时处理 DER 和 PEM 格式的证书
+     */
+    private extractPublicKey;
+    /**
+     * 计算文件 MD5 (小写十六进制)
+     */
+    private calculateFileMD5;
+    /**
+     * 计算字符串 MD5 (小写十六进制)
+     */
+    private calculateStringMD5;
+    /**
+     * 构建 RequestData JSON
+     */
+    private buildRequestData;
+    /**
+     * 生成只包含 RequestData 的 SIG（用于查询接口）
+     */
+    private generateQuerySIG;
+    /**
+     * 生成包含 RequestData + apk 的加密 SIG 字符串（用于上传接口）
+     */
+    private generateUploadSIG;
+    /**
+     * 将用户输入的公钥字符串规范化为 PEM 格式
+     */
+    private normalizePEM;
+    validateConfig(config: any): boolean;
+    canHandle(filePath: string): boolean;
+    /**
+     * 查询应用状态
+     * 使用 POST /dev/query 接口，需要 SIG 签名认证
+     *
+     * 返回值说明:
+     * - create: true → 需要通过新增方式上传 (synchroType=0)
+     * - updateVersion: true → 可以更新包 (synchroType=1)
+     * - updateInfo: true → 可以仅更新信息 (synchroType=2)
+     */
+    private queryAppStatus;
+    /**
+     * 查询小米应用商店分类列表
+     * POST /dev/category, 无需参数
+     */
+    queryCategories(): Promise<{
+        categoryId: number;
+        categoryName: string;
+    }[] | null>;
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 执行实际的上传操作
+     */
+    private performUpload;
+    /**
+     * 解析公钥: 优先使用内容字段, 其次从文件路径读取
+     */
+    private resolvePublicKey;
+    /**
+     * 尝试从文件名推断包名
+     * 例如: com.example.app-release.apk → com.example.app
+     */
+    private inferPackageName;
+    /**
+     * 从包名推断应用名称
+     * 例如: com.example.app → app 或 com.app → app
+     */
+    private inferAppName;
+}
+
+/**
+ * 工具命令信息
+ */
+/**
+ * App Store 上传器
+ *
+ * 上传方式：使用官方 CLI 工具上传 IPA
+ * - 优先: Transporter CLI（官方推荐）
+ * - 备选: xcrun altool（Xcode 自带，已弃用但可用）
+ *
+ * 可选功能：通过 App Store Connect API 自动更新发行说明
+ * - 需要额外配置 API Key 凭据（apiKeyId + apiIssuerId + privateKey）
+ * - 不配置 API Key 时仅上传 IPA，发行说明需手动更新
+ */
+declare class AppleStoreUploader implements IUploader {
+    name: string;
+    /**
+     * 验证配置是否有效
+     * 至少需要一种认证方式：
+     * - appleId + appPassword（CLI 上传）
+     * - apiKeyId + apiIssuerId + privateKey（API 调用，也可用于 CLI 上传）
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持处理该文件
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * 执行上传流程
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 使用可用的工具上传
+     * 策略: 优先 Transporter → 降级 altool → 都失败
+     */
+    private uploadWithAvailableTool;
+    /**
+     * 解析工具路径结果
+     */
+    private resolveToolPath;
+    /**
+     * 通过 Transporter CLI 上传
+     */
+    private uploadViaTransporter;
+    /**
+     * 通过 altool 上传
+     */
+    private uploadViaAltool;
+    /**
+     * 解析 altool/Transporter 错误信息，翻译为用户友好的语言
+     */
+    private parseAltoolError;
+    /**
+     * 检查是否配置了 API Key 凭据
+     */
+    private hasApiCredentials;
+    /**
+     * 创建 JWT 生成器
+     */
+    private createJWTGenerator;
+    /**
+     * 获取 API 请求头
+     */
+    private apiHeaders;
+    /**
+     * 尝试更新发行说明（失败不影响上传结果）
+     */
+    private tryUpdateReleaseNotes;
+    /**
+     * 获取处于"准备提交"状态的版本
+     * 只有此状态下的版本才能修改发行说明
+     */
+    private getPrepareForSubmissionVersion;
+    /**
+     * 获取版本的本地化信息列表
+     */
+    private getVersionLocalizations;
+    /**
+     * 更新本地化版本的 What's New 内容
+     */
+    private updateLocalizationWhatsNew;
+    /**
+     * 获取工具安装指引
+     */
+    private getToolInstallationGuide;
+}
+
+/**
+ * TestFlight 上传器
+ *
+ * 用于上传应用到 TestFlight 进行 Beta 测试
+ * 参考: https://developer.apple.com/documentation/appstoreconnectapi/build-beta-versions
+ */
+declare class TestFlightUploader implements IUploader {
+    name: string;
+    private static readonly API_ROOT;
+    private static readonly API_TIMEOUT;
+    private static readonly BUILD_PROCESSING_TIMEOUT;
+    private static readonly BUILD_POLLING_INTERVAL;
+    /**
+     * 验证配置
+     * @param config 配置对象
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持该文件
+     * @param filePath 文件路径
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * 执行上传到 TestFlight
+     * @param filePath 文件路径
+     * @param config 配置
+     * @param metadata 元数据
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 加载 JWT 生成器
+     * @param auth 认证信息
+     */
+    private loadJWTGenerator;
+    /**
+     * 提取 Bundle ID
+     * @param ipaPath IPA 路径
+     */
+    private extractBundleId;
+    /**
+     * 创建构建记录
+     * @param jwt JWT
+     * @param bundleId Bundle ID
+     * @param version 版本号
+     */
+    private createBuild;
+    /**
+     * 上传 IPA 文件
+     * @param jwt JWT
+     * @param buildId 构建 ID
+     * @param filePath 文件路径
+     */
+    private uploadIPAFile;
+    /**
+     * 等待构建处理
+     * @param jwt JWT
+     * @param buildId 构建 ID
+     * @param timeoutMs 超时时间
+     */
+    private waitForBuildProcessing;
+    /**
+     * 创建 Beta 版本（使其可测试）
+     * @param jwt JWT
+     * @param buildId 构建 ID
+     */
+    private createBetaBuildVersion;
+    /**
+     * Add beta testers to the build
+     */
+    private addBetaTesters;
+    /**
+     * 添加单个测试员到组
+     * @param jwt JWT
+     * @param testerEmail 测试员邮箱
+     * @param buildId 构建 ID
+     */
+    private addBetaTesterToGroup;
+    /**
+     * Add localization for beta build
+     */
+    private addBetaBuildLocalization;
+    /**
+     * Add single localization
+     */
+    private addLocalizationToBuilder;
+    /**
+     * 通知测试员
+     * @param jwt JWT
+     * @param buildId 构建 ID
+     * @param message 消息
+     */
+    private notifyBetaTesters;
+}
+
+/**
+ * Ad Hoc 上传器
+ *
+ * 用于创建 Ad Hoc 分发包，供特定设备安装
+ * Ad Hoc 允许在最多 100 个特定的 iOS 设备上安装应用
+ *
+ * 流程:
+ * 1. 使用 Xcode 生成 Ad Hoc IPA（使用指定的 Provisioning Profile）
+ * 2. 生成设备安装链接/二维码
+ * 3. 支持通过蒲公英或其他分发平台
+ */
+declare class AdHocUploader implements IUploader {
+    name: string;
+    /**
+     * 验证配置
+     * @param config 配置对象
+     * @returns 是否有效
+     */
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持该文件
+     * @param filePath 文件路径
+     * @returns 是否支持
+     */
+    canHandle(filePath: string): boolean;
+    /**
+     * 执行上传（生成 Ad Hoc 分发包）
+     * @param filePath 文件路径
+     * @param config 配置
+     * @param metadata 元数据
+     */
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 从 IPA 提取 Bundle ID
+     * @param ipaPath IPA 路径
+     */
+    private extractBundleId;
+    /**
+     * 验证 Provisioning Profile
+     * @param profileSpecifier Profile 名称
+     * @param teamId 团队 ID
+     */
+    private verifyProvisioningProfile;
+    /**
+     * 创建 manifest.plist 文件
+     * @param ipaPath IPA 路径
+     * @param version 版本号
+     * @param bundleId Bundle ID
+     * @param changelog 更新日志
+     */
+    private createManifest;
+    /**
+     * 设置分发目录结构
+     * @param ipaPath IPA 路径
+     * @param manifestPath Manifest 路径
+     */
+    private setupDistributionDirectory;
+    /**
+     * 生成安装链接 (itms-services)
+     * @param distributionPath 分发目录
+     * @param bundleId Bundle ID
+     */
+    private generateInstallUrl;
+    /**
+     * 生成二维码
+     * @param url 安装链接
+     * @param distributionPath 分发目录
+     */
+    private generateQRCode;
+    /**
+     * 输出分发信息
+     * @param installUrl 安装链接
+     * @param qrCodePath 二维码路径
+     * @param distributionPath 分发目录
+     * @param profileInfo Profile 信息
+     */
+    private outputDistributionInfo;
+    /**
+     * 检查是否安装了 Xcode
+     * @returns 是否安装
+     */
+    private checkXcodeInstalled;
+    /**
+     * 生成 Ad Hoc 导出选项 (ExportOptions.plist)
+     * @param teamId 团队 ID
+     * @param signingIdentity 签名证书
+     * @param provisioningProfile Profile 名称
+     */
+    private generateExportOptions;
+}
+
+/**
+ * 鸿蒙应用市场上传器
+ * 复用华为 AppGallery Connect API，但针对鸿蒙包优化
+ */
+declare class HarmonyUploader implements IUploader {
+    name: string;
+    private static TOKEN_URL;
+    private static PUBLISH_API_ROOT;
+    validateConfig(config: any): boolean;
+    /**
+     * 判断是否支持该文件
+     * @param filePath 文件路径
+     */
+    canHandle(filePath: string): boolean;
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 获取 Access Token
+     * @param clientId 客户端 ID
+     * @param clientSecret 客户端密钥
+     */
+    private getAccessToken;
+    /**
+     * 获取上传 URL
+     * @param token Token
+     * @param appId 应用 ID
+     * @param suffix 后缀
+     */
+    private getUploadUrl;
+    private uploadFile;
+    /**
+     * 更新应用文件信息
+     * @param token Token
+     * @param appId 应用 ID
+     * @param authCode 授权码
+     * @param filePath 文件路径
+     */
+    private updateAppFileInfo;
+}
+
+/**
+ * OPPO 应用商店上传器
+ *
+ * 基于 OPPO 开放平台「应用发布 API」实现
+ * 文档: https://open.oppomobile.com/new/developmentDoc/info?id=11280
+ *
+ * 上传流程:
+ * 1. 使用 client_id + client_secret 获取 access_token
+ * 2. 获取上传 URL
+ * 3. 上传 APK 文件
+ * 4. 提交版本信息（更新日志等）
+ */
+declare class OppoUploader implements IUploader {
+    name: string;
+    /** OPPO 开放 API 基础地址 */
+    private static readonly API_BASE;
+    /** 获取 token 接口 */
+    private static readonly TOKEN_API;
+    /** 获取上传 URL 接口 */
+    private static readonly UPLOAD_URL_API;
+    /** 上传完成后提交版本 */
+    private static readonly SUBMIT_API;
+    /** 查询应详情接口 */
+    private static readonly APP_INFO_API;
+    /**
+     * OPPO API 签名生成
+     * OPPO 使用 HMAC-SHA256 签名机制
+     */
+    private generateSign;
+    validateConfig(config: any): boolean;
+    canHandle(filePath: string): boolean;
+    /**
+     * 尝试从文件名推断包名
+     */
+    private inferPackageName;
+    /**
+     * 从包名推断应用名称
+     */
+    private inferAppName;
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 获取 access_token
+     * 官方文档: https://open.oppomobile.com/documentation/page/info?id=10998
+     */
+    private getAccessToken;
+    /**
+     * 获取应用详情
+     */
+    private getAppInfo;
+    /**
+     * 获取上传地址
+     */
+    private getUploadUrl;
+    /**
+     * 上传 APK 文件
+     */
+    private uploadFile;
+    /**
+     * 提交版本信息
+     */
+    private submitVersion;
+    /**
+     * 格式化错误信息
+     */
+    private formatError;
+}
+
+/**
+ * vivo 应用商店上传器
+ *
+ * 基于 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;
+}
+
+/**
+ * 腾讯应用宝上传器
+ *
+ * 基于腾讯开放平台「应用管理 API」实现
+ * 文档: https://wiki.open.qq.com/wiki/应用上传
+ *
+ * 上传流程:
+ * 1. 使用 appId + accessSecret 生成签名
+ * 2. 上传 APK 文件
+ * 3. 提交版本信息（更新说明等）
+ *
+ * 签名方式: HMAC-SHA256
+ */
+declare class TencentUploader implements IUploader {
+    name: string;
+    /** 腾讯开放平台 API 基础地址 */
+    private static readonly API_BASE;
+    /**
+     * 接口签名生成 (HmacSHA256)
+     * 规则: 所有参数按字典序排序拼接为 k1=v1&k2=v2... (不要进行 URL 编码)
+     *       使用 accessSecret 计算 HmacSHA256，转小写 16 进制
+     */
+    private generateSign;
+    validateConfig(config: any): boolean;
+    canHandle(filePath: string): boolean;
+    upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult>;
+    /**
+     * 阶段 1: 获取文件上传信息
+     */
+    private getFileUploadInfo;
+    /**
+     * 获取应用详情
+     */
+    private queryAppDetail;
+    /**
+     * 阶段 2: 直接上传到 COS (PUT)
+     */
+    private uploadToCos;
+    /**
+     * 阶段 3: 提交流水号信息
+     */
+    private submitModifyAppInfo;
+}
+
+interface RetryConfig {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    backoffMultiplier?: number;
+    maxDelayMs?: number;
+}
+/**
+ * 重试结果
+ */
+interface RetryResult<T> {
+    success: boolean;
+    data?: T;
+    error?: Error;
+    totalAttempts: number;
+    lastError?: string;
+}
+/**
+ * 错误分类
+ */
+declare enum ErrorCategory {
+    NETWORK_ERROR = "NETWORK_ERROR",
+    TEMPORARY_ERROR = "TEMPORARY_ERROR",
+    SERVER_ERROR = "SERVER_ERROR",
+    AUTH_ERROR = "AUTH_ERROR",
+    CLIENT_ERROR = "CLIENT_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * 重试策略管理器
+ */
+declare class RetryStrategy {
+    private config;
+    constructor(config?: RetryConfig);
+    /**
+     * 根据错误类型判断是否应该重试
+     */
+    shouldRetry(error: Error, retryCount: number): boolean;
+    /**
+     * 对错误进行分类
+     */
+    classifyError(error: Error): ErrorCategory;
+    /**
+     * 判断错误类别是否可重试
+     */
+    private isRetryableCategory;
+    /**
+     * 计算延迟时间（使用指数退避策略）
+     */
+    calculateDelay(retryCount: number): number;
+    /**
+     * 等待指定时间
+     */
+    private sleep;
+    /**
+     * 执行带重试的异步函数
+     */
+    execute<T>(fn: () => Promise<T>, operationName?: string): Promise<RetryResult<T>>;
+}
+/**
+ * 默认重试配置
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * 为上传操作创建重试策略
+ */
+declare function createUploadRetryStrategy(config?: RetryConfig): RetryStrategy;
+
+/**
+ * 上传管理器配置
+ */
+interface UploadManagerConfig {
+    maxConcurrent?: number;
+    continueOnError?: boolean;
+    verbose?: boolean;
+    cancellationToken?: {
+        isCancelled: boolean;
+    };
+}
+/**
+ * 聚合的上传结果报告
+ */
+interface UploadReport {
+    totalUploads: number;
+    successCount: number;
+    failureCount: number;
+    successPlatforms: string[];
+    failurePlatforms: string[];
+    results: UploadResult[];
+    totalDurationMs: number;
+    summary: string;
+}
+/**
+ * 上传管理器 - 处理多平台并行上传
+ */
+declare class UploadManager {
+    private uploaders;
+    private config;
+    constructor(config?: UploadManagerConfig);
+    /**
+     * 注册上传器
+     */
+    registerUploader(platform: string, uploader: IUploader): void;
+    /**
+     * 获取启用的平台列表（根据配置）
+     */
+    getEnabledPlatforms(config: any): string[];
+    /**
+     * 获取可用的平台列表
+     */
+    getAvailablePlatforms(): string[];
+    /**
+     * 执行并行上传（支持多文件智能分发）
+     */
+    uploadToMultiplePlatforms(filePaths: string | string[], // 支持单文件或文件数组
+    config: any, metadata: AppMetadata, targetPlatforms?: string[]): Promise<UploadReport>;
+    /**
+     * 上传到单个平台
+     */
+    private uploadToPlatform;
+    /**
+     * 聚合上传结果
+     */
+    private aggregateResults;
+    /**
+     * 输出上传报告
+     */
+    private printReport;
+    /**
+     * 格式化持续时间
+     */
+    private formatDuration;
+    /**
+     * 获取可重试的失败平台
+     */
+    getRetryablePlatforms(report: UploadReport): string[];
+    /**
+     * 重试失败的平台
+     */
+    retryFailedPlatforms(failedPlatforms: string[], filePath: string, config: any, metadata: AppMetadata): Promise<UploadReport>;
+}
+/**
+ * 创建上传管理器实例
+ */
+declare function createUploadManager(config?: UploadManagerConfig): UploadManager;
+
+/**
+ * Apple App Store Connect API JWT 生成器
+ *
+ * 使用 ES256 (ECDSA with SHA-256) 算法生成签名 JWT
+ * 有效期: 最多 20 分钟
+ *
+ * 参考: https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests
+ */
+declare class AppleJWTGenerator {
+    private issuerId;
+    private keyId;
+    private privateKey;
+    constructor(issuerId: string, keyId: string, privateKey: string);
+    /**
+     * 从文件路径加载私钥内容
+     */
+    static fromFile(issuerId: string, keyId: string, privateKeyPath: string): Promise<AppleJWTGenerator>;
+    /**
+     * 从内容字符串创建生成器
+     */
+    static fromContent(issuerId: string, keyId: string, privateKeyContent: string): AppleJWTGenerator;
+    /**
+     * 生成 JWT 令牌
+     * @returns Base64URL 编码的 JWT 字符串
+     */
+    generate(): string;
+    /**
+     * 创建 JWT Header
+     */
+    private createHeader;
+    /**
+     * 创建 JWT Payload
+     * 有效期: 20 分钟（1200 秒）
+     */
+    private createPayload;
+    /**
+     * 使用 ES256 算法签名
+     * ES256 = ECDSA with SHA-256
+     */
+    private sign;
+    /**
+     * 解析 DER 格式的签名并提取 r 和 s
+     */
+    private parseDERSignature;
+    /**
+     * 将 Buffer 填充或截断到指定长度
+     */
+    private padBuffer;
+    /**
+     * Base64URL 编码 (RFC 4648)
+     */
+    private base64urlEncode;
+}
+
+/**
+ * 安装包版本信息
+ */
+interface PackageInfo {
+    /** 版本名称，如 "1.2.3" */
+    versionName?: string;
+    /** 版本号（构建号），如 "42" */
+    versionCode?: string;
+    /** 包名/Bundle ID，如 "com.example.app" */
+    packageName?: string;
+    /** CPU 架构列表 (Android)，如 ["arm64-v8a", "armeabi-v7a"] */
+    nativeCode?: string[];
+    /** 文件 MD5 校验值 */
+    md5?: string;
+}
+/**
+ * 解析选项
+ */
+interface ParseOptions {
+    /** Android SDK 路径 */
+    androidSdkPath?: string;
+}
+/**
+ * 从安装包文件中解析版本信息
+ *
+ * 支持三种格式：
+ * - APK: 使用 aapt2/aapt（Android SDK 自带）
+ * - IPA: 使用 unzip + plutil（macOS 原生）
+ * - HAP: 使用 unzip（系统自带）
+ *
+ * 解析失败时返回 null，不会抛出异常
+ */
+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 };