@heybox/hb-sdk-protocol 0.7.5-alpha.0 → 0.8.0-alpha.2

package/src/capabilities.ts

@@ -3,6 +3,14 @@ import type {
   CloseResult,
   CopyLinkPayload,
   CopyLinkResult,
+  DirectoryCreatePayload,
+  DirectoryCreateResult,
+  DirectoryExistsPayload,
+  DirectoryExistsResult,
+  DirectoryListPayload,
+  DirectoryListResult,
+  DirectoryRemovePayload,
+  DirectoryRemoveResult,
   DeleteCurrentUserLeaderboardEntryPayload,
   DeleteCurrentUserLeaderboardEntryResult,
   GetCurrentUserLeaderboardEntryPayload,
@@ -21,16 +29,40 @@ import type {
   GetWindowInfoResult,
   HideLoadingPayload,
   HideLoadingResult,
+  FileCreatePayload,
+  FileCreateResult,
+  FileExistsPayload,
+  FileExistsResult,
+  FileReadBytesPayload,
+  FileReadBytesResult,
+  FileReadTextPayload,
+  FileReadTextResult,
+  FileRemovePayload,
+  FileRemoveResult,
+  FileStatPayload,
+  FileStatResult,
+  FileWriteBytesPayload,
+  FileWriteBytesResult,
+  FileWriteTextPayload,
+  FileWriteTextResult,
   LoginPayload,
   LoginResult,
+  NetworkDownloadPayload,
+  NetworkDownloadResult,
   NetworkRequestPayload,
   NetworkResponsePayload,
   OpenAppPagePayload,
   OpenAppPageResult,
+  PickDirectoryPayload,
+  PickDirectoryResult,
+  PickFilesPayload,
+  PickFilesResult,
   ReloadPayload,
   ReloadResult,
   ScreenshotPayload,
   ScreenshotResult,
+  SaveFilePayload,
+  SaveFileResult,
   SetClipboardPayload,
   SetClipboardResult,
   SetNavigationBarStylePayload,
@@ -60,6 +92,22 @@ export const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationB
 export const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage' as const;
 export const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage' as const;
 export const NETWORK_REQUEST_METHOD = 'network.request' as const;
+export const NETWORK_DOWNLOAD_METHOD = 'network.download' as const;
+export const FILES_PICK_FILES_METHOD = 'files.pickFiles' as const;
+export const FILES_PICK_DIRECTORY_METHOD = 'files.pickDirectory' as const;
+export const FILES_SAVE_FILE_METHOD = 'files.saveFile' as const;
+export const FILE_CREATE_METHOD = 'file.create' as const;
+export const FILE_REMOVE_METHOD = 'file.remove' as const;
+export const FILE_EXISTS_METHOD = 'file.exists' as const;
+export const FILE_READ_TEXT_METHOD = 'file.readText' as const;
+export const FILE_WRITE_TEXT_METHOD = 'file.writeText' as const;
+export const FILE_READ_BYTES_METHOD = 'file.readBytes' as const;
+export const FILE_WRITE_BYTES_METHOD = 'file.writeBytes' as const;
+export const FILE_STAT_METHOD = 'file.stat' as const;
+export const DIRECTORY_CREATE_METHOD = 'directory.create' as const;
+export const DIRECTORY_REMOVE_METHOD = 'directory.remove' as const;
+export const DIRECTORY_EXISTS_METHOD = 'directory.exists' as const;
+export const DIRECTORY_LIST_METHOD = 'directory.list' as const;
 export const UI_SHOW_TOAST_METHOD = 'ui.showToast' as const;
 export const UI_SHOW_LOADING_METHOD = 'ui.showLoading' as const;
 export const UI_HIDE_LOADING_METHOD = 'ui.hideLoading' as const;
@@ -79,7 +127,22 @@ export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_RE
 export type MiniProgramShareMethod = typeof SHARE_COPY_LINK_METHOD | typeof SHARE_SHOW_SHARE_MENU_METHOD | typeof SHARE_SCREENSHOT_METHOD;
 export type MiniProgramViewportMethod = typeof VIEWPORT_GET_WINDOW_INFO_METHOD | typeof VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
 export type MiniProgramStorageMethod = typeof STORAGE_GET_STORAGE_METHOD | typeof STORAGE_SET_STORAGE_METHOD;
-export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD;
+export type MiniProgramNetworkMethod = typeof NETWORK_REQUEST_METHOD | typeof NETWORK_DOWNLOAD_METHOD;
+export type MiniProgramFilesMethod = typeof FILES_PICK_FILES_METHOD | typeof FILES_PICK_DIRECTORY_METHOD | typeof FILES_SAVE_FILE_METHOD;
+export type MiniProgramFileMethod =
+  | typeof FILE_CREATE_METHOD
+  | typeof FILE_REMOVE_METHOD
+  | typeof FILE_EXISTS_METHOD
+  | typeof FILE_READ_TEXT_METHOD
+  | typeof FILE_WRITE_TEXT_METHOD
+  | typeof FILE_READ_BYTES_METHOD
+  | typeof FILE_WRITE_BYTES_METHOD
+  | typeof FILE_STAT_METHOD;
+export type MiniProgramDirectoryMethod =
+  | typeof DIRECTORY_CREATE_METHOD
+  | typeof DIRECTORY_REMOVE_METHOD
+  | typeof DIRECTORY_EXISTS_METHOD
+  | typeof DIRECTORY_LIST_METHOD;
 export type MiniProgramUiMethod = typeof UI_SHOW_TOAST_METHOD | typeof UI_SHOW_LOADING_METHOD | typeof UI_HIDE_LOADING_METHOD;
 export type MiniProgramDeviceMethod = typeof DEVICE_VIBRATE_METHOD | typeof DEVICE_SET_CLIPBOARD_METHOD;
 export type MiniProgramNavigationMethod = typeof NAVIGATION_CLOSE_METHOD | typeof NAVIGATION_RELOAD_METHOD | typeof NAVIGATION_OPEN_APP_PAGE_METHOD;
@@ -96,11 +159,27 @@ export type MiniProgramBridgeMethod =
   | MiniProgramViewportMethod
   | MiniProgramStorageMethod
   | MiniProgramNetworkMethod
+  | MiniProgramFilesMethod
+  | MiniProgramFileMethod
+  | MiniProgramDirectoryMethod
   | MiniProgramUiMethod
   | MiniProgramDeviceMethod
   | MiniProgramNavigationMethod
   | MiniProgramCloudMethod;
-export type MiniProgramCapabilityModule = 'auth' | 'user' | 'share' | 'viewport' | 'storage' | 'network' | 'ui' | 'device' | 'navigation' | 'cloud';
+export type MiniProgramCapabilityModule =
+  | 'auth'
+  | 'user'
+  | 'share'
+  | 'viewport'
+  | 'storage'
+  | 'network'
+  | 'files'
+  | 'file'
+  | 'directory'
+  | 'ui'
+  | 'device'
+  | 'navigation'
+  | 'cloud';
 export type MiniProgramCapabilityRisk = 'low' | 'medium' | 'high';
 
 export interface MiniProgramCapabilityDefinition {
@@ -148,6 +227,46 @@ export const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
   { method: STORAGE_GET_STORAGE_METHOD, module: 'storage', capability: STORAGE_GET_STORAGE_METHOD, permission: 'storage.read', risk: 'low' },
   { method: STORAGE_SET_STORAGE_METHOD, module: 'storage', capability: STORAGE_SET_STORAGE_METHOD, permission: 'storage.write', risk: 'medium' },
   { method: NETWORK_REQUEST_METHOD, module: 'network', capability: NETWORK_REQUEST_METHOD, permission: 'network.request', risk: 'high' },
+  { method: NETWORK_DOWNLOAD_METHOD, module: 'network', capability: NETWORK_DOWNLOAD_METHOD, permission: 'network.request', risk: 'high' },
+  { method: FILES_PICK_FILES_METHOD, module: 'files', capability: FILES_PICK_FILES_METHOD, permission: 'files.external', risk: 'high' },
+  {
+    method: FILES_PICK_DIRECTORY_METHOD,
+    module: 'files',
+    capability: FILES_PICK_DIRECTORY_METHOD,
+    permission: 'files.external',
+    risk: 'high',
+  },
+  { method: FILES_SAVE_FILE_METHOD, module: 'files', capability: FILES_SAVE_FILE_METHOD, permission: 'files.external', risk: 'high' },
+  { method: FILE_CREATE_METHOD, module: 'file', capability: FILE_CREATE_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_REMOVE_METHOD, module: 'file', capability: FILE_REMOVE_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_EXISTS_METHOD, module: 'file', capability: FILE_EXISTS_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_READ_TEXT_METHOD, module: 'file', capability: FILE_READ_TEXT_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_WRITE_TEXT_METHOD, module: 'file', capability: FILE_WRITE_TEXT_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_READ_BYTES_METHOD, module: 'file', capability: FILE_READ_BYTES_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_WRITE_BYTES_METHOD, module: 'file', capability: FILE_WRITE_BYTES_METHOD, permission: 'files.access', risk: 'high' },
+  { method: FILE_STAT_METHOD, module: 'file', capability: FILE_STAT_METHOD, permission: 'files.access', risk: 'high' },
+  {
+    method: DIRECTORY_CREATE_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_CREATE_METHOD,
+    permission: 'files.access',
+    risk: 'high',
+  },
+  {
+    method: DIRECTORY_REMOVE_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_REMOVE_METHOD,
+    permission: 'files.access',
+    risk: 'high',
+  },
+  {
+    method: DIRECTORY_EXISTS_METHOD,
+    module: 'directory',
+    capability: DIRECTORY_EXISTS_METHOD,
+    permission: 'files.access',
+    risk: 'high',
+  },
+  { method: DIRECTORY_LIST_METHOD, module: 'directory', capability: DIRECTORY_LIST_METHOD, permission: 'files.access', risk: 'high' },
   { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, permission: 'ui.toast', risk: 'low' },
   { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
   { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, permission: 'ui.loading', risk: 'low' },
@@ -218,6 +337,22 @@ export interface MiniProgramCapabilityPayloadMap {
   [STORAGE_GET_STORAGE_METHOD]: GetStoragePayload;
   [STORAGE_SET_STORAGE_METHOD]: SetStoragePayload;
   [NETWORK_REQUEST_METHOD]: NetworkRequestPayload;
+  [NETWORK_DOWNLOAD_METHOD]: NetworkDownloadPayload;
+  [FILES_PICK_FILES_METHOD]: PickFilesPayload;
+  [FILES_PICK_DIRECTORY_METHOD]: PickDirectoryPayload;
+  [FILES_SAVE_FILE_METHOD]: SaveFilePayload;
+  [FILE_CREATE_METHOD]: FileCreatePayload;
+  [FILE_REMOVE_METHOD]: FileRemovePayload;
+  [FILE_EXISTS_METHOD]: FileExistsPayload;
+  [FILE_READ_TEXT_METHOD]: FileReadTextPayload;
+  [FILE_WRITE_TEXT_METHOD]: FileWriteTextPayload;
+  [FILE_READ_BYTES_METHOD]: FileReadBytesPayload;
+  [FILE_WRITE_BYTES_METHOD]: FileWriteBytesPayload;
+  [FILE_STAT_METHOD]: FileStatPayload;
+  [DIRECTORY_CREATE_METHOD]: DirectoryCreatePayload;
+  [DIRECTORY_REMOVE_METHOD]: DirectoryRemovePayload;
+  [DIRECTORY_EXISTS_METHOD]: DirectoryExistsPayload;
+  [DIRECTORY_LIST_METHOD]: DirectoryListPayload;
   [UI_SHOW_TOAST_METHOD]: ShowToastPayload;
   [UI_SHOW_LOADING_METHOD]: ShowLoadingPayload;
   [UI_HIDE_LOADING_METHOD]: HideLoadingPayload;
@@ -246,6 +381,22 @@ export interface MiniProgramCapabilityResultMap {
   [STORAGE_GET_STORAGE_METHOD]: GetStorageResult;
   [STORAGE_SET_STORAGE_METHOD]: void;
   [NETWORK_REQUEST_METHOD]: NetworkResponsePayload;
+  [NETWORK_DOWNLOAD_METHOD]: NetworkDownloadResult;
+  [FILES_PICK_FILES_METHOD]: PickFilesResult;
+  [FILES_PICK_DIRECTORY_METHOD]: PickDirectoryResult;
+  [FILES_SAVE_FILE_METHOD]: SaveFileResult;
+  [FILE_CREATE_METHOD]: FileCreateResult;
+  [FILE_REMOVE_METHOD]: FileRemoveResult;
+  [FILE_EXISTS_METHOD]: FileExistsResult;
+  [FILE_READ_TEXT_METHOD]: FileReadTextResult;
+  [FILE_WRITE_TEXT_METHOD]: FileWriteTextResult;
+  [FILE_READ_BYTES_METHOD]: FileReadBytesResult;
+  [FILE_WRITE_BYTES_METHOD]: FileWriteBytesResult;
+  [FILE_STAT_METHOD]: FileStatResult;
+  [DIRECTORY_CREATE_METHOD]: DirectoryCreateResult;
+  [DIRECTORY_REMOVE_METHOD]: DirectoryRemoveResult;
+  [DIRECTORY_EXISTS_METHOD]: DirectoryExistsResult;
+  [DIRECTORY_LIST_METHOD]: DirectoryListResult;
   [UI_SHOW_TOAST_METHOD]: ShowToastResult;
   [UI_SHOW_LOADING_METHOD]: ShowLoadingResult;
   [UI_HIDE_LOADING_METHOD]: HideLoadingResult;

package/src/constants.ts

@@ -5,3 +5,4 @@ export const SDK_HANDSHAKE_METHOD = 'sdk.handshake' as const;
 export const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe' as const;
 export const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report' as const;
 export const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation' as const;
+export const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress' as const;

package/src/guards.ts

@@ -1,13 +1,167 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE } from './constants';
+import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, SDK_HANDSHAKE_METHOD } from './constants';
 import type { MiniProgramBridgeMessage } from './bridge';
+import type {
+  DownloadProgressPayload,
+  MiniProgramDirectoryDescriptor,
+  MiniProgramDirectoryRef,
+  MiniProgramFileDescriptor,
+  MiniProgramFileRef,
+  MiniProgramFileStat,
+  MiniProgramFileSystemEntityDescriptor,
+  MiniProgramPathRootRef,
+} from './payloads';
 
 export function isMiniProgramBridgeMessage(value: unknown): value is MiniProgramBridgeMessage {
-  if (!value || typeof value !== 'object') return false;
-  const message = value as Partial<MiniProgramBridgeMessage>;
+  if (!isRecord(value)) return false;
+  if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+    return false;
+  }
+
+  if (value.type === 'handshake') {
+    return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+  }
+  if (value.type === 'request') {
+    return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+  }
+  if (value.type === 'response') {
+    return (
+      isNonEmptyString(value.id) &&
+      (value.method === undefined || isNonEmptyString(value.method)) &&
+      (value.error === undefined || isBridgeError(value.error))
+    );
+  }
+  if (value.type === 'event') {
+    if (!isNonEmptyString(value.method) || value.error !== undefined) return false;
+    if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
+      return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+    }
+    return value.id === undefined || isNonEmptyString(value.id);
+  }
+  if (value.type === 'cancel') {
+    return (
+      value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined
+    );
+  }
+  return false;
+}
+
+export function isMiniProgramRelativePath(value: unknown): value is string {
+  if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
+    return false;
+  }
+  if (/[\\\u0000-\u001f\u007f]/.test(value)) return false;
+  return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
+}
+
+export function isMiniProgramPathRootRef(value: unknown): value is MiniProgramPathRootRef {
+  if (!isRecord(value)) return false;
+  if (value.kind === 'sandbox') return hasOnlyKeys(value, ['kind']);
+  return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+}
+
+export function isMiniProgramFileRef(value: unknown): value is MiniProgramFileRef {
+  if (!isRecord(value) || value.kind !== 'file') return false;
+  if (isNonEmptyString(value.handleId)) {
+    return hasOnlyKeys(value, ['kind', 'handleId']);
+  }
+  return (
+    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
+  );
+}
+
+export function isMiniProgramDirectoryRef(value: unknown): value is MiniProgramDirectoryRef {
+  if (!isRecord(value) || value.kind !== 'directory') return false;
+  if (isNonEmptyString(value.handleId)) {
+    return hasOnlyKeys(value, ['kind', 'handleId']);
+  }
   return (
-    message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
-    (message.version === 1 || message.version === 2) &&
-    typeof message.nonce === 'string' &&
-    typeof message.type === 'string'
+    isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath'])
   );
 }
+
+export function isMiniProgramFileDescriptor(value: unknown): value is MiniProgramFileDescriptor {
+  return (
+    isRecord(value) &&
+    value.kind === 'file' &&
+    isNonEmptyString(value.name) &&
+    isFileMode(value.mode) &&
+    isMiniProgramFileRef(value.ref) &&
+    hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref'])
+  );
+}
+
+export function isMiniProgramDirectoryDescriptor(value: unknown): value is MiniProgramDirectoryDescriptor {
+  return (
+    isRecord(value) &&
+    value.kind === 'directory' &&
+    isNonEmptyString(value.name) &&
+    isFileMode(value.mode) &&
+    isMiniProgramDirectoryRef(value.ref) &&
+    hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref'])
+  );
+}
+
+export function isMiniProgramFileSystemEntityDescriptor(value: unknown): value is MiniProgramFileSystemEntityDescriptor {
+  return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
+}
+
+export function isMiniProgramByteArray(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
+}
+
+export function isMiniProgramFileStat(value: unknown): value is MiniProgramFileStat {
+  return (
+    isRecord(value) &&
+    value.kind === 'file' &&
+    isNonNegativeSafeInteger(value.size) &&
+    (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
+    (value.createdAt === undefined || isNonNegativeFiniteNumber(value.createdAt)) &&
+    hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt'])
+  );
+}
+
+export function isMiniProgramDownloadProgressPayload(value: unknown): value is DownloadProgressPayload {
+  if (
+    !isRecord(value) ||
+    !isNonNegativeSafeInteger(value.loaded) ||
+    typeof value.lengthComputable !== 'boolean' ||
+    !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])
+  ) {
+    return false;
+  }
+  if (!value.lengthComputable) return value.total === undefined;
+  return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
+}
+
+function isSDKHandshakePayload(value: unknown) {
+  return isRecord(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+}
+
+function isBridgeError(value: unknown) {
+  return isRecord(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+}
+
+function isFileMode(value: unknown) {
+  return value === 'read' || value === 'readwrite';
+}
+
+function isNonNegativeSafeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isNonNegativeFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly string[]) {
+  const allowed = new Set(allowedKeys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/payloads.ts

@@ -189,6 +189,180 @@ export interface NetworkResponsePayload<T = unknown> {
   headers: MiniProgramNetworkHeaders;
 }
 
+export type MiniProgramFileMode = 'read' | 'readwrite';
+
+export interface MiniProgramSandboxRootRef {
+  kind: 'sandbox';
+}
+
+export interface MiniProgramDirectFileRef {
+  kind: 'file';
+  handleId: string;
+}
+
+export interface MiniProgramDirectDirectoryRef {
+  kind: 'directory';
+  handleId: string;
+}
+
+export type MiniProgramPathRootRef = MiniProgramSandboxRootRef | MiniProgramDirectDirectoryRef;
+
+export interface MiniProgramDerivedFileRef {
+  kind: 'file';
+  root: MiniProgramPathRootRef;
+  relativePath: string;
+}
+
+export interface MiniProgramDerivedDirectoryRef {
+  kind: 'directory';
+  root: MiniProgramPathRootRef;
+  relativePath: string;
+}
+
+export type MiniProgramFileRef = MiniProgramDirectFileRef | MiniProgramDerivedFileRef;
+export type MiniProgramDirectoryRef = MiniProgramDirectDirectoryRef | MiniProgramDerivedDirectoryRef;
+export type MiniProgramFileSystemEntityRef = MiniProgramFileRef | MiniProgramDirectoryRef;
+
+export interface MiniProgramFileDescriptor {
+  kind: 'file';
+  name: string;
+  mode: MiniProgramFileMode;
+  ref: MiniProgramFileRef;
+}
+
+export interface MiniProgramDirectoryDescriptor {
+  kind: 'directory';
+  name: string;
+  mode: MiniProgramFileMode;
+  ref: MiniProgramDirectoryRef;
+}
+
+export type MiniProgramFileSystemEntityDescriptor = MiniProgramFileDescriptor | MiniProgramDirectoryDescriptor;
+
+export interface MiniProgramCreateOptions {
+  recursive?: boolean;
+  exclusive?: boolean;
+}
+
+export interface MiniProgramFileStat {
+  kind: 'file';
+  size: number;
+  modifiedAt?: number;
+  createdAt?: number;
+}
+
+export type PickFilesPayload =
+  | {
+      mode?: MiniProgramFileMode;
+      accept?: string[];
+      multiple?: boolean;
+    }
+  | undefined;
+export type PickFilesResult = Array<MiniProgramFileDescriptor & { ref: MiniProgramDirectFileRef }>;
+
+export type PickDirectoryPayload = { mode?: MiniProgramFileMode } | undefined;
+export type PickDirectoryResult = MiniProgramDirectoryDescriptor & { ref: MiniProgramDirectDirectoryRef };
+
+export interface SaveFilePayload {
+  suggestedName: string;
+}
+export type SaveFileResult = MiniProgramFileDescriptor & { ref: MiniProgramDirectFileRef };
+
+export interface FileCreatePayload extends MiniProgramCreateOptions {
+  target: MiniProgramFileRef;
+}
+export type FileCreateResult = void;
+
+export interface FileRemovePayload {
+  target: MiniProgramFileRef;
+}
+export type FileRemoveResult = void;
+
+export interface FileExistsPayload {
+  target: MiniProgramFileRef;
+}
+export type FileExistsResult = boolean;
+
+export interface FileReadTextPayload {
+  target: MiniProgramFileRef;
+}
+export type FileReadTextResult = string;
+
+export interface FileWriteTextPayload {
+  target: MiniProgramFileRef;
+  content: string;
+}
+export type FileWriteTextResult = void;
+
+export interface FileReadBytesPayload {
+  target: MiniProgramFileRef;
+}
+export type FileReadBytesResult = Uint8Array;
+
+export interface FileWriteBytesPayload {
+  target: MiniProgramFileRef;
+  content: Uint8Array;
+}
+export type FileWriteBytesResult = void;
+
+export interface FileStatPayload {
+  target: MiniProgramFileRef;
+}
+export type FileStatResult = MiniProgramFileStat;
+
+export interface DirectoryCreatePayload extends MiniProgramCreateOptions {
+  target: MiniProgramDirectoryRef;
+}
+export type DirectoryCreateResult = void;
+
+export interface DirectoryRemovePayload {
+  target: MiniProgramDirectoryRef;
+  recursive?: boolean;
+}
+export type DirectoryRemoveResult = void;
+
+export interface DirectoryExistsPayload {
+  target: MiniProgramDirectoryRef;
+}
+export type DirectoryExistsResult = boolean;
+
+export interface DirectoryListPayload {
+  target: MiniProgramDirectoryRef;
+  limit?: number;
+}
+export type DirectoryListResult = MiniProgramFileSystemEntityDescriptor[];
+
+export interface DownloadProgressPayload {
+  loaded: number;
+  total?: number;
+  lengthComputable: boolean;
+}
+
+interface NetworkDownloadBasePayload {
+  url: string;
+  params?: MiniProgramNetworkParams;
+  headers?: MiniProgramNetworkHeaders;
+  timeout?: number;
+  withCredentials?: boolean;
+  maxBytes?: number;
+}
+
+export type NetworkDownloadPayload = NetworkDownloadBasePayload &
+  (
+    | {
+        to: MiniProgramFileRef;
+        suggestedName?: never;
+        overwrite?: never;
+      }
+    | {
+        to: MiniProgramDirectoryRef;
+        suggestedName?: string;
+        overwrite?: boolean;
+      }
+  );
+
+export type NetworkDownloadResult = MiniProgramFileDescriptor;
+
 export type MiniProgramToastStatus = 'success' | 'error';
 export interface ShowToastPayload {
   message: string;

package/types/bridge.d.ts

@@ -1,6 +1,6 @@
-import { MINI_PROGRAM_MESSAGE_NAMESPACE } from './constants';
-import type { UserInfoAuthorization } from './payloads';
-export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event';
+import { MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_OPERATION_PROGRESS_METHOD } from './constants';
+import type { DownloadProgressPayload, UserInfoAuthorization } from './payloads';
+export type MiniProgramBridgeMessageType = 'handshake' | 'request' | 'response' | 'event' | 'cancel';
 export type MiniProgramEventName = 'launch' | 'ready' | 'show' | 'hide' | 'unload' | 'error' | 'heybox_app_login_change' | 'user_info_authorization_change';
 export interface MiniProgramBridgeError {
     code: string;
@@ -46,6 +46,22 @@ export interface MiniProgramBridgeMessage<TPayload = unknown> {
     payload?: TPayload;
     error?: MiniProgramBridgeError;
 }
+export interface MiniProgramBridgeCancelMessage extends MiniProgramBridgeMessage<never> {
+    version: 2;
+    type: 'cancel';
+    id: string;
+    method?: never;
+    payload?: never;
+    error?: never;
+}
+export interface MiniProgramBridgeProgressMessage extends MiniProgramBridgeMessage<DownloadProgressPayload> {
+    version: 2;
+    type: 'event';
+    id: string;
+    method: typeof MINI_PROGRAM_OPERATION_PROGRESS_METHOD;
+    payload: DownloadProgressPayload;
+    error?: never;
+}
 export interface MiniProgramEventPayloadMap {
     launch: {
         timestamp: number;