dsh-zspace 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+## 0.3.0 — 2026-10-07
+
+**双通道**：同一网络时直连 NAS 的 WebDAV，跨网络继续走桌面客户端云中转，插件自动选路。工具名与参数**完全不变**（仍是 13 个），既有配置继续可用。
+
+- 新增 `lib/client/webdav.js`：WebDAV 传输层（PROPFIND 列目录/取元信息、MKCOL、PUT、GET（含 Range）、MOVE、COPY、DELETE、Basic 鉴权、namespace 无关的 multistatus 解析、NAS 路径 ↔ DAV 路径双向映射）。
+- 新增 `lib/client/router.js`：选路与回退。`auto`（默认）按**可达性**探测（1.5s PROPFIND，结果缓存 60s）；**运行中** WebDAV 失败（超时/拒绝连接/5xx）会标记下线 30s 并在**同一次调用内**改用中转重试，业务错误（401/403/404/405/409、`N00…`）不触发回退。
+- 新增配置：`transportMode`(auto/webdav/relay)、`webdavUrl`、`webdavUser`、`webdavPassword`、`webdavHomePath`、`webdavPublicPath`、`webdavProbeTimeoutMs`。**密码建议只放环境变量 `ZS_WEBDAV_PASSWORD`（可选 `ZS_WEBDAV_USER`），不要写进 patch**。
+- `zspace_status` 增加 `transport` / `webdavUrl` / `webdavProbe` 字段，并说明当前在用哪条通道、不可用时两边的原因。
+- WebDAV 通道的收益：直连低延迟、不依赖桌面客户端在线、目录列表一次 `PROPFIND` 拿全（没有中转 50 行分页）。注意 `zspace_remove` 在直连通道下是 NAS 侧删除语义（是否进回收站由 NAS 决定）。
+- 验证：**36 项测试**（新增 `test/webdav.test.js` 7 项，含真 socket 的 mock WebDAV 服务器、鉴权失败/不可达探测、auto 选路、运行期回退、强制模式不回退）；真机自检新增通道诊断步骤（配了密码时还会跑一遍 WebDAV 直连写→读往返）。
+
+## 0.1.2 — 2026-10-06
+
+新增一个写入类工具 + 一个配置项，并把文档里的真实池名换成占位符（**无破坏性变更**，工具表新增一行）：
+
+- 新增 `zspace_write`：把文本直接写到 NAS，省掉"先生成本地临时文件再上传"这一步。默认覆盖同名文件，`overwrite: false` 时先探测存在性并拒绝；体积受 `writeMaxBytes` 约束；底层复用同一条上传路径（自动决定单请求/分片），临时文件无论成败都会清理。
+- 新增配置项 `writeMaxBytes`（默认 5 MB），四处同步：Config schema、DEFAULTS、加载期校验、`cordis.patch.yml`。
+- 文档与工具描述里的示例路径由真实的 `/<具体池>/...` 泛化为 `/<pool>/...`（探测候选路径代码保留，那是发现算法的一部分）。
+- 清掉 0.1.1 拆分脚本引入的 19 处重复 JSDoc。
+- 验证：29 项 mock 测试（新增 zspace_write 的 4 类断言）+ 真机 21 步自检（新增"直写文本→读回内容比对"）。
+
 ## 0.1.1 — 2026-10-06
 
 纯内部重构，**对外行为与 API 不变**（`ZSpaceClient` / `ZSpaceError` / `createToolSpecs` / 12 个工具名与参数完全保持）：

package/README.md

@@ -30,17 +30,35 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 2. 该账号对目标空间有权限（个人空间 / 公共空间）；
 3. 不需要给 NAS 开任何端口，也不需要 DDNS。
 
