dsh-zotero 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wenjie Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,180 @@
+# dsh-zotero
+
+<p align="center">
+  <b>English</b> · <a href="README.md"><b>中文</b></a>
+</p>
+
+Let agents search, read, and cite your local [Zotero](https://www.zotero.org) library: find papers, browse notes and annotations, pull evidence by question, open the source document, generate citations.
+
+Describe what you need in a session and the Agent calls the tools below as needed. The only manual command is `/zotero status`.
+
+## Tools
+
+| Tool                | Purpose                                                                                                                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `zotero_search`     | Discover: search the library by title/creator/year, or indexed full text with `everything`; scope to a collection or saved search.                                                                       |
+| `zotero_get`        | Inspect: read one item's structured core metadata, optionally with manifests and previews of its notes, annotations, and attachments.                                                                    |
+| `zotero_retrieve`   | Evidence: return the most relevant bounded evidence passages (annotations, notes, abstract, full-text chunks) for a query.                                                                               |
+| `zotero_attachment` | Source: resolve an item or attachment ref to the original attachment's verified on-disk path or linked URL. An item ref yields the best attachment Zotero itself picks; an attachment ref pinpoints one. |
+| `zotero_export`     | Cite: let Zotero's own citation/export machinery produce citations, a CSL bibliography, or `bibtex` / `biblatex` / `ris` / `csljson`.                                                                    |
+
+Every tool returns reusable refs of the form `zotero://user/0/<item|attachment|annotation|collection|search>/<KEY>`, optionally qualified with `?server=<id>`. Later calls chain through these refs. The Zotero 10+ `server` qualifier binds a ref to the database that produced it, so a database switch blocks stale refs instead of misreading them.
+
+## Usage example
+
+The Agent moves down the ladder as a request deepens. A typical conversation:
+
+> User: "Find papers about FlashAttention."
+> Agent → `zotero_search`, returning candidates with refs.
+>
+> User: "What is the first one? Have I read it before?"
+> Agent → `zotero_get`: metadata, 17 annotations, 2 notes, limited previews.
+>
+> User: "What did I think about its evaluation?"
+> Agent → `zotero_retrieve(query:"evaluation", sources:["annotations","notes"])`, returning matching note and annotation evidence.
+>
+> User: "How does the paper itself explain memory efficiency?"
+> Agent → `zotero_retrieve(query:"memory efficiency", sources:["fulltext","abstract"])`, returning abstract and full-text passages.
+>
+> User: "Show me the original PDF."
+> Agent → `zotero_attachment(item ref)`, returning the verified file path; if the composition has a PDF/file reader, the Agent hands it off for further analysis.
+>
+> User: "Generate an APA bibliography for these three."
+> Agent → `zotero_export(format:"bibliography", style:"apa")`.
+
+## Command
+
+`/zotero status` reports connectivity, API/schema versions, and the database identity (Server ID, Zotero 10+). This is the only health check. Ordinary calls fail with typed domain errors.
+
+## Limits
+
+- Read-only library: V1 has no path that modifies items, notes, tags, or collections.
+- Full-text evidence depends on Zotero's index: `everything` search and `retrieve` full-text passages both require indexing.
+- Attachment depth depends on the harness composition: `zotero_attachment` returns the file location; reading that PDF further needs a matching file/PDF capability.
+- Evidence ranking is term-based relevance, not embedding or semantic search.
+
+## Requirements
+
+- Zotero desktop with the local API enabled: **Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"**.
+- Read access is unauthenticated on `http://127.0.0.1:23119/api`. V1 has no path that modifies library data (items, notes, tags, collections).
+- Zotero ≥ 7 speaking local API version 3. Upgrade if the status command reports a version mismatch.
+
+## Install
+
+### By package name
+
+```sh
+dsh plugin --profile <name> add dsh-zotero
+```
+
+The tarball ships the built `lib/`; no local build is needed.
+
+### From a local tarball
+
+```sh
+cd dsh-zotero
+npm pack
+dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
+```
+
+`npm pack` runs `prepare` first, so the tarball carries a fresh `lib/`. Use this for unpublished or local trial installs.
+
+### From the GitHub source
+
+```sh
+dsh plugin --profile <name> add github:Vncntvx/dsh-zotero
+```
+
+A git install fetches sources instead of built artifacts, so pnpm installs the dependencies and then runs this package's `prepare` to build in place (TypeScript and `@types/node` live in `dependencies`). pnpm ≥ 10 refuses to run a git dependency's `prepare` by default, so the first `add` fails and points at the fix: add the package key to the profile's `pnpm-workspace.yaml` and re-run:
+
+```yaml
+allowBuilds:
+  dsh-zotero: true
+```
+
+`allowBuilds` grants permission to run the package's code on your machine at install time. Only allow sources you trust, and prefer pinning a commit (`github:Vncntvx/dsh-zotero#<sha>`).
+
+The plugin mounts as id `zotero` and takes effect on the next dsh start. After installing or enabling the plugin, start a new session if the current one was created before the plugin loaded, so the Agent picks up the Zotero tools.
+
+## Configuration
+
+All values are `Config` fields changeable from the bundle's `config` block (e.g. via `dsh plugin config`). Defaults are shown.
+
+| Field                  | Default                      | Meaning                                                      |
+| ---------------------- | ---------------------------- | ------------------------------------------------------------ |
+| `baseUrl`              | `http://127.0.0.1:23119/api` | Local API base URL. Plain loopback HTTP only.                |
+| `provider`             | `local`                      | Provider id to select.                                       |
+| `timeoutMs`            | `5000`                       | Per-request provider deadline.                               |
+| `maxSearchResults`     | `20`                         | Upper bound for `zotero_search` `limit`.                     |
+| `maxEvidenceChars`     | `6000`                       | Total character budget for retrieved evidence.               |
+| `maxEvidencePassages`  | `4`                          | Upper bound for evidence passage counts.                     |
+| `maxDetailChars`       | `3000`                       | Character budget for `zotero_get` abstract previews.         |
+| `maxNoteChars`         | `2000`                       | Character budget per note preview in `zotero_get`.           |
+| `maxNoteRecords`       | `50`                         | Upper bound for note records returned by `zotero_get`.       |
+| `maxAnnotationRecords` | `100`                        | Upper bound for annotation records returned by `zotero_get`. |
+| `fulltextChunkWords`   | `200`                        | Word count per full-text passage entering evidence ranking.  |
+| `maxFulltextChars`     | `250000`                     | Full text accepted into evidence ranking.                    |
+| `maxResponseBytes`     | `16777216`                   | Streaming byte bound for every API response.                 |
+| `maxExportChars`       | `1000000`                    | Export output hard limit. Never mid-truncated.               |
+| `defaultStyle`         | `apa`                        | CSL style for citation/bibliography formats.                 |
+| `defaultLocale`        | `en-US`                      | CSL locale for citation/bibliography formats.                |
+
+## Development
+
+### Commands
+
+```sh
+npm install                      # uses a local npm cache
+npm test                         # unit tests (mock Zotero server)
+npm run test:coverage            # 100% coverage gate on src/
+npm run typecheck                # tsc --noEmit, app + test projects
+npm run build                    # emits lib/
+npm run format                   # prettier --write across the repo
+npm run format:check             # verify formatting (run before committing)
+```
+
+Integration tests run against a live Zotero and stay skipped unless enabled:
+
+```sh
+npm run test:integration
+# or: ZOTERO_INTEGRATION=1 npx vitest run tests/integration/zotero.integration.spec.ts
+```
+
+### Running locally
+
+#### From a dsh source checkout
+
+Build the checkout once (`pnpm install && pnpm run build`), then load the plugin source through the dev overlay:
+
+```sh
+pnpm dsh web --patch ./dsh-zotero/dev.cordis.yml
+```
+
+`dev.cordis.yml` points the plugin entry at the absolute `src/index.ts`. The dsh source launch loads that TypeScript entry through tsx, so the plugin requires no prebuild. Update the absolute path when the checkout location differs.
+
+#### With the npm-installed dsh
+
+**Resident instance**: pack a tarball and install it into a profile. The plugin runs from the tarball copy; code updates require re-packing and re-installing. Verify with the production-stack smoke:
+
+```sh
+npm pack
+dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
+cd ~/.dsh/profiles/<name>
+node --input-type=module < /path/to/dsh-zotero/scripts/smoke.mjs
+```
+
+Run the smoke inside the profile directory, so bare imports resolve from the profile's flat `node_modules`. It verifies `status`, `search`, `get`, `retrieve`, `export`, the policy prompt section, and tool registration; `SMOKE PASS` indicates the packed plugin passes the installed-path checks.
+
+**Dev instance (hot swap)**: the `dev-lib.cordis.yml` overlay disables the profile's tarball copy (id `zotero`), inserts `zotero-dev` at this checkout's `lib/index.js`, and re-enables HMR. The production web profile disables loader HMR, and the HMR watch base sits in the profile directory, so the overlay sets `base` explicitly. When the build output changes, HMR disposes the old instance and re-constructs the plugin in the same process; dsh keeps running:
+
+```sh
+cd /Volumes/Work/deepseek-harness/dsh-zotero
+npm run dev &                    # tsc --watch: rebuild lib on src changes
+dsh web --patch ./dev-lib.cordis.yml --port 3307
+```
+
+Hot swap affects only the instance started with `--patch`; the resident instance keeps running the tarball version.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/README.md

@@ -0,0 +1,180 @@
+# dsh-zotero
+
+<p align="center">
+  <a href="README.en.md"><b>English</b></a> · <b>中文</b>
+</p>
+
+让 Agents 搜索、阅读并引用你的本地 [Zotero](https://www.zotero.org) 文献库：找文献、查看笔记与批注、按问题取证、打开原文、生成引用。
+
+在会话里用自然语言描述需求，Agent 自动按需调用下面的工具；唯一的手动命令是 `/zotero status`。
+
+## 工具
+
+| 工具                | 用途                                                                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `zotero_search`     | 发现：按标题/作者/年份搜索库里的资料，`everything` 模式连全文索引一起搜；可限定某个分类或已保存搜索。                        |
+| `zotero_get`        | 检查：读取一条资料的结构化核心元数据，可选检查笔记、注释、附件的清单与预览。                                                 |
+| `zotero_retrieve`   | 取证：按问题返回最相关的有界证据片段（注释、笔记、摘要、全文分块）。                                                         |
+| `zotero_attachment` | 原文：解析条目或附件 ref，返回原始附件已验证的磁盘路径或链接 URL。条目 ref 取 Zotero 自选的最佳附件，附件 ref 指定单个附件。 |
+| `zotero_export`     | 引用：让 Zotero 按自己的 citation/export 能力生成结果（引用、CSL 参考文献表、`bibtex` / `biblatex` / `ris` / `csljson`）。   |
+
+每个工具都返回形如 `zotero://user/0/<item|attachment|annotation|collection|search>/<KEY>` 的可复用 ref，后续操作都通过它串联。Zotero 10+ 的 `?server=<id>` 限定符把 ref 绑定到产生它的数据库身份，数据库切换时阻止误读旧 ref。
+
+## 使用示例
+
+Agent 按需求逐层深入，一段典型对话：
+
+> 用户：「帮我找 FlashAttention 相关论文」
+> Agent → `zotero_search`，返回候选条目与 ref。
+>
+> 用户：「第一篇是什么？我以前读过吗？」
+> Agent → `zotero_get`：元数据、17 条批注、2 条笔记与有限预览。
+>
+> 用户：「我当时对 evaluation 有什么意见？」
+> Agent → `zotero_retrieve(query:"evaluation", sources:["annotations","notes"])`，返回相关笔记与批注证据。
+>
+> 用户：「论文自己怎么解释 memory efficiency？」
+> Agent → `zotero_retrieve(query:"memory efficiency", sources:["fulltext","abstract"])`，返回摘要与全文片段。
+>
+> 用户：「我要看原 PDF」
+> Agent → `zotero_attachment(条目 ref)`，返回已验证的文件路径；若当前 Harness 配置了 PDF/file 读取能力，再交给该能力继续分析。
+>
+> 用户：「把这三篇生成 APA 参考文献表」
+> Agent → `zotero_export(format:"bibliography", style:"apa")`。
+
+## 命令
+
+`/zotero status` 报告连通性、API/schema 版本和数据库身份标识（Server ID，Zotero 10+）。这是唯一的健康检查。普通调用失败时返回带类型的领域错误。
+
+## 限制
+
+- 对文献库只读：V1 没有任何修改条目、笔记、标签、分类等文献库数据的路径。
+- 全文证据依赖 Zotero 的全文索引：`everything` 搜索和 `retrieve` 的全文片段都以索引为前提。
+- 附件深度分析取决于当前 Harness 配置：`zotero_attachment` 返回文件位置，能否继续读取该 PDF 由 composition 里是否有相应文件/PDF 能力决定。
+- 证据排序是词项相关度检索，不是 embedding 或语义搜索。
+
+## 环境要求
+
+- 已安装 Zotero 桌面版，并启用本地 API：**设置 → 高级 → “Allow other applications on this computer to communicate with Zotero”**。
+- 本地 API 为无认证读取，地址为 `http://127.0.0.1:23119/api`。V1 没有任何修改文献库数据（条目、笔记、标签、分类等）的路径。
+- Zotero ≥ 7，本地 API 版本为 3。如果 status 命令报告版本不匹配，请升级。
+
+## 安装
+
+### 按包名安装
+
+```sh
+dsh plugin --profile <name> add dsh-zotero
+```
+
+tarball 内含已构建的 `lib/`，无需本地构建。
+
+### 本地 tarball
+
+```sh
+cd dsh-zotero
+npm pack
+dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
+```
+
+`npm pack` 先运行 `prepare` 构建 `lib/`，适合未发布或本地试装。
+
+### 从 GitHub 源码安装
+
+```sh
+dsh plugin --profile <name> add github:Vncntvx/dsh-zotero
+```
+
+git 安装拉取源码而非构建产物，pnpm 安装依赖后运行本包的 `prepare` 现场构建（TypeScript 与 `@types/node` 在 `dependencies` 中）。pnpm ≥ 10 默认拒绝运行 git 依赖的 `prepare`，首次 `add` 会失败并提示：把包名加进 profile 的 `pnpm-workspace.yaml` 后重新执行：
+
+```yaml
+allowBuilds:
+  dsh-zotero: true
+```
+
+`allowBuilds` 授权该包在安装时执行代码，只允许你信任的来源，建议固定到具体提交（`github:Vncntvx/dsh-zotero#<sha>`）。
+
+插件以 id `zotero` 挂载，下次启动 dsh 时生效。安装或启用插件后，如果当前会话创建于插件加载之前，请新建会话，确保 Agent 获得 Zotero 工具。
+
+## 配置
+
+所有值都是 `Config` 字段，可在 bundle 的 `config` 块中修改（例如通过 `dsh plugin config`）。以下为默认值。
+
+| 字段                   | 默认值                       | 含义                                   |
+| ---------------------- | ---------------------------- | -------------------------------------- |
+| `baseUrl`              | `http://127.0.0.1:23119/api` | 本地 API 基础 URL。仅支持纯回环 HTTP。 |
+| `provider`             | `local`                      | 要选择的 provider id。                 |
+| `timeoutMs`            | `5000`                       | 每个请求的 provider 超时时间。         |
+| `maxSearchResults`     | `20`                         | `zotero_search` `limit` 的上限。       |
+| `maxEvidenceChars`     | `6000`                       | 检索证据的总字符预算。                 |
+| `maxEvidencePassages`  | `4`                          | 证据片段数量的上限。                   |
+| `maxDetailChars`       | `3000`                       | `zotero_get` 摘要预览的字符预算。      |
+| `maxNoteChars`         | `2000`                       | `zotero_get` 单条笔记预览的字符预算。  |
+| `maxNoteRecords`       | `50`                         | `zotero_get` 返回笔记数量的上限。      |
+| `maxAnnotationRecords` | `100`                        | `zotero_get` 返回批注数量的上限。      |
+| `fulltextChunkWords`   | `200`                        | 进入证据排序的全文片段词数。           |
+| `maxFulltextChars`     | `250000`                     | 进入证据排序的全文大小上限。           |
+| `maxResponseBytes`     | `16777216`                   | 每个 API 响应的流式字节上限。          |
+| `maxExportChars`       | `1000000`                    | 导出输出的硬上限。不会中途截断。       |
+| `defaultStyle`         | `apa`                        | 引用/参考文献使用的 CSL 样式。         |
+| `defaultLocale`        | `en-US`                      | 引用/参考文献使用的 CSL locale。       |
+
+## 开发
+
+### 命令
+
+```sh
+npm install                      # 使用本地 npm 缓存
+npm test                         # 单元测试（mock Zotero server）
+npm run test:coverage            # 对 src/ 的 100% 覆盖率门禁
+npm run typecheck                # tsc --noEmit，app + test 项目
+npm run build                    # 生成 lib/
+npm run format                   # prettier --write 全仓格式化
+npm run format:check             # 校验格式化（提交前执行）
+```
+
+集成测试面向真实 Zotero，默认跳过，需显式开启：
+
+```sh
+npm run test:integration
+# 或：ZOTERO_INTEGRATION=1 npx vitest run tests/integration/zotero.integration.spec.ts
+```
+
+### 本地启动
+
+#### 从 dsh 源码启动
+
+在 deepseek-harness 源码 checkout 中构建一次（`pnpm install && pnpm run build`），然后通过 dev overlay 加载插件源码：
+
+```sh
+pnpm dsh web --patch ./dsh-zotero/dev.cordis.yml
+```
+
+`dev.cordis.yml` 将插件入口指向绝对的 `src/index.ts`。dsh 的源码启动经 tsx 加载该 TypeScript 入口，插件因此无需预构建；若 checkout 路径不同，需同步修改文件中的绝对路径。
+
+#### 使用 npm 安装的 dsh
+
+**常驻实例**：打包为 tarball 并安装到 profile，插件以 tarball 中的副本运行；代码更新需重新打包安装。安装后运行生产栈 smoke 验证：
+
+```sh
+npm pack
+dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
+cd ~/.dsh/profiles/<name>
+node --input-type=module < /path/to/dsh-zotero/scripts/smoke.mjs
+```
+
+smoke 需在 profile 目录内运行，裸导入由此从 profile 的扁平 `node_modules` 解析。脚本依次验证 `status`、`search`、`get`、`retrieve`、`export`、策略提示词分区与五个工具注册；输出 `SMOKE PASS` 表示打包后的插件通过安装路径验证。
+
+**开发实例（热替换）**：`dev-lib.cordis.yml` 覆盖层禁用 profile 中的 tarball 副本（id `zotero`），插入 `zotero-dev` 指向本仓库的 `lib/index.js`，并重新启用 HMR。生产 web profile 默认禁用 loader HMR，且 HMR 的监视根位于 profile 目录，因此覆盖层显式设置了 `base`。构建输出变化后，HMR 在同一进程内销毁旧实例并重新构造插件，无需重启 dsh：
+
+```sh
+cd /Volumes/Work/deepseek-harness/dsh-zotero
+npm run dev &                    # tsc --watch：修改 src 后自动重建 lib
+dsh web --patch ./dev-lib.cordis.yml --port 3307
+```
+
+热替换仅作用于通过 `--patch` 启动的实例；常驻实例继续运行 tarball 版本。
+
+## 许可证
+
+本插件以 [MIT](./LICENSE) 许可证发布。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# This patch is used when the plugin is installed as a dsh bundle.
+# The `name` refers to the package name, so Node module resolution can find it.
+- insert:
+    - id: zotero
+      name: dsh-zotero
+      config: {}

package/lib/attachments.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Attachment records and deterministic attachment selection.
+ *
+ * Zotero's own best-attachment choice (`links.attachment` on item
+ * responses) is preferred wherever it exists; `selectAttachment` is the
+ * documented fallback that ranks child rows the same way Zotero's
+ * `getBestAttachment` does — PDF over other kinds, imported files first,
+ * then earliest addition date, then key order.
+ * @module dsh-zotero/attachments
+ */
+/**
+ * A normalized attachment child row, before ref provenance is attached.
+ * Ref-free on purpose: callers own the `?server=` qualifier.
+ */
+export interface ZoteroAttachmentCandidate {
+    readonly key: string;
+    readonly title: string;
+    readonly contentType: string;
+    readonly linkMode?: string;
+    /** `data.url`; meaningful for `linked_url` attachments. */
+    readonly url?: string;
+}
+/** Extract a Zotero object key from an API `links.attachment.href`. */
+export declare function extractAttachmentKey(href: string | undefined): string | undefined;
+/**
+ * Read Zotero's own best-attachment link from an item response.
+ * @returns the attachment key and content type, or undefined when the item
+ * has no attachment link (or its href carries no valid Zotero key).
+ */
+export declare function bestAttachmentFromLinks(json: unknown): {
+    key: string;
+    contentType: string;
+} | undefined;
+/**
+ * Normalize one attachment item JSON object.
+ * @throws {ZoteroError} `ZOTERO_UNEXPECTED` when the object has no valid Zotero key.
+ */
+export declare function normalizeAttachmentRecord(json: unknown): ZoteroAttachmentCandidate;
+/**
+ * Select one attachment of the requested kind from raw child rows, ranked
+ * deterministically: imported files first, then earliest `dateAdded`, then
+ * key order. Rows without an attachment content type are skipped; a
+ * malformed attachment row fails loud like every other broken invariant.
+ * @param rows - raw child item JSON objects (notes and annotations are skipped).
+ * @param kind - `pdf` selects `application/pdf`; anything else is matched as a literal content type.
+ * @returns the winning record, or undefined when no row matches the kind.
+ * @throws {ZoteroError} `ZOTERO_UNEXPECTED` on an attachment row without a valid key.
+ */
+export declare function selectAttachment(rows: readonly unknown[], kind: string): ZoteroAttachmentCandidate | undefined;
+//# sourceMappingURL=attachments.d.ts.map

package/lib/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,OAAO,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAKlD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,yBAAyB,CAmBlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,IAAI,EAAE,MAAM,GACX,yBAAyB,GAAG,SAAS,CAoBvC"}

package/lib/attachments.js

@@ -0,0 +1,95 @@
+/**
+ * Attachment records and deterministic attachment selection.
+ *
+ * Zotero's own best-attachment choice (`links.attachment` on item
+ * responses) is preferred wherever it exists; `selectAttachment` is the
+ * documented fallback that ranks child rows the same way Zotero's
+ * `getBestAttachment` does — PDF over other kinds, imported files first,
+ * then earliest addition date, then key order.
+ * @module dsh-zotero/attachments
+ */
+import { ZOTERO_UNEXPECTED, ZoteroError } from './errors.js';
+const OBJECT_KEY_PATTERN = /^[A-Z0-9]{8}$/;
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Extract a Zotero object key from an API `links.attachment.href`. */
+export function extractAttachmentKey(href) {
+    if (href === undefined)
+        return undefined;
+    return /\/items\/([A-Z0-9]{8})(?:[/?#]|$)/.exec(href)?.[1];
+}
+/**
+ * Read Zotero's own best-attachment link from an item response.
+ * @returns the attachment key and content type, or undefined when the item
+ * has no attachment link (or its href carries no valid Zotero key).
+ */
+export function bestAttachmentFromLinks(json) {
+    const attachment = asRecord(asRecord(asRecord(json)?.links)?.attachment);
+    const key = extractAttachmentKey(asString(attachment?.href));
+    if (key === undefined)
+        return undefined;
+    return { key, contentType: asString(attachment?.attachmentType) ?? '' };
+}
+/**
+ * Normalize one attachment item JSON object.
+ * @throws {ZoteroError} `ZOTERO_UNEXPECTED` when the object has no valid Zotero key.
+ */
+export function normalizeAttachmentRecord(json) {
+    const record = asRecord(json);
+    const key = asString(record?.key);
+    if (key === undefined || !OBJECT_KEY_PATTERN.test(key)) {
+        throw new ZoteroError('Zotero returned an attachment without a valid object key.', ZOTERO_UNEXPECTED);
+    }
+    const data = asRecord(record?.data);
+    const linkMode = asString(data?.linkMode);
+    const url = asString(data?.url);
+    return {
+        key,
+        title: asString(data?.title) ?? '',
+        contentType: asString(data?.contentType) ?? '',
+        ...(linkMode !== undefined ? { linkMode } : {}),
+        ...(url !== undefined ? { url } : {}),
+    };
+}
+/**
+ * Select one attachment of the requested kind from raw child rows, ranked
+ * deterministically: imported files first, then earliest `dateAdded`, then
+ * key order. Rows without an attachment content type are skipped; a
+ * malformed attachment row fails loud like every other broken invariant.
+ * @param rows - raw child item JSON objects (notes and annotations are skipped).
+ * @param kind - `pdf` selects `application/pdf`; anything else is matched as a literal content type.
+ * @returns the winning record, or undefined when no row matches the kind.
+ * @throws {ZoteroError} `ZOTERO_UNEXPECTED` on an attachment row without a valid key.
+ */
+export function selectAttachment(rows, kind) {
+    const wantedContentType = kind === 'pdf' ? 'application/pdf' : kind;
+    const scored = [];
+    for (const row of rows) {
+        const record = asRecord(row);
+        const data = asRecord(record?.data);
+        if (asString(data?.contentType) === undefined)
+            continue;
+        const candidate = normalizeAttachmentRecord(row);
+        if (candidate.contentType !== wantedContentType)
+            continue;
+        scored.push({ candidate, dateAdded: asString(data?.dateAdded) ?? '' });
+    }
+    scored.sort((a, b) => {
+        const rankA = a.candidate.linkMode === 'imported_file' ? 0 : 1;
+        const rankB = b.candidate.linkMode === 'imported_file' ? 0 : 1;
+        if (rankA !== rankB)
+            return rankA - rankB;
+        const byDate = a.dateAdded.localeCompare(b.dateAdded);
+        if (byDate !== 0)
+            return byDate;
+        return a.candidate.key.localeCompare(b.candidate.key);
+    });
+    return scored[0]?.candidate;
+}
+//# sourceMappingURL=attachments.js.map

package/lib/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE5D,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAE1C,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACtD,CAAC;AAeD,uEAAuE;AACvE,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxC,OAAO,mCAAmC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAa;IAEb,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,UAAU,CAAC,CAAA;IACxE,MAAM,GAAG,GAAG,oBAAoB,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAA;IAC5D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACvC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,IAAI,EAAE,EAAE,CAAA;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAa;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACjC,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,WAAW,CACnB,2DAA2D,EAC3D,iBAAiB,CAClB,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IAC/B,OAAO;QACL,GAAG;QACH,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;QAClC,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE;QAC9C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAwB,EACxB,IAAY;IAEZ,MAAM,iBAAiB,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAA;IACnE,MAAM,MAAM,GAAkE,EAAE,CAAA;IAChF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;QAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QACnC,IAAI,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,SAAS;YAAE,SAAQ;QACvD,MAAM,SAAS,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAA;QAChD,IAAI,SAAS,CAAC,WAAW,KAAK,iBAAiB;YAAE,SAAQ;QACzD,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACxE,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,QAAQ,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9D,MAAM,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,QAAQ,KAAK,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9D,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,KAAK,GAAG,KAAK,CAAA;QACzC,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACrD,IAAI,MAAM,KAAK,CAAC;YAAE,OAAO,MAAM,CAAA;QAC/B,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,CAAA;AAC7B,CAAC"}

package/lib/client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The Local API HTTP boundary: plain-loopback `fetch` with a pinned API
+ * version, instance-identity protection, a streaming response byte bound,
+ * and strict transport-error translation. Every request is request-driven —
+ * there is no keep-alive state, no background work, and no redirect
+ * following, so a loopback endpoint can never be taken elsewhere.
+ * @module dsh-zotero/client
+ */
+export interface ZoteroHttpClientOptions {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxResponseBytes: number;
+}
+export interface ZoteroHttpGetOptions {
+    /** Caller cancellation; an abort preserves harness cancellation semantics, never a timeout. */
+    readonly signal?: AbortSignal;
+    /** Override the remembered instance id for this request. */
+    readonly serverId?: string;
+    /** Send the remembered instance id (default true); false suppresses it for identity refreshes. */
+    readonly sendServerId?: boolean;
+}
+export interface ZoteroHttpResponse {
+    readonly body: string;
+    readonly headers: Headers;
+}
+export declare class ZoteroHttpClient {
+    private readonly options;
+    private currentServerId;
+    private readonly baseUrlWithSlash;
+    constructor(options: ZoteroHttpClientOptions);
+    /** The instance id remembered from the latest response carrying one (Zotero 10+). */
+    get serverId(): string | undefined;
+    /**
+     * GET a path relative to the API base (no leading slash; `''` is `/api/`).
+     * @param path - relative path, e.g. `users/0/items/ABCD1234`.
+     * @param search - query parameters, serialized verbatim.
+     */
+    get(path: string, search?: URLSearchParams, opts?: ZoteroHttpGetOptions): Promise<ZoteroHttpResponse>;
+    /** GET and parse a JSON response. */
+    getJson<T>(path: string, search?: URLSearchParams, opts?: ZoteroHttpGetOptions): Promise<{
+        json: T;
+        body: string;
+        headers: Headers;
+    }>;
+    private rememberServerId;
+    /** Re-read `/api/` without the remembered id so a stale id cannot 412 the refresh. */
+    private refreshIdentity;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAkFD,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;gBAEZ,OAAO,EAAE,uBAAuB;IAI7D,qFAAqF;IACrF,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;;;OAIG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,eAAe,EACxB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;IAwC9B,qCAAqC;IAC/B,OAAO,CAAC,CAAC,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,eAAe,EACxB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAavD,OAAO,CAAC,gBAAgB;IAKxB,sFAAsF;YACxE,eAAe;CAG9B"}