@heybox/hb-sdk-protocol 0.8.1-alpha.1 → 0.8.1-alpha.11

package/types/payloads.d.ts

@@ -146,6 +146,33 @@ export type ScreenshotPayload = {
     post?: MiniProgramSharePostOptions | null;
 } | undefined;
 export type ScreenshotResult = unknown;
+/** 当前小程序实例的运行模式。 */
+export type MiniProgramRuntimeMode = 'production' | 'preview' | 'development' | 'unknown';
+/** Host 明确提供的操作系统名称。 */
+export type MiniProgramOperatingSystemName = 'android' | 'ios' | 'ohos' | 'windows' | 'macos' | 'linux' | 'unknown';
+/**
+ * Runtime 在握手期间下发的环境快照。
+ *
+ * @remarks
+ * 所有字段只用于界面适配、兼容降级和诊断，不能作为鉴权、权限控制或风控依据。
+ * 版本字段均为不透明字符串，除缺失判断外不承诺格式或大小比较语义。
+ */
+export interface MiniProgramRuntimeEnvironmentInfo {
+    readonly runtime: {
+        readonly mode: MiniProgramRuntimeMode;
+    };
+    readonly host: {
+        readonly appVersion: string | null;
+    };
+    readonly miniProgram: {
+        readonly id: string | null;
+        readonly version: string | null;
+    };
+    readonly operatingSystem: {
+        readonly name: MiniProgramOperatingSystemName;
+        readonly version: string | null;
+    };
+}
 export interface GetStoragePayload {
     key: string;
 }