+## 双通道：同网络直连 WebDAV，跨网络走云中转
+
+插件对同一套工具**自动选路**，判断依据是**可达性**而不是 IP 网段（本机在 `192.168.31.x` 也能直连 `<nas-ip>` 的 NAS）：
+
+| 情况 | 通道 | 条件 |
+|---|---|---|
+| 能直连 NAS（同网络） | **WebDAV 直连** | 配了 `webdavUrl` + 环境变量 `ZS_WEBDAV_PASSWORD`；1.5s PROPFIND 探测通过即启用 |
+| 跨网络 / WebDAV 不可达 | 桌面客户端云中转（默认） | 桌面客户端已登录并在运行 |
+
+- WebDAV 通道的好处：延迟更低、不依赖桌面客户端在线、目录列表一次 `PROPFIND` 拿全（没有中转的 50 行分页）。
+- 运行中 WebDAV 掉了（换网、NAS 重启）会**自动回退到中转并在同一次调用内重试**，只损失一点延迟，不会让工具调用失败；30s 后重新探测。
+- `transportMode`：`auto`（默认）/ `webdav`（强制，失败直接报错）/ `relay`（保持旧行为）。
+- 路径映射：NAS 的 `/sata1/my/data/...` ↔ WebDAV 的 `<webdavHomePath>/...`（默认根 `/`）；公共空间由 `webdavPublicPath` 指定（默认空＝不在 WebDAV 暴露，相关路径自动回到中转）。
+- 极空间要在「系统设置 → 文件服务」里开启 WebDAV（默认端口 `5005`，本机实测可用；`5006` 是自签 HTTPS，证书校验会失败）。
+- 密码只走环境变量（`ZS_WEBDAV_PASSWORD`，可选 `ZS_WEBDAV_USER`），**不要写进 patch 文件**——patch 是明文，会被备份/截图带走。
+- `zspace_remove` 在 WebDAV 通道下是 NAS 侧的删除语义（是否进回收站由 NAS 决定）；要确保进回收站请用 `transportMode: relay`。
+
 ## 工具
 
 | 工具 | 作用 |
 |---|---|
-| `zspace_status` | 探活：代理、账号、NAS、存储池余量、个人/公共空间根路径与条目数。其它工具报错时先跑它 |
+| `zspace_status` | 探活：**当前通道**（WebDAV 直连 / 云中转）、代理、账号、NAS、存储池余量、个人/公共空间根路径与条目数。其它工具报错时先跑它 |
 | `zspace_ls` | 列目录，支持 `depth` 递归与 `limit` 预算；自动分页（NAS 单页 50 条） |
 | `zspace_stat` | 单个文件/目录的元信息（大小、修改/创建时间） |
 | `zspace_find` | 按名称在目录树里查找（大小写不敏感子串），会报告扫描了多少条目、是否提前停止 |
 | `zspace_read` | 把小文本文件读进上下文（默认上限 256 KB，二进制自动识别） |
 | `zspace_download` | 从 NAS 下载到本机（默认落到 `~/Downloads/zspace`） |
 | `zspace_upload` | 上传本地文件，**大文件自动走分片协议**，中文文件名可用 |
+| `zspace_write` | 把文本**直接写到 NAS**（省掉本地临时文件），默认覆盖、可传 `overwrite: false` 拒绝覆盖 |
 | `zspace_mkdir` | 建目录 |
 | `zspace_rename` | 就地重命名 |
 | `zspace_move` | 移动到另一个目录（服务端操作，不下载） |
@@ -51,11 +69,11 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 
 | 写法 | 含义 |
 |---|---|
-| 省略 / `""` | 个人空间根（本机实测 `/sata1/my/data`） |
+| 省略 / `""` | 个人空间根（形如 `/<pool>/my/data`，实际值由插件探测） |
 | `home:相册` | 个人空间下的 `相册` |
-| `public:公共分组/skills` | 公共空间下的路径（本机 `/sata1/public/...`） |
+| `public:公共分组/skills` | 公共空间下的路径（形如 `/<pool>/public/...`） |
 | `docs/2026` | 相对个人空间根 |
-| `/sata1/my/data/x.txt` | NAS 绝对路径，原样使用 |
+| `/<pool>/my/data/x.txt` | NAS 绝对路径，原样使用 |
 
 两个根路径由插件按存储池自动探测（`/<pool>/my/data`、`/<pool>/public`），也可在配置里写死。
 
