@beomsukoh/zotero-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beomsu Koh
+
+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.md

@@ -0,0 +1,117 @@
+# zotero-cli
+
+Pure CLI wrapper for the Zotero API. Supports both the local desktop API (read-only, no auth) and the web API (full CRUD with API key).
+
+Same architecture as [devonthink-cli](https://github.com/GoBeromsu/devonthink-cli): CommandModule pattern, port/adapter, typed error hierarchy. Zero runtime dependencies.
+
+## Install
+
+```bash
+npm install -g @goberomsu/zotero-cli
+```
+
+## Quick Start
+
+```bash
+# List items (local Zotero API, no auth needed)
+zt items --limit 10
+
+# Search
+zt search "machine learning"
+
+# Get a specific item
+zt get ABCD1234
+
+# List collections
+zt collections
+
+# Export as BibTeX
+zt export --format bibtex
+
+# Get item template for creating a journal article
+zt template journalArticle
+
+# Create an item
+zt create:item --type journalArticle --title "My Paper" --doi "10.1234/example"
+
+# Attach a PDF to an item
+zt attach ./paper.pdf --key ABCD1234
+
+# Get full-text content
+zt fulltext ABCD1234
+
+# Show available item types
+zt types
+
+# Show fields for a specific type
+zt types journalArticle
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `ZOTERO_BASE_URL` | `http://localhost:23119/api` | API base URL |
+| `ZOTERO_API_KEY` | — | API key (required for writes) |
+| `ZOTERO_USER_ID` | `0` | User ID (`0` = local API) |
+
+**Local mode** (reads only, Zotero desktop must be running):
+```bash
+zt items --limit 10
+```
+
+**Web mode** (full CRUD):
+```bash
+export ZOTERO_API_KEY=your_key_here
+export ZOTERO_USER_ID=12345
+export ZOTERO_BASE_URL=https://api.zotero.org
+```
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---|---|
+| `zt items` | List items (`--collection`, `--top`, `--tag`, `--type`, `--limit`, `--sort`) |
+| `zt collections` | List collections (`--parent`) |
+| `zt get <key>` | Get item by key (`--children` for child items) |
+| `zt search <query>` | Search items (`--qmode`, `--tag`, `--type`) |
+| `zt tags` | List tags |
+| `zt libraries` | List group libraries |
+| `zt delete --key <key>` | Delete item or collection (`--collection` flag) |
+| `zt attach <file> --key <key>` | Attach file to item (`--content-type`) |
+| `zt export --format <fmt>` | Export items (bibtex, ris, csljson, csv, tei, etc.) |
+| `zt fulltext <key>` | Get full-text content |
+
+### Create
+
+| Command | Description |
+|---|---|
+| `zt create:item` | Create item from JSON or `--type`/`--title`/`--doi` options |
+| `zt create:collection <name>` | Create collection (`--parent` for nesting) |
+
+### Lookup
+
+| Command | Description |
+|---|---|
+| `zt types [itemType]` | List item types, or fields for a specific type |
+| `zt template <itemType>` | Get JSON template for creating items |
+
+### Export Formats
+
+`bibtex`, `biblatex`, `ris`, `csljson`, `csv`, `tei`, `wikipedia`, `mods`, `refer`
+
+## Architecture
+
+```
+zt <command> [options]
+  -> CommandRegistry -> CommandModule.parse() -> CommandModule.execute()
+    -> ZoteroPort (application boundary)
+      -> HttpZoteroAdapter
+        -> Zotero Local API (localhost:23119) or Web API (api.zotero.org)
+```
+
+## License
+
+MIT

package/dist/adapters/http/HttpZoteroAdapter.js

@@ -0,0 +1,332 @@
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { NotFoundError, ConflictError, ExternalToolError, } from "../../application/errors.js";
+export class HttpZoteroAdapter {
+    http;
+    baseUrl;
+    apiKey;
+    userId;
+    constructor(http, baseUrl, apiKey, userId) {
+        this.http = http;
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.userId = userId;
+    }
+    // ── Query methods ──────────────────────────────────────────────
+    async listItems(library, collectionKey, options) {
+        const path = collectionKey
+            ? `${this.libraryPrefix(library)}/collections/${collectionKey}/items`
+            : `${this.libraryPrefix(library)}/items`;
+        const url = this.buildUrl(path, this.searchParams(options));
+        return this.get(url);
+    }
+    async listTopItems(library, collectionKey, options) {
+        const path = collectionKey
+            ? `${this.libraryPrefix(library)}/collections/${collectionKey}/items/top`
+            : `${this.libraryPrefix(library)}/items/top`;
+        const url = this.buildUrl(path, this.searchParams(options));
+        return this.get(url);
+    }
+    async getItem(library, itemKey) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}`);
+        return this.get(url);
+    }
+    async getItemChildren(library, itemKey, options) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/children`, this.listParams(options));
+        return this.get(url);
+    }
+    async listCollections(library, parentKey, options) {
+        const path = parentKey
+            ? `${this.libraryPrefix(library)}/collections/${parentKey}/collections`
+            : `${this.libraryPrefix(library)}/collections`;
+        const url = this.buildUrl(path, this.listParams(options));
+        return this.get(url);
+    }
+    async getCollection(library, collectionKey) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/collections/${collectionKey}`);
+        return this.get(url);
+    }
+    async listTags(library, options) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/tags`, this.listParams(options));
+        return this.get(url);
+    }
+    async listLibraries() {
+        const id = this.userId ?? "0";
+        const url = this.buildUrl(`/users/${id}/groups`);
+        return this.get(url);
+    }
+    async searchItems(library, query, options) {
+        const params = this.searchParams(options);
+        params.set("q", query);
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items`, params);
+        return this.get(url);
+    }
+    // ── Mutation methods ───────────────────────────────────────────
+    async createItem(library, data) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items`);
+        return this.post(url, data);
+    }
+    async updateItem(library, itemKey, data, version) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}`);
+        return this.patch(url, data, version);
+    }
+    async deleteItem(library, itemKey, version) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}`);
+        const response = await this.http.request("DELETE", url, {
+            headers: this.headers({ "If-Unmodified-Since-Version": String(version) }),
+        });
+        return this.parseResponse(response);
+    }
+    async createCollection(library, data) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/collections`);
+        return this.post(url, data);
+    }
+    async deleteCollection(library, collectionKey, version) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/collections/${collectionKey}`);
+        const response = await this.http.request("DELETE", url, {
+            headers: this.headers({ "If-Unmodified-Since-Version": String(version) }),
+        });
+        return this.parseResponse(response);
+    }
+    async addToCollection(library, itemKey, collectionKey) {
+        const item = (await this.getItem(library, itemKey));
+        const data = item["data"];
+        const version = item["version"] ?? 0;
+        const collections = Array.isArray(data?.["collections"])
+            ? [...data["collections"]]
+            : [];
+        if (!collections.includes(collectionKey)) {
+            collections.push(collectionKey);
+        }
+        return this.updateItem(library, itemKey, { collections }, version);
+    }
+    async removeFromCollection(library, itemKey, collectionKey) {
+        const item = (await this.getItem(library, itemKey));
+        const data = item["data"];
+        const version = item["version"] ?? 0;
+        const collections = Array.isArray(data?.["collections"])
+            ? data["collections"].filter((k) => k !== collectionKey)
+            : [];
+        return this.updateItem(library, itemKey, { collections }, version);
+    }
+    // ── Schema/template methods (global, not library-scoped) ─────
+    async getItemTypes() {
+        const url = "https://api.zotero.org/itemTypes";
+        return this.get(url);
+    }
+    async getItemTemplate(itemType) {
+        const url = `https://api.zotero.org/items/new?itemType=${encodeURIComponent(itemType)}`;
+        return this.get(url);
+    }
+    async getItemTypeFields(itemType) {
+        const url = `https://api.zotero.org/itemTypeFields?itemType=${encodeURIComponent(itemType)}`;
+        return this.get(url);
+    }
+    async getItemTypeCreatorTypes(itemType) {
+        const url = `https://api.zotero.org/itemTypeCreatorTypes?itemType=${encodeURIComponent(itemType)}`;
+        return this.get(url);
+    }
+    // ── Full-text ───────────────────────────────────────────────────
+    async getFullText(library, itemKey) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/fulltext`);
+        return this.get(url);
+    }
+    // ── Export ──────────────────────────────────────────────────────
+    async exportItems(library, format, options) {
+        const params = this.searchParams(options);
+        params.set("format", format);
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items`, params);
+        const response = await this.http.request("GET", url, {
+            headers: this.headers(),
+        });
+        if (response.status >= 400) {
+            throw new ExternalToolError(`Zotero API error (${response.status}): ${response.body || "unknown error"}`);
+        }
+        return response.body;
+    }
+    // ── File operations ────────────────────────────────────────────
+    async uploadAttachment(library, parentItemKey, filePath, contentType) {
+        // 1. Get the attachment template
+        const template = (await this.getItemTemplate("attachment&linkMode=imported_file"));
+        // 2. Create the attachment item
+        const fileName = basename(filePath);
+        const attachmentData = {
+            ...template,
+            parentItem: parentItemKey,
+            title: fileName,
+            contentType,
+        };
+        const createUrl = this.buildUrl(`${this.libraryPrefix(library)}/items`);
+        const createResponse = await this.http.request("POST", createUrl, {
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify([attachmentData]),
+        });
+        const createResult = await this.parseResponse(createResponse);
+        const successful = createResult?.["successful"];
+        const created = successful?.["0"];
+        const attachmentKey = created?.["key"] ??
+            created?.["data"]?.["key"];
+        if (!attachmentKey) {
+            throw new ExternalToolError(`Failed to create attachment item: ${JSON.stringify(createResult)}`);
+        }
+        // 3. Read the file, compute md5 and size
+        const fileBuffer = await readFile(filePath);
+        const md5 = createHash("md5").update(fileBuffer).digest("hex");
+        const fileSize = fileBuffer.length;
+        const mtime = Date.now();
+        // 4. Get upload authorization
+        const authUrl = this.buildUrl(`${this.libraryPrefix(library)}/items/${attachmentKey}/file`);
+        const authBody = new URLSearchParams({
+            md5,
+            filename: fileName,
+            filesize: String(fileSize),
+            mtime: String(mtime),
+        }).toString();
+        const authResponse = await this.http.request("POST", authUrl, {
+            headers: this.headers({
+                "Content-Type": "application/x-www-form-urlencoded",
+                "If-None-Match": "*",
+            }),
+            body: authBody,
+        });
+        const authResult = (await this.parseResponse(authResponse));
+        // 5. If file already exists on server, we're done
+        if (authResult["exists"] === 1) {
+            return { exists: true, key: attachmentKey };
+        }
+        // 6. Upload the file to the storage service
+        const uploadUrl = authResult["url"];
+        const prefix = authResult["prefix"] ?? "";
+        const suffix = authResult["suffix"] ?? "";
+        const uploadContentType = authResult["contentType"];
+        const uploadKey = authResult["uploadKey"];
+        // Build the upload body: prefix + file content + suffix
+        const prefixBuf = Buffer.from(prefix, "utf-8");
+        const suffixBuf = Buffer.from(suffix, "utf-8");
+        const uploadBody = Buffer.concat([prefixBuf, fileBuffer, suffixBuf]);
+        const uploadResponse = await this.http.request("POST", uploadUrl, {
+            headers: { "Content-Type": uploadContentType },
+            body: uploadBody.toString("binary"),
+        });
+        if (uploadResponse.status >= 400) {
+            throw new ExternalToolError(`File upload failed (${uploadResponse.status}): ${uploadResponse.body || "unknown error"}`);
+        }
+        // 7. Register the upload
+        const registerBody = new URLSearchParams({ upload: uploadKey }).toString();
+        const registerResponse = await this.http.request("POST", authUrl, {
+            headers: this.headers({
+                "Content-Type": "application/x-www-form-urlencoded",
+                "If-None-Match": "*",
+            }),
+            body: registerBody,
+        });
+        await this.parseResponse(registerResponse);
+        return { success: true, key: attachmentKey };
+    }
+    async getFileUrl(library, itemKey) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/file`);
+        return url;
+    }
+    // ── Helpers ────────────────────────────────────────────────────
+    libraryPrefix(library) {
+        return `/${library.type === "group" ? "groups" : "users"}/${library.id}`;
+    }
+    buildUrl(path, params) {
+        const base = `${this.baseUrl}${path}`;
+        if (params && Array.from(params).length > 0) {
+            return `${base}?${params.toString()}`;
+        }
+        return base;
+    }
+    headers(extra) {
+        const h = {
+            "Zotero-API-Version": "3",
+            ...extra,
+        };
+        if (this.apiKey) {
+            h["Zotero-API-Key"] = this.apiKey;
+        }
+        return h;
+    }
+    async parseResponse(response) {
+        if (response.status === 204) {
+            return null;
+        }
+        if (response.status === 404) {
+            throw new NotFoundError(`Resource not found: ${response.body || "unknown"}`);
+        }
+        if (response.status === 409 || response.status === 412) {
+            throw new ConflictError(`Conflict: ${response.body || "resource version mismatch"}`);
+        }
+        if (response.status >= 400) {
+            throw new ExternalToolError(`Zotero API error (${response.status}): ${response.body || "unknown error"}`);
+        }
+        if (!response.body) {
+            return null;
+        }
+        try {
+            return JSON.parse(response.body);
+        }
+        catch {
+            throw new ExternalToolError(`Failed to parse Zotero API response: ${response.body.slice(0, 200)}`);
+        }
+    }
+    listParams(options) {
+        const params = new URLSearchParams();
+        if (!options)
+            return params;
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.start !== undefined)
+            params.set("start", String(options.start));
+        if (options.sort)
+            params.set("sort", options.sort);
+        if (options.direction)
+            params.set("direction", options.direction);
+        if (options.format)
+            params.set("format", options.format);
+        return params;
+    }
+    searchParams(options) {
+        const params = this.listParams(options);
+        if (!options)
+            return params;
+        if (options.query)
+            params.set("q", options.query);
+        if (options.qmode)
+            params.set("qmode", options.qmode);
+        if (options.tag) {
+            for (const t of options.tag) {
+                params.append("tag", t);
+            }
+        }
+        if (options.itemType)
+            params.set("itemType", options.itemType);
+        return params;
+    }
+    // ── HTTP verb shortcuts ────────────────────────────────────────
+    async get(url) {
+        const response = await this.http.request("GET", url, {
+            headers: this.headers(),
+        });
+        return this.parseResponse(response);
+    }
+    async post(url, data) {
+        const response = await this.http.request("POST", url, {
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(data),
+        });
+        return this.parseResponse(response);
+    }
+    async patch(url, data, version) {
+        const response = await this.http.request("PATCH", url, {
+            headers: this.headers({
+                "Content-Type": "application/json",
+                "If-Unmodified-Since-Version": String(version),
+            }),
+            body: JSON.stringify(data),
+        });
+        return this.parseResponse(response);
+    }
+}

package/dist/adapters/output/ConsoleOutputAdapter.js

@@ -0,0 +1,8 @@
+export class ConsoleOutputAdapter {
+    write(message) {
+        process.stdout.write(`${message}\n`);
+    }
+    writeError(message) {
+        process.stderr.write(`${message}\n`);
+    }
+}

package/dist/application/errors.js

@@ -0,0 +1,42 @@
+export class AppError extends Error {
+    code;
+    exitCode;
+    constructor(message, code, exitCode) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}
+export class ValidationError extends AppError {
+    constructor(message) {
+        super(message, "VALIDATION_ERROR", 2);
+    }
+}
+export class NotFoundError extends AppError {
+    constructor(message) {
+        super(message, "NOT_FOUND", 3);
+    }
+}
+export class ConflictError extends AppError {
+    constructor(message) {
+        super(message, "CONFLICT", 4);
+    }
+}
+export class ExternalToolError extends AppError {
+    constructor(message) {
+        super(message, "EXTERNAL_TOOL_ERROR", 5);
+    }
+}
+export function toExitCode(error) {
+    if (error instanceof AppError) {
+        return error.exitCode;
+    }
+    return 1;
+}
+export function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/application/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/application/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { createRuntime } from "./compositionRoot.js";
+import { toErrorMessage, toExitCode } from "./application/errors.js";
+export async function runCli(argv) {
+    const runtime = createRuntime();
+    await runtime.registry.run(argv, runtime);
+}
+runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${toErrorMessage(error)}\n`);
+    process.exit(toExitCode(error));
+});