@@ -191,7 +218,6 @@ export interface NetworkRequestPayload {
     data?: unknown;
     headers?: MiniProgramNetworkHeaders;
     timeout?: number;
-    withCredentials?: boolean;
 }
 export interface NetworkResponsePayload<T = unknown> {
     data: T;
@@ -330,7 +356,6 @@ interface NetworkDownloadBasePayload {
     params?: MiniProgramNetworkParams;
     headers?: MiniProgramNetworkHeaders;
     timeout?: number;
-    withCredentials?: boolean;
     maxBytes?: number;
 }
 export type NetworkDownloadPayload = NetworkDownloadBasePayload & ({
@@ -436,4 +461,124 @@ export interface GetLeaderboardInfoResult {
     order: LeaderboardOrder;
     rankLimit: number;
 }
+/** 受管桌面程序可选能力。 */
+export type CompanionCapability = 'stdio' | 'attachments' | 'notifications';
+export type CompanionTarget = 'windows-x64' | 'macos-arm64';
+export type CompanionSignatureStatus = 'unsigned' | 'valid' | 'invalid' | 'unknown';
+/** Companion alias 的跨构建、Runtime 与 Host 规范。 */
+export declare const COMPANION_ALIAS_PATTERN: RegExp;
+/** Companion Host 可跨 bridge 保留的稳定领域错误码。 */
+export declare const COMPANION_ERROR_CODES: readonly ["COMPANION_UNSUPPORTED", "COMPANION_NOT_DECLARED", "COMPANION_TARGET_UNSUPPORTED", "COMPANION_NOT_PREPARED", "COMPANION_PREPARATION_CANCELLED", "COMPANION_DOWNLOAD_FAILED", "COMPANION_DESCRIPTOR_UNAVAILABLE", "COMPANION_ARCHIVE_INVALID", "COMPANION_INTEGRITY_FAILED", "COMPANION_ENTRYPOINT_INVALID", "COMPANION_USER_CANCELLED", "COMPANION_ELEVATION_DENIED", "COMPANION_OS_BLOCKED", "COMPANION_LAUNCH_FAILED", "COMPANION_SESSION_VERSION_MISMATCH", "COMPANION_SESSION_OWNERSHIP_LOST", "COMPANION_SESSION_EXITED", "COMPANION_PIPE_CLOSED", "COMPANION_OUTPUT_LIMIT", "COMPANION_PROCESS_CRASHED", "COMPANION_ATTACHMENT_NOT_FOUND", "COMPANION_NOTIFICATION_UNAVAILABLE", "COMPANION_TERMINATE_FAILED"];
+export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
+export interface CompanionInfo {
+    alias: string;
+    displayName: string;
+    target: CompanionTarget;
+    capabilities: readonly CompanionCapability[];
+    archiveBytes: number;
+    signatureStatus: CompanionSignatureStatus;
+    /** Host 确认的产物来源；旧 Host 缺省时来源未知。 */
+    source?: 'local-dev' | 'released';
+}
+export interface CompanionErrorSummary {
+    code: CompanionErrorCode;
+    message: string;
+    retryable: boolean;
+}
+export type CompanionPrepareProgress = {
+    phase: 'downloading';
+    loaded: number;
+    total?: number;
+} | {
+    phase: 'verifying';
+    processed: number;
+    total: number;
+} | {
+    phase: 'extracting';
+    processed: number;
+    total: number;
+};
+export type CompanionPreparationStatus = {
+    state: 'not-prepared';
+} | {
+    state: 'preparing';
+    progress: CompanionPrepareProgress;
+} | {
+    state: 'ready';
+    preparedAt: number;
+} | {
+    state: 'failed';
+    error: CompanionErrorSummary;
+};
+export type CompanionExitReason = 'exited' | 'terminated' | 'crashed' | 'host-shutdown' | 'permission-revoked' | 'output-limit';
+export type CompanionExit = {
+    reason: 'exited';
+    exitCode: number;
+} | {
+    reason: Exclude<CompanionExitReason, 'exited'>;
+    exitCode?: number;
+};
+/** 活动 Session 的 wire 快照；不包含路径、PID 或原生句柄。 */
+export interface CompanionSessionSnapshot {
+    id: string;
+    alias: string;
+    target: CompanionTarget;
+    capabilities: readonly CompanionCapability[];
+    state: 'running';
+    controllerGeneration: number;
+}
+export interface CompanionAliasPayload {
+    alias: string;
+}
+export type CompanionGetInfoPayload = CompanionAliasPayload;
+export type CompanionGetInfoResult = CompanionInfo;
+export type CompanionGetPreparationStatusPayload = CompanionAliasPayload;
+export type CompanionGetPreparationStatusResult = CompanionPreparationStatus;
+export type CompanionPreparePayload = CompanionAliasPayload;
+export type CompanionPrepareResult = CompanionInfo;
+export type CompanionCancelPreparationPayload = CompanionAliasPayload;
+export type CompanionCancelPreparationResult = void;
+export type CompanionGetActiveSessionPayload = CompanionAliasPayload;
+export type CompanionGetActiveSessionResult = CompanionSessionSnapshot | undefined;
+export type CompanionLaunchPayload = CompanionAliasPayload;
+export type CompanionLaunchResult = CompanionSessionSnapshot;
+export interface CompanionSessionControllerPayload {
+    sessionId: string;
+    controllerGeneration: number;
+}
+export interface CompanionSessionWritePayload extends CompanionSessionControllerPayload {
+    data: Uint8Array;
+}
+export type CompanionSessionWriteResult = void;
+export type CompanionSessionCloseStdinPayload = CompanionSessionControllerPayload;
+export type CompanionSessionCloseStdinResult = void;
+export type CompanionSessionTerminatePayload = CompanionSessionControllerPayload;
+export type CompanionSessionTerminateResult = void;
+export interface CompanionSessionAckOutputPayload extends CompanionSessionControllerPayload {
+    stream: 'stdout' | 'stderr';
+    sequence: number;
+}
+export type CompanionSessionAckOutputResult = void;
+export interface CompanionOpenAttachmentPayload extends CompanionSessionControllerPayload {
+    id: string;
+}
+export type CompanionOpenAttachmentResult = MiniProgramFileDescriptor;
+export type CompanionNotificationCategory = 'completed' | 'failed' | 'stopped' | 'attention';
+export interface CompanionShowNotificationPayload extends CompanionSessionControllerPayload {
+    category: CompanionNotificationCategory;
+}
+export type CompanionShowNotificationResult = void;
+export interface CompanionSessionOutputPayload extends CompanionSessionControllerPayload {
+    stream: 'stdout' | 'stderr';
+    sequence: number;
+    data: Uint8Array;
+}
+export interface CompanionSessionExitPayload {
+    sessionId: string;
+    exit: CompanionExit;
+}
+export interface CompanionSessionOwnershipLostPayload {
+    sessionId: string;
+    controllerGeneration: number;
+}
 export {};

package/types/permission-catalog.d.ts

@@ -1,5 +1,5 @@
 import type { MiniProgramBridgeMethod, MiniProgramCapabilityRisk } from './capabilities';
-export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network"];
+export declare const MINI_PROGRAM_PERMISSION_KEYS: readonly ["userInfo", "steamLibrary", "share", "storage", "filesystem", "clipboard", "leaderboard", "network", "companion"];
 export type MiniProgramPermissionKey = (typeof MINI_PROGRAM_PERMISSION_KEYS)[number];
 export type MiniProgramPermissionRequirement = {
     readonly kind: 'none';
@@ -103,6 +103,15 @@ export declare const MINI_PROGRAM_PERMISSION_CATALOG: readonly [{
     };
     readonly methods: readonly ["network.request", "network.download"];
     readonly conditions: readonly ["声明后仍需平台批准，并继续执行网络安全策略。"];
+}, {
+    readonly key: "companion";
+    readonly name: "桌面辅助应用";
+    readonly description: "下载、准备并运行随当前小程序版本发布的受管桌面程序。";
+    readonly access: "platform-approval";
+    readonly risk: "high";
+    readonly config: {};
+    readonly methods: readonly ["companion.getInfo", "companion.getPreparationStatus", "companion.prepare", "companion.cancelPreparation", "companion.getActiveSession", "companion.launch", "companion.session.write", "companion.session.closeStdin", "companion.session.terminate", "companion.session.ackOutput", "companion.openAttachment", "companion.showNotification"];
+    readonly conditions: readonly ["声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"];
 }];
 export declare const MINI_PROGRAM_NO_DECLARATION_METHODS: readonly ["user.revokeAuthorization", "ui.showToast", "ui.showLoading", "ui.hideLoading", "viewport.getWindowInfo", "viewport.setNavigationBarStyle", "device.vibrate", "navigation.close", "navigation.reload", "navigation.openAppPage"];
 export declare function isMiniProgramPermissionKey(key: string): key is MiniProgramPermissionKey;