@@ -74,7 +92,14 @@ dsh plugin --profile desktop add /绝对路径/dsh-zspace-0.1.0.tgz
 | `apiVersion` | `2.3.2026042401` | NAS Web API 版本号参数 |
 | `homePath` / `publicPath` | 空＝自动探测 | 写死个人/公共空间根 |
 | `downloadDir` | 空＝`~/Downloads/zspace` | 默认下载目录 |
+| `transportMode` | `auto` | 通道：`auto` / `webdav` / `relay` |
+| `webdavUrl` | 空＝关闭 | WebDAV 地址，如 `http://<nas-ip>:5005/` |
+| `webdavUser` | 空 | WebDAV 账号（NAS 账号）；密码走 `ZS_WEBDAV_PASSWORD` |
+| `webdavPassword` | 空 | 密码兜底项，建议留空改用环境变量 |
+| `webdavHomePath` / `webdavPublicPath` | `/` / 空 | 个人/公共空间在 WebDAV 里的路径（空＝公共空间不暴露） |
+| `webdavProbeTimeoutMs` | `1500` | 直连探测超时 |
 | `readMaxBytes` | `262144` | `zspace_read` 上限 |
+| `writeMaxBytes` | `5242880` | `zspace_write` 单次写入上限（更大的内容用 `zspace_upload`） |
 | `listMaxEntries` | `2000` | 单次列目录/树的上限 |
 | `timeoutMs` / `maxRetries` | `60000` / `2` | 请求超时与瞬时失败重试 |
 | `smallUploadMaxBytes` | `8388608` | 超过就用分片上传 |

package/cordis.patch.yml

@@ -3,11 +3,17 @@
 # A patch replaces the targeted row's whole `config`, so a profile that
 # overrides this row must restate every key it wants to keep.
 #
+# WebDAV fast path: when the machine can reach the NAS directly (same network),
+# `transportMode: auto` probes this URL and uses it; otherwise every call falls
+# back to the desktop client relay. The password is NOT stored here — set
+# ZS_WEBDAV_PASSWORD in the host environment (and optionally ZS_WEBDAV_USER).
+#
 # Every value below has a code-side default, so this patch stays valid even on
 # a host without patch-side helper evaluation. `homePath` / `publicPath` are
 # intentionally empty: the plugin discovers them from the NAS storage pools at
-# runtime (e.g. /sata1/my/data and /sata1/public), which keeps the same file
-# working on NAS models that name their pools differently.
+# runtime (personal space looks like /<pool>/my/data, public space like
+# /<pool>/public), which keeps the same file working on NAS models that name
+# their pools differently.
 
 - insert:
     - id: zspace
@@ -19,10 +25,18 @@
         publicPath: ""
         downloadDir: ""
         readMaxBytes: 262144
+        writeMaxBytes: 5242880
         listMaxEntries: 2000
         timeoutMs: 60000
         maxRetries: 2
         smallUploadMaxBytes: 8388608
         sliceSize: 2097152
+        transportMode: auto
+        webdavUrl: ""
+        webdavUser: ""
+        webdavPassword: ""
+        webdavHomePath: /
+        webdavPublicPath: ""
+        webdavProbeTimeoutMs: 1500
         promptEnabled: true
         promptOrder: 60

package/lib/README.md

@@ -17,15 +17,18 @@ lib/
 │   ├── spaces.js    153 行  代理探活、存储池、个人/公共空间根探测
 │   ├── browse.js     64 行  分页列目录、单条元信息
 │   ├── mutate.js    102 行  mkdir / rename / move / copy / remove
+│   ├── relay.js     31 行  中转通道聚合（把下面各能力汇总成一个面）
+│   ├── webdav.js   520 行  WebDAV 直连通道（PROPFIND/PUT/MOVE/COPY + 路径双向映射）
+│   ├── router.js    99 行  选路：auto 探测 / 强制 / 运行期回退
 │   ├── upload.js    129 行  单请求上传 + 分片协议
 │   └── download.js  128 行  流式下载、限量读入内存