package/dist/commands/CommandRegistry.js

@@ -0,0 +1,44 @@
+import { ValidationError } from "../application/errors.js";
+const CATEGORY_ORDER = ["Core", "Property", "Create", "Lookup", "Other"];
+export class CommandRegistry {
+    commands = new Map();
+    register(command) {
+        this.commands.set(command.name, command);
+    }
+    help() {
+        const lines = ["Usage: zt <command> [options]", ""];
+        const byCategory = new Map();
+        for (const command of this.commands.values()) {
+            const list = byCategory.get(command.category) ?? [];
+            list.push(command);
+            byCategory.set(command.category, list);
+        }
+        for (const category of CATEGORY_ORDER) {
+            const commands = byCategory.get(category);
+            if (!commands || commands.length === 0)
+                continue;
+            lines.push(`${category}:`);
+            for (const command of commands.sort((a, b) => a.name.localeCompare(b.name))) {
+                lines.push(`  ${command.name.padEnd(24)} ${command.description}`);
+            }
+            lines.push("");
+        }
+        return lines.join("\n").trimEnd();
+    }
+    async run(argv, context) {
+        const [commandName, ...rest] = argv;
+        if (!commandName || commandName === "help" || commandName === "--help") {
+            context.output.write(this.help());
+            return;
+        }
+        const command = this.commands.get(commandName);
+        if (!command)
+            throw new ValidationError(`Unknown command: ${commandName}`);
+        if (rest.includes("--help")) {
+            context.output.write(command.help(context));
+            return;
+        }
+        const input = command.parse(rest, context);
+        await command.execute(input, context);
+    }
+}

