@heybox/hb-sdk-protocol 0.8.1-alpha.8 → 0.8.1

package/generated/native-host-contract.json

@@ -0,0 +1,479 @@
+{
+  "schema": "heybox-mini-program-native-host",
+  "protocolVersion": 1,
+  "contractRevision": 1,
+  "chunkMaxBytes": 65536,
+  "operations": {
+    "system": [
+      "describe"
+    ],
+    "network": [
+      "open",
+      "read",
+      "release",
+      "transfer"
+    ],
+    "files": [
+      "create",
+      "remove",
+      "exists",
+      "openRead",
+      "openWrite",
+      "read",
+      "release",
+      "write",
+      "stat",
+      "list",
+      "pickFiles",
+      "pickDirectory",
+      "saveFile"
+    ]
+  },
+  "cases": [
+    {
+      "name": "system-describe",
+      "valid": true,
+      "request": {
+        "requestId": "req_describe",
+        "domain": "system",
+        "operation": "describe"
+      },
+      "messages": [
+        {
+          "requestId": "req_describe",
+          "type": "result",
+          "payload": {
+            "protocolVersion": 1,
+            "contractRevision": 1,
+            "operations": {
+              "system": [
+                "describe"
+              ],
+              "network": [
+                "open",
+                "read",
+                "release",
+                "transfer"
+              ],
+              "files": [
+                "create",
+                "remove",
+                "exists",
+                "openRead",
+                "openWrite",
+                "read",
+                "release",
+                "write",
+                "stat",
+                "list",
+                "pickFiles",
+                "pickDirectory",
+                "saveFile"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "network-open",
+      "valid": true,
+      "request": {
+        "requestId": "req_open",
+        "domain": "network",
+        "operation": "open",
+        "payload": {
+          "purpose": "download",
+          "url": "https://cdn.example.test/file.zip",
+          "method": "GET",
+          "timeoutMs": 30000
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_open",
+          "type": "result",
+          "payload": {
+            "status": 200,
+            "statusText": "OK",
+            "headers": {
+              "content-length": [
+                "4"
+              ]
+            },
+            "resourceId": "resource_1"
+          }
+        }
+      ]
+    },
+    {
+      "name": "network-read-chunk",
+      "valid": true,
+      "request": {
+        "requestId": "req_read",
+        "domain": "network",
+        "operation": "read",
+        "payload": {
+          "resourceId": "resource_1",
+          "maxBytes": 65536
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_read",
+          "type": "result",
+          "payload": {
+            "resourceId": "resource_1",
+            "data": "dGVzdA==",
+            "byteLength": 4,
+            "eof": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "network-transfer-progress",
+      "valid": true,
+      "request": {
+        "requestId": "req_transfer",
+        "domain": "network",
+        "operation": "transfer",
+        "payload": {
+          "resourceId": "resource_1",
+          "target": {
+            "scope": "sandbox",
+            "kind": "file",
+            "relativePath": "downloads/file.zip"
+          },
+          "mode": "upsert",
+          "maxBytes": 2147483648,
+          "expectedBytes": 4
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_transfer",
+          "type": "progress",
+          "payload": {
+            "resourceId": "resource_1",
+            "loaded": 4
+          }
+        },
+        {
+          "requestId": "req_transfer",
+          "type": "result",
+          "payload": {
+            "committedBytes": 4
+          }
+        }
+      ]
+    },
+    {
+      "name": "files-open-read",
+      "valid": true,
+      "request": {
+        "requestId": "req_file_open",
+        "domain": "files",
+        "operation": "openRead",
+        "payload": {
+          "ref": {
+            "scope": "sandbox",
+            "kind": "file",
+            "relativePath": "data.bin"
+          },
+          "maxBytes": 8388608
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_file_open",
+          "type": "result",
+          "payload": {
+            "resourceId": "file_resource_1"
+          }
+        }
+      ]
+    },
+    {
+      "name": "files-create",
+      "valid": true,
+      "request": {
+        "requestId": "req_create",
+        "domain": "files",
+        "operation": "create",
+        "payload": {
+          "ref": {
+            "scope": "sandbox",
+            "kind": "file",
+            "relativePath": "data.bin"
+          },
+          "recursive": false,
+          "exclusive": true
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_create",
+          "type": "result"
+        }
+      ]
+    },
+    {
+      "name": "files-open-write",
+      "valid": true,
+      "request": {
+        "requestId": "req_write_open",
+        "domain": "files",
+        "operation": "openWrite",
+        "payload": {
+          "ref": {
+            "scope": "sandbox",
+            "kind": "file",
+            "relativePath": "data.bin"
+          },
+          "maxBytes": 8388608
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_write_open",
+          "type": "result",
+          "payload": {
+            "resourceId": "file_write_1"
+          }
+        }
+      ]
+    },
+    {
+      "name": "files-write-chunk",
+      "valid": true,
+      "request": {
+        "requestId": "req_write",
+        "domain": "files",
+        "operation": "write",
+        "payload": {
+          "resourceId": "file_write_1",
+          "data": "AAE=",
+          "byteLength": 2,
+          "eof": true
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_write",
+          "type": "result"
+        }
+      ]
+    },
+    {
+      "name": "files-list",
+      "valid": true,
+      "request": {
+        "requestId": "req_list",
+        "domain": "files",
+        "operation": "list",
+        "payload": {
+          "ref": {
+            "scope": "sandbox",
+            "kind": "directory",
+            "relativePath": ""
+          },
+          "limit": 1000
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_list",
+          "type": "result",
+          "payload": [
+            {
+              "kind": "file",
+              "mode": "readwrite",
+              "name": "data.bin",
+              "ref": {
+                "scope": "sandbox",
+                "kind": "file",
+                "relativePath": "data.bin"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "files-read-chunk",
+      "valid": true,
+      "request": {
+        "requestId": "req_file_read",
+        "domain": "files",
+        "operation": "read",
+        "payload": {
+          "resourceId": "file_resource_1",
+          "maxBytes": 65536
+        }
+      },
+      "messages": [
+        {
+          "requestId": "req_file_read",
+          "type": "result",
+          "payload": {
+            "resourceId": "file_resource_1",
+            "data": "AAE=",
+            "byteLength": 2,
+            "eof": true
+          }
+        }
+      ]
+    },
+    {
+      "name": "cancel-race",
+      "valid": true,
+      "request": {
+        "requestId": "req_cancel",
+        "domain": "network",
+        "operation": "open",
+        "payload": {
+          "purpose": "request",
+          "url": "https://api.example.test/data",
+          "method": "GET",
+          "timeoutMs": 30000
+        }
+      },
+      "cancel": {
+        "type": "cancel",
+        "requestId": "req_cancel"
+      },
+      "messages": [
+        {
+          "requestId": "req_cancel",
+          "type": "error",
+          "error": {
+            "code": "REQUEST_FAILED",
+            "message": "请求已取消"
+          }
+        }
+      ]
+    },
+    {
+      "name": "unsupported-operation",
+      "valid": true,
+      "request": {
+        "requestId": "req_missing",
+        "domain": "files",
+        "operation": "unknown"
+      },
+      "messages": [
+        {
+          "requestId": "req_missing",
+          "type": "error",
+          "error": {
+            "code": "METHOD_FORBIDDEN",
+            "message": "当前客户端不支持该能力"
+          }
+        }
+      ]
+    },
+    {
+      "name": "invalid-shape",
+      "valid": false,
+      "request": {
+        "requestId": "",
+        "domain": "network",
+        "operation": "open"
+      }
+    },
+    {
+      "name": "oversized-chunk",
+      "valid": false,
+      "message": {
+        "requestId": "req_big",
+        "type": "result",
+        "payload": {
+          "resourceId": "resource_1",
+          "data": "",
+          "byteLength": 65537,
+          "eof": false
+        }
+      }
+    },
+    {
+      "name": "zero-nonterminal-chunk",
+      "valid": false,
+      "message": {
+        "requestId": "req_zero",
+        "type": "result",
+        "payload": {
+          "resourceId": "resource_1",
+          "data": "",
+          "byteLength": 0,
+          "eof": false
+        }
+      }
+    },
+    {
+      "name": "duplicate-terminal",
+      "valid": false,
+      "messages": [
+        {
+          "requestId": "req_dup",
+          "type": "result"
+        },
+        {
+          "requestId": "req_dup",
+          "type": "error",
+          "error": {
+            "code": "REQUEST_FAILED",
+            "message": "重复终态"
+          }
+        }
+      ]
+    },
+    {
+      "name": "late-progress",
+      "valid": false,
+      "messages": [
+        {
+          "requestId": "req_late",
+          "type": "result"
+        },
+        {
+          "requestId": "req_late",
+          "type": "progress",
+          "payload": {
+            "resourceId": "resource_1",
+            "loaded": 1
+          }
+        }
+      ]
+    },
+    {
+      "name": "cross-session-handle",
+      "valid": false,
+      "request": {
+        "requestId": "req_cross",
+        "domain": "files",
+        "operation": "stat",
+        "payload": {
+          "ref": {
+            "scope": "grant",
+            "id": "other_session_handle",
+            "kind": "file",
+            "relativePath": ""
+          }
+        }
+      }
+    },
+    {
+      "name": "redacted-error",
+      "valid": true,
+      "message": {
+        "requestId": "req_error",
+        "type": "error",
+        "error": {
+          "code": "FILE_ACCESS_DENIED",
+          "message": "文件访问被拒绝"
+        }
+      }
+    }
+  ]
+}

package/generated/permission-catalog.json

@@ -0,0 +1,185 @@
+{
+  "hash": "411af8cb9f6bffc9a10c7b1bdf8eda6f777d25e52e34b8b2e72eb9ab0b2ee095",
+  "permissions": [
+    {
+      "key": "userInfo",
+      "name": "用户信息",
+      "description": "登录小程序并读取当前用户的授权信息。",
+      "access": "declaration",
+      "risk": "medium",
+      "config": {},
+      "methods": [
+        "auth.login",
+        "user.getInfo"
+      ],
+      "conditions": [
+        "继续执行黑盒登录、用户授权和可信手势规则。"
+      ]
+    },
+    {
+      "key": "steamLibrary",
+      "name": "Steam 游戏库",
+      "description": "读取当前用户授权的 Steam 游戏库。",
+      "access": "declaration",
+      "risk": "high",
+      "config": {},
+      "methods": [
+        "user.getSteamGameList"
+      ],
+      "conditions": [
+        "继续执行账号绑定和数据可用性规则。"
+      ]
+    },
+    {
+      "key": "share",
+      "name": "分享",
+      "description": "使用小程序分享、分享菜单和截图能力。",
+      "access": "declaration",
+      "risk": "medium",
+      "config": {},
+      "methods": [
+        "share.copyLink",
+        "share.showShareMenu",
+        "share.screenshot"
+      ],
+      "conditions": [
+        "继续执行分享参数校验和 Host 支持检查。"
+      ]
+    },
+    {
+      "key": "storage",
+      "name": "键值存储",
+      "description": "读写按小程序隔离的简单键值数据。",
+      "access": "declaration",
+      "risk": "medium",
+      "config": {},
+      "methods": [
+        "storage.getStorage",
+        "storage.setStorage"
+      ],
+      "conditions": [
+        "仅用于简单键值存储，不包含文件系统。"
+      ]
+    },
+    {
+      "key": "filesystem",
+      "name": "文件系统",
+      "description": "访问小程序沙盒文件和用户选择的外部文件。",
+      "access": "declaration",
+      "risk": "high",
+      "config": {},
+      "methods": [
+        "network.download",
+        "files.pickFiles",
+        "files.pickDirectory",
+        "files.saveFile",
+        "file.create",
+        "file.remove",
+        "file.exists",
+        "file.readText",
+        "file.writeText",
+        "file.readBytes",
+        "file.writeBytes",
+        "file.stat",
+        "directory.create",
+        "directory.remove",
+        "directory.exists",
+        "directory.list"
+      ],
+      "conditions": [
+        "外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。"
+      ]
+    },
+    {
+      "key": "clipboard",
+      "name": "剪贴板",
+      "description": "向系统剪贴板写入文本。",
+      "access": "declaration",
+      "risk": "medium",
+      "config": {},
+      "methods": [
+        "device.setClipboard"
+      ],
+      "conditions": [
+        "继续执行文本长度和 Host 支持限制。"
+      ]
+    },
+    {
+      "key": "leaderboard",
+      "name": "排行榜",
+      "description": "读写小程序云排行榜。",
+      "access": "declaration",
+      "risk": "medium",
+      "config": {},
+      "methods": [
+        "cloud.leaderboard.submit",
+        "cloud.leaderboard.getList",
+        "cloud.leaderboard.getCurrentUserEntry",
+        "cloud.leaderboard.deleteCurrentUserEntry",
+        "cloud.leaderboard.getInfo"
+      ],
+      "conditions": [
+        "排行榜必须已创建，用户和资源规则保持不变。"
+      ]
+    },
+    {
+      "key": "network",
+      "name": "网络",
+      "description": "通过 network 模块请求或下载外部资源。",
+      "access": "platform-approval",
+      "risk": "high",
+      "config": {
+        "useOfficialDomain": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "是否申请访问小黑盒官方域名。"
+        }
+      },
+      "methods": [
+        "network.request",
+        "network.download"
+      ],
+      "conditions": [
+        "声明后仍需平台批准，并继续执行网络安全策略。"
+      ]
+    },
+    {
+      "key": "companion",
+      "name": "桌面辅助应用",
+      "description": "下载、准备并运行随当前小程序版本发布的受管桌面程序。",
+      "access": "platform-approval",
+      "risk": "high",
+      "config": {},
+      "methods": [
+        "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"
+      ],
+      "conditions": [
+        "声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。"
+      ]
+    }
+  ],
+  "noDeclarationMethods": [
+    "user.revokeAuthorization",
+    "ui.showToast",
+    "ui.showLoading",
+    "ui.hideLoading",
+    "viewport.getWindowInfo",
+    "viewport.setNavigationBarStyle",
+    "device.vibrate",
+    "navigation.close",
+    "navigation.reload",
+    "navigation.openAppPage"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk-protocol",
-  "version": "0.8.1-alpha.8",
+  "version": "0.8.1",
   "description": "Heybox mini-program iframe bridge wire contracts.",
   "sideEffects": false,
   "exports": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "generated",
     "types",
     "src",
     "README.md"
@@ -34,15 +35,18 @@
     "access": "public"
   },
   "scripts": {
+    "prebuild:package": "pnpm run check:native-host-contract",
     "build:package": "pnpm run clean && pnpm run build:lib && pnpm run build:types",
     "build:lib": "rollup -c rollup.config.ts --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
     "build:types": "tsc -p tsconfig.dts.json",
     "test:types": "tsc -p tsconfig.dts.json --noEmit --pretty false",
     "clean": "rimraf ./dist && rimraf ./types",
     "check:boundary": "node scripts/check-boundary.cjs",
+    "gen:native-host-contract": "node scripts/generate-native-host-contract.mjs",
+    "check:native-host-contract": "node scripts/generate-native-host-contract.mjs --check",
     "gen:permission-catalog": "pnpm run build:lib && node scripts/generate-permission-catalog.mjs",
     "check:permission-catalog": "pnpm run build:lib && node scripts/generate-permission-catalog.mjs --check",
-    "pretest:unit": "pnpm run build:types",
+    "pretest:unit": "pnpm run check:native-host-contract && pnpm run build:types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest"
   }

package/src/capabilities.ts

@@ -164,7 +164,9 @@ export const COMPANION_SHOW_NOTIFICATION_METHOD = 'companion.showNotification' a
 export type MiniProgramAuthMethod = typeof AUTH_LOGIN_METHOD;
 export type MiniProgramUserMethod = typeof USER_GET_INFO_METHOD | typeof USER_REVOKE_AUTHORIZATION_METHOD | typeof USER_GET_STEAM_GAME_LIST_METHOD;
 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 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 | typeof NETWORK_DOWNLOAD_METHOD;
 export type MiniProgramFilesMethod = typeof FILES_PICK_FILES_METHOD | typeof FILES_PICK_DIRECTORY_METHOD | typeof FILES_SAVE_FILE_METHOD;