-├── tools.js        66 行   工具注册表：建 ctx、按顺序调用 12 个工厂
+├── tools.js        68 行   工具注册表：建 ctx、按顺序调用 13 个工厂
 └── tools/
     ├── shared.js     52 行  clampInt / entryLine / guarded
     ├── paths.js      84 行  home:/public:/相对/绝对 解析 + 本地路径（含 ~/）
     ├── walk.js      118 行  walkDirectory（ls 递归）、findByName（受限查找）
-    └── <工具名>.js  35-116 行  每个工具一个文件：status ls stat find read
-                                download upload mkdir rename move copy remove
+    └── <工具名>.js  35-120 行  每个工具一个文件：status ls stat find read
+                                download upload write mkdir rename move copy remove
 ```
 
 ## 依赖方向（严格单向，无环）

package/lib/client/browse.js

@@ -39,13 +39,6 @@ export async function list(client, remotePath, options = {}) {
 	return { entries, truncated };
 }
 
-/**
- * File or directory metadata.
- *
- * @param {string} remotePath - absolute remote path.
- * @returns {Promise<ReturnType<typeof toEntry>>} normalized entry.
- */
-
 /**
  * File or directory metadata.
  *

package/lib/client/download.js

@@ -43,14 +43,6 @@ export async function download(client, remotePath, localDir, options = {}) {
 	return { localPath: dest, bytes: stat.size };
 }
 
-/**
- * Read the head of a remote file into memory.
- *
- * @param {string} remotePath - absolute remote file.
- * @param {{maxBytes?: number}} [options] - byte cap.
- * @returns {Promise<{buffer: Buffer, truncated: boolean, bytes: number}>} content.
- */
-
 /**
  * Read the head of a remote file into memory.
  *
@@ -72,13 +64,6 @@ export async function readFile(client, remotePath, options = {}) {
 	return { buffer, truncated, bytes: buffer.length };
 }
 
-/**
- * Open a download response, retrying transient proxy failures.
- *
- * @param {string} remotePath - absolute remote file.
- * @returns {Promise<import("node:http").IncomingMessage>} the open response (caller consumes it).
- */
-
 /**
  * Open a download response, retrying transient proxy failures.
  *

package/lib/client/mutate.js

@@ -18,14 +18,6 @@ export async function mkdir(client, remotePath) {
 	return toEntry(data ?? {});
 }
 
-/**
- * Rename a file or directory in place.
- *
- * @param {string} remotePath - absolute current path.
- * @param {string} newName - new base name (no directory part).
- * @returns {Promise<ReturnType<typeof toEntry>>} the renamed entry.
- */
-
 /**
  * Rename a file or directory in place.
  *
@@ -38,14 +30,6 @@ export async function rename(client, remotePath, newName) {
 	return toEntry(data ?? {});
 }
 
-/**
- * Move files or directories into a target directory.
- *
- * @param {string[]} remotePaths - absolute source paths.
- * @param {string} to - absolute destination directory.
- * @returns {Promise<void>} resolves when the NAS accepted the move.
- */
-
 /**
  * Move files or directories into a target directory.
  *
@@ -57,14 +41,6 @@ export async function move(client, remotePaths, to) {
 	await client.post("/v2/file/move", { paths: remotePaths, to });
 }
 
-/**
- * Copy files or directories into a target directory.
- *
- * @param {string[]} remotePaths - absolute source paths.
- * @param {string} to - absolute destination directory.
- * @returns {Promise<void>} resolves when the NAS accepted the copy.
- */
-
 /**
  * Copy files or directories into a target directory.
  *
@@ -76,13 +52,6 @@ export async function copy(client, remotePaths, to) {
 	await client.post("/v2/file/copy", { paths: remotePaths, to });
 }
 
-/**
- * Delete files or directories (the NAS moves them to its recycle bin).
- *
- * @param {string[]} remotePaths - absolute paths to remove.
- * @returns {Promise<void>} resolves when the NAS accepted the deletion.
- */
-
 /**
  * Delete files or directories (the NAS moves them to its recycle bin).
  *

package/lib/client/relay.js

@@ -0,0 +1,30 @@
+/**
+ * Relay transport: everything through the desktop client's local proxy.
+ *
+ * This is the original (cross-network) path, kept as one uniform surface so the
+ * router can treat it and the WebDAV transport interchangeably. Each function
+ * here is a straight re-export of the capability module that implements it.
+ *
+ * @module dsh-zspace/client/relay
+ */
+
+export { check, homePath, isDirectory, pools, publicPath } from "./spaces.js";
+export { info, list } from "./browse.js";
+export { copy, mkdir, move, remove, rename } from "./mutate.js";
+export { upload, uploadSliced } from "./upload.js";
+export { download, openDownload, readFile } from "./download.js";
+
+/** Transport name used by the router and status output. */
+export const name = "relay";
+
+/**
+ * How to probe this transport. The relay is "up" when the desktop client's
+ * local proxy answers — the same check the plugin has always used.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<boolean>} whether the proxy answers.
+ */
+export async function probe(client) {
+	const { check } = await import("./spaces.js");
+	return await check(client);
+}

package/lib/client/router.js

@@ -0,0 +1,132 @@
+/**
+ * Transport router — WebDAV fast path vs. desktop-client relay.
+ *
+ * The plugin always speaks the same tool surface; this module decides which
+ * transport serves a call:
+ *
+ * | mode | behaviour |
+ * |---|---|
+ * | `auto` (default) | probe WebDAV once per minute; usable → WebDAV, otherwise relay |
+ * | `webdav` | always WebDAV (failures surface loudly) |
+ * | `relay` | always the desktop-client relay (previous behaviour) |
+ *
+ * "Same network" is decided by **reachability**, not by comparing IP prefixes:
+ * a machine on `192.168.31.x` may still route straight to a NAS on
+ * `<nas-ip>`, and a machine on the NAS's own subnet may have WebDAV
+ * disabled. A 1.5s PROPFIND answers that question directly.
+ *
+ * Runtime failures on the WebDAV path (timeouts, refused connections, 5xx)
+ * mark it down for a cooldown and retry the same call over the relay, so losing
+ * the LAN mid-session only costs latency — never a failed tool call. Business
+ * errors (401/403/404/405/409, `N00…` codes) are *not* transport failures and
+ * are returned as-is.
+ *
+ * @module dsh-zspace/client/router
+ */
+
+import * as relay from "./relay.js";
+import { ZSpaceError } from "./errors.js";
+import * as webdav from "./webdav.js";
+
+/** How long a probe result is trusted. */
+const PROBE_TTL_MS = 60_000;
+
+/** How long to stay on the relay after a WebDAV runtime failure. */
+const DOWN_COOLDOWN_MS = 30_000;
+
+/** Methods served by a transport (the rest are relay internals). */
+export const ROUTED_METHODS = [
+	"check",
+	"pools",
+	"isDirectory",
+	"homePath",
+	"publicPath",
+	"list",
+	"info",
+	"mkdir",
+	"rename",
+	"move",
+	"copy",
+	"remove",
+	"download",
+	"readFile",
+	"upload",
+];
+
+/**
+ * Whether an error means "this transport is unusable right now" (as opposed to
+ * a legitimate answer about the path or the credentials).
+ *
+ * @param {unknown} error - thrown value.
+ * @returns {boolean} true when falling back to the relay is the right move.
+ */
+export function isTransportFailure(error) {
+	const code = String(/** @type {{code?: string}} */ (error)?.code ?? "");
+	if (["ETIMEDOUT", "EDAV", "EPROXY", "ECONNREFUSED", "ECONNRESET", "ENETUNREACH", "EAI_AGAIN"].includes(code)) return true;
+	if (/^HTTP(5\d\d)$/.test(code)) return true;
+	return error instanceof TypeError; // undici network failures
+}
+
+/**
+ * Which transport should serve the next call.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<"webdav"|"relay">} chosen transport.
+ */
+export async function selectTransport(client) {
+	const mode = client.transportMode || "auto";
+	if (mode !== "webdav" && mode !== "auto") return "relay";
+	if (!webdav.configured(client)) return "relay";
+	if (mode === "webdav") return "webdav";
+	if (client._webdavDownUntil && Date.now() < client._webdavDownUntil) return "relay";
+
+	const cached = client._webdavProbe;
+	if (cached && Date.now() - cached.at < PROBE_TTL_MS) return cached.usable ? "webdav" : "relay";
+
+	const result = await webdav.probe(client);
+	client._webdavProbe = { at: Date.now(), ...result };
+	return result.usable ? "webdav" : "relay";
+}
+
+/**
+ * Human-readable transport state for `zspace_status`.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @returns {Promise<{transport: string, configured: boolean, probe: Record<string, any>|null}>} report.
+ */
+export async function transportReport(client) {
+	const transport = await selectTransport(client);
+	return {
+		transport,
+		configured: webdav.configured(client),
+		probe: client._webdavProbe ?? null,
+	};
+}
+
+/**
+ * Run one capability through the selected transport, with relay fallback.
+ *
+ * @param {import("../client.js").ZSpaceClient} client - live client.
+ * @param {string} method - capability name (see {@link ROUTED_METHODS}).
+ * @param {unknown[]} args - arguments after the client.
+ * @returns {Promise<any>} capability result.
+ */
+export async function dispatch(client, method, args) {
+	const transport = await selectTransport(client);
+	const implementation = transport === "webdav" ? webdav : relay;
+	const fn = /** @type {Record<string, Function>} */ (implementation)[method];
+	if (typeof fn !== "function") throw new ZSpaceError("ENOTIMPL", `传输 ${transport} 未实现 ${method}`);
+	try {
+		return await fn(client, ...args);
+	} catch (error) {
+		if (transport !== "webdav" || client.transportMode === "webdav" || !isTransportFailure(error)) throw error;
+		client._webdavDownUntil = Date.now() + DOWN_COOLDOWN_MS;
+		client._webdavProbe = {
+			at: Date.now(),
+			reachable: false,
+			usable: false,
+			reason: `运行中失败，${Math.round(DOWN_COOLDOWN_MS / 1000)}s 内走中转：${error?.message ?? error}`,
+		};
+		return await /** @type {Record<string, Function>} */ (relay)[method](client, ...args);
+	}
+}

package/lib/client/session.js

@@ -22,13 +22,6 @@ export function authHeaders(client) {
 	};
 }
 
-/**
- * Common form fields. These belong in the request **body**; the NAS rejects
- * them in the query string with `N001212`.
- *
- * @returns {Record<string, string>} common fields.
- */
-
 /**
  * Common form fields. These belong in the request **body**; the NAS rejects
  * them in the query string with `N001212`.

package/lib/client/spaces.js

@@ -27,12 +27,6 @@ export async function check(client) {
 	});
 }
 
-/**
- * Storage pools (`/zspool/info`), cached per client.
- *
- * @returns {Promise<Array<{name: string, status: string, totalSize: number, freeSize: number}>>} pools.
- */
-
 /**
  * Storage pools (`/zspool/info`), cached per client.
  *
@@ -51,13 +45,6 @@ export async function pools(client) {
 	return client._pools;
 }
 
-/**
- * Whether a remote directory can be listed.
- *
- * @param {string} remotePath - absolute remote path.
- * @returns {Promise<boolean>} true when listing succeeds.
- */
-
 /**
  * Whether a remote directory can be listed.
  *
@@ -74,17 +61,7 @@ export async function isDirectory(client, remotePath) {
 }
 
 /**
- * Locate the personal-space root, e.g. `/sata1/my/data`.
- *
- * Uses the configured path when set, otherwise tries `/<pool>/my/data` for
- * every storage pool and falls back to the historical `/sata11/my/data`.
- *
- * @returns {Promise<string>} personal-space root.
- * @throws {ZSpaceError} when no candidate is listable.
- */
-
-/**
- * Locate the personal-space root, e.g. `/sata1/my/data`.
+ * Locate the personal-space root, e.g. `/<pool>/my/data`.
  *
  * Uses the configured path when set, otherwise tries `/<pool>/my/data` for
  * every storage pool and falls back to the historical `/sata11/my/data`.
@@ -111,14 +88,7 @@ export async function homePath(client) {
 }
 
 /**
- * Locate the public-space root, e.g. `/sata1/public`.
- *
- * @returns {Promise<string>} public-space root.
- * @throws {ZSpaceError} when no candidate is listable (account may lack access).
- */
-
-/**
- * Locate the public-space root, e.g. `/sata1/public`.
+ * Locate the public-space root, e.g. `/<pool>/public`.
  *
  * @returns {Promise<string>} public-space root.
  * @throws {ZSpaceError} when no candidate is listable (account may lack access).

package/lib/client/transport.js

@@ -90,13 +90,6 @@ export function endpointUrl(client, endpoint, query) {
 	return url;
 }
 
-/**
- * Encode form fields, expanding arrays into repeated `key[]` entries.
- *
- * @param {Record<string, unknown>} fields - form fields.
- * @returns {string} urlencoded body.
- */
-
 /**
  * Encode form fields, expanding arrays into repeated `key[]` entries.
  *
@@ -116,15 +109,6 @@ export function formBody(client, fields) {
 	return parts.join("&");
 }
 
-/**
- * Retry a transport call with exponential backoff.
- *
- * @template T
- * @param {() => Promise<T>} attempt - one attempt.
- * @param {(error: unknown) => boolean} shouldRetry - retry predicate.
- * @returns {Promise<T>} the first successful result.
- */
-
 /**
  * Retry a transport call with exponential backoff.
  *
@@ -147,23 +131,6 @@ export async function retrying(client, attempt, shouldRetry) {
 	throw lastError;
 }
 
-/**
- * Send one buffered request.
- *
- * @param {object} options - request options.
- * @param {"GET"|"POST"} [options.method] - HTTP method.
- * @param {string} options.endpoint - API path.
- * @param {Record<string, unknown>} [options.query] - extra query values.
- * @param {Record<string, unknown>} [options.form] - form fields (merged with common params).
- * @param {Record<string, unknown>} [options.fields] - raw fields appended without common params.
- * @param {Buffer} [options.body] - raw request body.
- * @param {string} [options.filePath] - stream this file as the request body.
- * @param {Record<string, string>} [options.headers] - extra headers (override auth).
- * @param {string} [options.url] - absolute URL override (sliced upload).
- * @param {number} [options.timeoutMs] - per-attempt timeout.
- * @returns {Promise<{status: number, headers: import("node:http").IncomingHttpHeaders, text: string}>} response.
- */
-
 /**
  * Send one buffered request.
  *
@@ -268,15 +235,6 @@ export async function send(client, options) {
 	});
 }
 
-/**
- * Validate a buffered JSON response and unwrap its `data`.
- *
- * @param {{status: number, text: string}} response - raw response.
- * @param {string} endpoint - endpoint for error context.
- * @returns {any} the response `data` (or the whole body when it has none).
- * @throws {ZSpaceError} on HTTP failures, HTTP 413 and non-200 business codes.
- */
-
 /**
  * Validate a buffered JSON response and unwrap its `data`.
  *
@@ -306,14 +264,6 @@ export function parse(client, response, endpoint) {
 	return body.data !== undefined ? body.data : body;
 }
 
-/**
- * POST form fields and return the unwrapped `data`.
- *
- * @param {string} endpoint - API path.
- * @param {Record<string, unknown>} [fields] - form fields.
- * @returns {Promise<any>} response data.
- */
-
 /**
  * POST form fields and return the unwrapped `data`.
  *

package/lib/client/upload.js

@@ -52,18 +52,6 @@ export async function upload(client, localPath, remoteDir, options = {}) {
 	}
 }
 
-/**
- * Sliced upload (`/v2/file/upload`), the protocol the desktop client uses
- * for anything the local proxy will not pass through in one request.
- *
- * @param {string} localPath - local file.
- * @param {string} target - absolute remote file path.
- * @param {number} total - total byte size.
- * @param {import("node:fs").Stats} stat - local file stat.
- * @param {(sent: number, total: number) => void} [onProgress] - progress callback.
- * @returns {Promise<void>} resolves when the last slice was accepted.
- */
-
 /**
  * Sliced upload (`/v2/file/upload`), the protocol the desktop client uses
  * for anything the local proxy will not pass through in one request.