package/dist/commands/attachCommand.js

@@ -0,0 +1,49 @@
+import { ValidationError } from "../application/errors.js";
+import { assertNoMissingOptionValues, assertNoUnknownOptions, getOption, parseArgs } from "../utils/args.js";
+import { renderJson, resolveLibrary } from "./helpers.js";
+export class AttachCommand {
+    name = "attach";
+    category = "Core";
+    description = "Attach a file to an existing item.";
+    help() {
+        return [
+            "Usage:",
+            "  zt attach <file-path> --key <parentItemKey>",
+            "",
+            "Upload and attach a file to an existing Zotero item.",
+            "",
+            "Options:",
+            "  --key <parentItemKey>  Parent item key (required)",
+            "  --group <id>           Library group ID",
+            "  --content-type <mime>  MIME type (default: application/pdf)",
+            "",
+            "Examples:",
+            '  zt attach paper.pdf --key ABC12345',
+            '  zt attach image.png --key ABC12345 --content-type image/png',
+            '  zt attach paper.pdf --key ABC12345 --group 123456'
+        ].join("\n");
+    }
+    parse(argv, context) {
+        const parsed = parseArgs(argv);
+        assertNoUnknownOptions(parsed, ["key", "group", "content-type"]);
+        assertNoMissingOptionValues(parsed, ["key", "group", "content-type"]);
+        const library = resolveLibrary(parsed, context?.config ?? { baseUrl: "" });
+        const key = getOption(parsed, "key");
+        const filePath = parsed.positionals[0];
+        const contentType = getOption(parsed, "content-type") ?? "application/pdf";
+        if (!filePath) {
+            throw new ValidationError("attach requires a file path. Usage: zt attach <file-path> --key <parentItemKey>");
+        }
+        if (parsed.positionals.length > 1) {
+            throw new ValidationError("attach accepts at most one positional argument (file path).");
+        }
+        if (!key) {
+            throw new ValidationError("attach requires --key <parentItemKey>.");
+        }
+        return { library, key, filePath, contentType };
+    }
+    async execute(input, context) {
+        const result = await context.zotero.uploadAttachment(input.library, input.key, input.filePath, input.contentType);
+        context.output.write(renderJson(result));
+    }
+}