@thuzjq/meteorcloud-device-sdk-node 0.5.1

package/README.md

@@ -0,0 +1,45 @@
+# @thuzjq/meteorcloud-device-sdk-node
+
+MeteorCloud SDK for Node.js >=20.10. Version 0.5.1.
+
+## Install
+
+```sh
+npm install @thuzjq/meteorcloud-device-sdk-node@0.5.1
+```
+
+The SDK has no required runtime dependencies. Windows DPAPI key storage uses
+optional peer dependency `@meteorlive/dpapi`. Install it separately when selecting
+that storage provider. Never log or distribute private keys or access tokens.
+
+## Integration
+
+Read the [Node integration guide](docs/NODE_INTEGRATION_GUIDE.zh-CN.md).
+The package includes CommonJS exports and TypeScript declarations in `index.d.ts`.
+
+Your application authorizes an installation through `MeteorCloud.connect()` and
+reports events through `client.uploadEvent()`. The SDK handles request signing,
+token renewal, chunked uploads, retry handling and resumable upload journals.
+Product client identifiers must be assigned by MeteorCloud.
+
+## Station declarations
+
+Supply `camera.key` and `camera.station.latitude`, `longitude`, and measured
+`elevationM`. `timezone` is optional with a compatible server. The server resolves
+an IANA zone and applies daylight-saving rules for the observation date.
+Country, province, city and district are server-enriched metadata. They may
+remain pending if the lookup service is unavailable.
+
+A camera key represents a fixed observing position. Create and persist a new key
+when the position changes. Existing observations retain their original identity.
+SDK resource deletion is not supported; use the website's available controls.
+
+## Verification
+
+Validate authorization, upload and resume behavior with an authorized test account
+before integrating into an unattended capture workflow. Upload completion and
+subsequent scientific processing are separate states; see the integration guide.
+
+## License
+
+UNLICENSED. Public package availability does not grant an open-source license.

package/docs/NODE_INTEGRATION_GUIDE.zh-CN.md

@@ -0,0 +1,414 @@
+
+# 流星云（MeteorCloud）Node.js SDK 接入指南
+
+> 面向：把自己的软件接入流星云的 Node 开发者
+> 版本：`@thuzjq/meteorcloud-device-sdk-node` `0.5.1`，Node 20.10+，**零运行时依赖**
+> `client_id` 由我们分配：`meteormasterai` / `meteorstudio` / `ufocapture-adapter`
+
+| | |
+| --- | --- |
+| **管什么** | 用户怎么授权、开发者怎么调、SDK 内部怎么工作、要准备什么数据、错误怎么分类、密钥存哪 |
+| **不管什么** | 不讲服务端实现、不讲科学流水线、不讲你自己的采集与配置模型 |
+| **权威来源** | 代码即权威：`index.d.ts`（类型）、`index.js`、`lib/`、`test/`。文档与代码冲突时以代码为准 |
+
+---
+
+## 0. 现在能做什么，不能做什么
+
+## 0.5.1
+
+机位声明必填 latitude、longitude、elevationM，timezone 可省略。服务端按坐标解析
+IANA 时区并按日期处理夏令时。行政区划查询不可用时，相关字段可能待补全。
+换位置需要新的 camera.key。SDK 不提供删除接口。
+
+接入方应使用获授权的测试账号完成授权、上传和恢复验证。
+
+---
+
+## 上报成功与科学配对独立
+
+`await client.uploadEvent(...)` 返回 `status: 'completed'` 就是上报成功。立即保存
+`uploadUid` / `jobUid`、显示“上报成功”、关闭上传转圈，无需等待科学配对。
+
+科学配对是可选的后续查询。多数单站数据不一定有配对结果；`pending` 可显示
+“暂无配对结果”，`rejected` 表示科学结果未确认，`failed` 表示后续处理异常。
+这些状态以及查询超时均不得覆盖上传成功状态，也不得触发重新上传。
+
+只在用户查看科学结果时按需查询 `client.jobStatus(jobUid)`。如使用轮询，应遵守
+`nextPollAfterSeconds`，离开页面或 `resultFinal === true` 时停止；不要让上传队列
+等待科学结果，不要把 `scientific_result_rejected` 显示成“上传失败”。
+
+## 1. 用户视角：一次授权，之后无感
+
+用户在你的软件里点一次"连接流星云"，然后：
+
+| 步骤 | 用户看到什么 |
+| --- | --- |
+| 1 | 系统默认浏览器自动打开 |
+| 2 | 没登录就是流星云登录页，用已有账号登录（含微信）；已登录直接跳过 |
+| 3 | 一屏"是否允许〈你的软件〉访问我的流星云账户"，点**允许** |
+| 4 | 浏览器显示"绑定完成，可以关闭"，你的软件那边 `connect()` 返回 |
+
+**用户不做的事**：不用从管理网页复制任何码，不用勾选相机，不用填写任何 UID。
+确认页上没有相机列表。
+
+之后就没有用户的事了。相机和站点由服务端在**第一次上报时自动登记**，用户在网页上
+能看到它们；用户可以在网页上把自动建出的临时站标为固定站，也可以吊销某个安装实例。
+这些都是纯服务端动作，你的上报代码一个字都不用改。
+
+---
+
+## 2. 开发者视角：最小可用代码
+
+```bash
+npm install @thuzjq/meteorcloud-device-sdk-node
+# 仅 Windows、且要用不落盘的密钥档时（可选 peer，见 §7）
+npm install @meteorlive/dpapi
+```
+
+### 2.1 首次连接（每个安装一次）
+
+```js
+const { MeteorCloud } = require('@thuzjq/meteorcloud-device-sdk-node')
+
+const { client, account } = await MeteorCloud.connect({
+  issuer: 'https://cloud.meteorlive.com/cloud',   // 必须带 /cloud
+  clientId: 'meteormasterai',
+  configPath: 'C:/ProgramData/YourApp/meteorcloud.json',
+  keyPath:    'C:/ProgramData/YourApp/meteorcloud.key'
+})
+```
+
+SDK 会自己生成本机私钥、起环回监听、打开浏览器、等回调、换码、写配置、取 Token、读账户。
+
+`issuer` 的 `/cloud` 不是可选的：它同时决定路由、客户端断言的 `aud` 和 DPoP 的 `htu`。
+漏掉它的表现是 404 或 `invalid_client`，不像是 URL 写错。
+
+### 2.2 后续启动（不再走浏览器）
+
+```js
+const { MeteorCloudClient } = require('@thuzjq/meteorcloud-device-sdk-node')
+
+const client = await MeteorCloudClient.fromConfig('C:/ProgramData/YourApp/meteorcloud.json')
+if (!(await client.isBound())) {
+  // 私钥丢了或当前 Windows 用户读不出来，提示用户重新授权
+}
+```
+
+`fromConfig()` 只读配置、不碰密钥，所以务必用 `isBound()` 探一次：否则最早要等到
+`uploadEvent()` 把几个 G 的文件哈希完才发现签不了名。
+
+### 2.3 日常上报
+
+```js
+await client.uploadEvent({
+  camera: {
+    key: channel.cloudKey,          // 你为这一路生成一次并存进自己配置的稳定键
+    name: '北向广角',
+    station: {
+      latitude: 36.07, longitude: 120.38, elevationM: 45,
+      timezone: 'Asia/Shanghai', name: '青岛家里'
+    }
+  },
+  clientRequestKey: eventId,        // 幂等键，你的事件 ID
+  manifestJson,                     // 与 manifest 文件字节完全一致的 JSON 字符串
+  artifacts: [
+    { role: 'manifest', path: manifestPath, contentType: 'application/json' },
+    { role: 'ecsv',     path: ecsvPath,     contentType: 'text/plain' },
+    { role: 'media',    path: mp4Path,      contentType: 'video/mp4' }
+  ],
+  journalPath: `${workDir}/${eventId}.journal.json`
+})
+```
+
+`channel.cloudKey` 用 `MeteorCloud.newCameraKey()` 生成一次，存进**你自己的**配置，之后一直用它。
+
+就这些。绑定一次，之后每次上报带上机位声明即可。
+
+---
+
+## 3. 它是怎么工作的
+
+### 3.1 三层身份
+
+| 层 | 载体 | 寿命 | 能干什么 |
+| --- | --- | --- | --- |
+| 用户 | 浏览器登录态 | 会话级 | 登录、同意或拒绝 |
+| 安装实例 | 本机 P-256 私钥 + `installation_uid` | 长期，可吊销 | 代表该账户换取短期 Token |
+| 操作 Token | 不透明 Token，DPoP 绑定 | 10 分钟 | 查询账户资源、上报、查任务 |
+
+**没有 Refresh Token，也没有任何长期 Bearer 凭据落盘。** 续期靠本机私钥现签一份
+RFC 7523 断言换新 Token，SDK 在过期前 60 秒自动做，并发调用共享同一次续期。
+Token 只在内存里；配置文件、journal、日志都写不进去（写入前有拦截）。
+
+一年没开机的客户端和一分钟前刚跑过的，行为完全一样。
+
+### 3.2 机位声明：客户端不维护任何清单
+
+三份数据分属三方，不要混：
+
+| 数据 | 谁持有 | SDK 会读吗 |
+| --- | --- | --- |
+| 你软件本地的站点、通道、摄像头配置 | 你的软件 | **不会**。SDK 不扫描、不接收、不同步 |
+| 流星云账户下已登记的站点、相机 | 服务端 | 只有你显式调查询方法时 |
+| 本次上报的机位声明 | 你在业务时刻决定 | 作为单次参数接收，用完即忘 |
+
+服务端的识别规则（你零参与）：
+
+- **相机身份** = `(租户, 账户, 产品 client_id, camera.key)`。见过即是，没见过就建。
+- **站点身份 = 位置**。同账户下坐标按列精度取整后相同即同一站；多路填同样坐标自动归到一站；
+  没见过的坐标就新建一个**临时站**。
+- **站点不可改，相机可迁移**。已知相机换了坐标就挂到另一个站，旧站保留。
+- **名字**首次建立时采用；之后改名只改相机名，不动站点。
+
+`authorize()` 的响应会回 `stationUid` / `cameraUid` / `createdStation` / `createdCamera`，
+**仅作告知**，你不必保存。下次上报凭同一个 `camera` 块就能定位到同一台相机。
+（注意：`uploadEvent()` 返回的是 finalize 响应，不带这四个字段。）
+
+已经手里有 `cameraUid` 的，可以用 `cameraUid` 代替 `camera` 块，这是正常用法而非兼容层。
+两者都不给会在**读文件之前**本地报错，不会白哈希一遍几个 G 的视频。
+
+### 3.3 一次上报的三段
+
+```
+authorize  →  分块 PUT  →  finalize
+```
+
+1. **authorize**：本地先校验机位声明，再哈希全部文件，把尺寸和 SHA-256 报给服务端换一个会话。
+2. **分块 PUT**：每块默认 32 MiB，带 `Content-Range` 和该块的 SHA-256，逐块顺序直传到我们自己的服务器。
+3. **finalize**：服务端重新校验全文摘要，落库，返回 `jobUid`。
+
+### 3.4 断点续传与幂等
+
+- **服务端的 `receivedBytes` 是唯一权威**。任何失败后客户端都会重读它再续传，
+  所以"块传到了但 200 丢了"会被识别成进度，而不是重传成冲突。
+- `journalPath` 是本地进度提示，**一个事件一份**，成功前不要删。它只是加速，
+  丢了也不影响正确性；磁盘满了写不进去也不会中断上传。
+- `clientRequestKey` 是幂等键。同一个键重报同样内容会拿回同一个会话；
+  内容不同则报冲突。**换事件要换键。**
+- 收到 429 时 SDK 会遵守 `Retry-After`。服务端对上传控制面按 IP 限每分钟 20 次，
+  一次事件至少占 2 次。
+
+---
+
+## 4. API 速查
+
+必学的只有四个，其余按需。
+
+| 方法 | 作用 |
+| --- | --- |
+| `MeteorCloud.connect(options)` | 首次授权，返回 `{ client, token, account, installation, config, configPath }` |
+| `MeteorCloud.beginConnect(options)` | 两阶段版：先拿 `authorizationUrl` 自己去开（Electron / 内嵌 WebView），再 `await pending.wait()`；`pending.cancel()` 取消 |
+| `MeteorCloud.newCameraKey()` | 生成 32 位十六进制稳定键。纯本地，无网络 |
+| `MeteorCloudClient.fromConfig(path)` | 从配置恢复客户端 |
+| `client.isBound()` | 私钥是否真的可用（会试签一次，不只是看文件在不在） |
+| `client.uploadEvent(request)` | 上报一个事件：authorize → 分块 → finalize |
+| `client.jobStatus(jobUid)` | 查科学任务状态 |
+| `client.getAccount()` | 当前账户摘要 `{ accountId, nickname, tenantId }` |
+| `client.listStations(query?)` / `listCameras(query?)` / `getCamera(uid)` | 读回账户已登记的资源。普通查询，**不缓存**，不要在启动或上传时调 |
+| `client.ensureCamera(block)` | 可选预建。参数是 `camera` 块**本身**（不是 `{camera:{...}}`），行为与上报时的登记完全一致 |
+| `client.authorize(request)` / `uploadAuthorized(...)` / `finalize(uid)` / `abort(uid)` | 拆开用的低层接口 |
+| `client.getAccessToken()` | 取当前 Token（互操作用，不是让你自己管续期） |
+
+`ConnectOptions` 常用项：`issuer`、`clientId`、`configPath`、`keyPath`、`keyStoreScheme`
+（`file` / `dpapi` / `cng`）、`browserMode`（`system` 默认 / `manual`）、`onAuthorizeUrl`、
+`signal`（`AbortSignal`）、`timeoutMs`（默认 5 分钟）。
+
+进度回调 `onProgress(progress)` 的 `stage` 依次是
+`hashing` → `authorizing` → `uploading`（带 `role` / `transferredBytes` / `totalBytes`）
+→ `finalizing` → `completed`。**回调返回 `false` 即取消上传。**
+
+---
+
+## 5. 你要准备的数据
+
+### 5.1 机位声明字段
+
+| 字段 | 必填 | 规则 |
+| --- | --- | --- |
+| `camera.key` | 是 | 1–64 字符，`A-Za-z0-9._:-`，首字符为字母或数字。**不含个人信息**。改键 = 换相机 |
+| `camera.name` | 否 | ≤128 字符，不含控制字符。缺省用 key |
+| `station.latitude` | 是 | WGS84 度，−90 ~ 90。必须是数字，字符串会被拒 |
+| `station.longitude` | 是 | WGS84 度，−180 ~ 180 |
+| `station.elevationM` | 是 | 整数米，−500 ~ 10000 |
+| `station.timezone` | 是 | IANA 时区 id 如 `Asia/Shanghai`。**`+08:00` 这种偏移会被拒**，因为它没有夏令时规则 |
+| `station.name` | 否 | ≤128 字符。仅首次建站时采用 |
+| `cameraUid` | 与 `camera` 二选一 | `cam_` + 32 位小写十六进制 |
+
+校验在**读任何文件之前**完成，错误消息只说字段名和规则，**从不回显坐标值**（那是别人家的位置）。
+
+### 5.2 文件与 manifest
+
+必须三个，`preview` 可选作第四个：
+
+| 角色 | 内容 | 上限 |
+| --- | --- | --- |
+| `manifest` | 事件元数据 JSON | 1 MiB |
+| `ecsv` | 测光/位置序列 | 2 GiB |
+| `media` | 视频或图像 | 100 MiB |
+| `preview` | 预览图（可选） | 20 MiB |
+
+manifest 的硬性要求：
+
+- `schema` 必须是 `"mlc.manifest/2"`；
+- `local_event_id` 必须**逐字等于** `clientRequestKey`；
+- `files.<role>.sha256` 必须与你实际提交的文件摘要一致；没提交的角色要缺省或写 `"-"`；
+- `manifestJson` 字符串与 manifest 文件的字节必须完全一致。
+
+这几条 SDK 都在本地先查一遍。不查的话，服务端的摘要不符会以 **401** 返回，
+读起来像"你的凭据错了"，而实际是 manifest 内容不对。
+
+---
+
+## 6. 错误处理
+
+SDK 只抛一种错误 `MeteorCloudError`。先看 `kind`：
+
+| `kind` | 含义 | 该怎么做 |
+| --- | --- | --- |
+| `validation` | 你的参数不对 | **别重试**，修代码 |
+| `io` | 本地文件读写问题 | 查路径与磁盘 |
+| `transport` | 网络层失败 | 可重试，SDK 内部已退避过 |
+| `device_api` | 服务端拒绝了请求 | 看 `httpStatus` 与 `apiCode` |
+| `auth` | 授权或 Token 问题 | 看 `oauthError` |
+| `keystore` | 密钥不可用 | 多半要重新授权 |
+| `cancelled` | 超时或被取消 | 看 `action` 区分 |
+
+配套字段：`httpStatus`、`apiCode`（服务端稳定业务码）、`retryable`、`retryAfterSeconds`、
+`action`。`error.toSafeObject()` 返回可以直接写日志的版本。
+
+几个必须认识的 `action`：
+
+| `action` | 含义 |
+| --- | --- |
+| `authorize_timeout` | 用户没在超时内完成授权，可以再来一次 |
+| `authorize_cancelled` / `authorize_aborted` | 你自己取消的 |
+| `account_api_unsupported` | 这台服务端还没上账户级 API（见 §0），**升级服务端，不要重新绑定** |
+| `bind_registered_load_config` | **绑定其实成功了**，只是随后取 Token 或读账户失败。**千万不要再调 `connect()`**，那会生成第二把密钥、注册第二个安装实例，把第一个孤立掉。改用 `fromConfig()` 读错误上的 `configPath` |
+
+常见业务码：`1030003035` 没声明机位、`1030003030` 分块顺序错、`1030003026` 幂等键撞了不同内容、
+`1030002005` 摘要不符。
+
+---
+
+## 7. 密钥存储分档
+
+| 档 | `key_reference` | 平台 | 说明 |
+| --- | --- | --- | --- |
+| `cng` | `cng://meteorlive/<名>` | Windows | 最强：私钥不可导出、不落盘。**`@meteorlive/cng` 尚未发布**，Node 侧暂不可用 |
+| `dpapi` | `dpapi://<路径>` | Windows | 默认档。DPAPI 按当前用户加密后落盘。需可选 peer `@meteorlive/dpapi` |
+| `file` | `file://<路径>` | 全平台 | 明文 PKCS#8，权限 0600。**仅开发和受控环境** |
+
+不传 `keyStoreScheme` 时：Windows 用 `dpapi`，其他平台用 `file`。
+
+三条纪律：SDK 只暴露 `sign()`，永远不提供导出私钥；新建密钥不会覆盖已有密钥；
+绑定失败且服务端尚未登记时，本次新建的密钥会被清理，而**服务端一旦登记就绝不销毁密钥**
+（否则会留下一个永远无法认证、只能人工吊销的安装实例）。
+
+配置文件只有五个字段，且**不含任何秘密**：
+
+```json
+{
+  "schema": "mlc.installation/1",
+  "issuer": "https://cloud.meteorlive.com/cloud",
+  "client_id": "meteormasterai",
+  "installation_uid": "ins_<32位十六进制>",
+  "key_reference": "dpapi://C:/ProgramData/YourApp/meteorcloud.key"
+}
+```
+
+---
+
+## 8. 日志纪律
+
+**永远不要记录**：完整 Token、`Authorization` 头、客户端断言、DPoP proof、私钥、
+授权码、PKCE verifier、**完整的授权 URL**。
+
+**可以记录**：错误类别、HTTP 状态、业务码、OAuth `error`、Token 指纹
+（`token.fingerprint`，SHA-256 前 16 位）、`installationUid` 脱敏尾段。
+
+`error.toSafeObject()` 就是按这条规则设计的，直接用它。
+
+---
+
+## 9. 已知缺口
+
+| 缺口 | 影响 |
+| --- | --- |
+| 未在 Windows 真机跑过 0.5.0 | 上一份真机收据属于 0.4.x |
+| `@meteorlive/cng` 未发布、`@meteorlive/dpapi` 未发公开 npm | 最强密钥档 Node 侧不可用；装不上 dpapi 的机器只能退到明文档 |
+| 失败后调 `abort()` 会烧掉幂等键 | 失败后暂时不要 `abort`，直接重试同一个键 |
+| 没有"列出我上传过什么"的接口 | 事件 ID ↔ `jobUid` 的账本要你自己维护 |
+| 站点/相机没有更新和删除 API | 客户端只能被动登记或预建，其余管理动作在网页上做 |
+| 坐标填错会留下一个空临时站 | 无上报的临时站会自动归档，不影响已受理事件。⚠ 服务端尚未实现该归档任务（`archived` 只有常量定义、没有写入方），当前 `archivedAt` 恒不下发，填错的临时站会一直留着 |
+
+---
+
+## 10. 完整示例
+
+```js
+'use strict'
+const { MeteorCloud, MeteorCloudClient, MeteorCloudError } = require('@thuzjq/meteorcloud-device-sdk-node')
+
+const CONFIG = 'C:/ProgramData/YourApp/meteorcloud.json'
+const KEY    = 'C:/ProgramData/YourApp/meteorcloud.key'
+const ISSUER = 'https://cloud.meteorlive.com/cloud'
+
+async function getClient() {
+  try {
+    const client = await MeteorCloudClient.fromConfig(CONFIG)
+    if (await client.isBound()) return client
+  } catch (_) { /* 还没绑定过，往下走 */ }
+
+  const { client, account } = await MeteorCloud.connect({
+    issuer: ISSUER, clientId: 'meteormasterai', configPath: CONFIG, keyPath: KEY
+  })
+  console.log('已连接账户：', account.nickname)
+  return client
+}
+
+async function report(client, event, channel) {
+  const result = await client.uploadEvent({
+    camera: {
+      key: channel.cloudKey,               // MeteorCloud.newCameraKey() 生成一次并存好
+      name: channel.displayName,
+      station: {
+        latitude: channel.lat, longitude: channel.lon,
+        elevationM: channel.elevationM, timezone: channel.timezone
+      }
+    },
+    clientRequestKey: event.id,
+    manifestJson: event.manifestJson,
+    artifacts: [
+      { role: 'manifest', path: event.manifestPath, contentType: 'application/json' },
+      { role: 'ecsv',     path: event.ecsvPath,     contentType: 'text/plain' },
+      { role: 'media',    path: event.mediaPath,    contentType: 'video/mp4' }
+    ],
+    journalPath: `${event.workDir}/${event.id}.journal.json`,
+    onProgress: (p) => { if (p.stage === 'uploading') ui.setProgress(p.transferredBytes / p.totalBytes) }
+  })
+  return result.jobUid            // 存好它，之后用 jobStatus() 查科学结果
+}
+
+async function main(event, channel) {
+  const client = await getClient()
+  try {
+    const jobUid = await report(client, event, channel)
+    console.log('已受理：', jobUid)
+  } catch (error) {
+    if (!(error instanceof MeteorCloudError)) throw error
+    console.error('上报失败', error.toSafeObject())
+    if (error.action === 'bind_registered_load_config') {
+      console.error('绑定是成功的，不要重新授权；配置在', error.configPath)
+    }
+    if (error.kind === 'validation') return   // 参数错，重试没意义
+  }
+}
+```
+
+---
+
+## 11. 相关文档
+
+- [`../README.md`](../README.md) — 英文速查与 API 索引
+- [`../index.d.ts`](../index.d.ts) — 类型定义，附带每个字段的理由，**最权威**