@beomsukoh/zotero-cli 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ Same architecture as [devonthink-cli](https://github.com/GoBeromsu/devonthink-cl
 ## Install
 
 ```bash
-npm install -g @goberomsu/zotero-cli
+npm install -g @beomsukoh/zotero-cli
 ```
 
 ## Quick Start
@@ -45,6 +45,16 @@ zt types
 
 # Show fields for a specific type
 zt types journalArticle
+
+# Import paper by DOI (requires Translation Server)
+docker run -p 1969:1969 zotero/translation-server
+zt import --doi "10.1145/3025453.3025912"
+
+# Import from URL
+zt import --url "https://arxiv.org/abs/2301.01234"
+
+# Import PDF: resolve DOI from filename, create item, attach PDF
+zt import ./10.1234_example.pdf
 ```
 
 ## Configuration
@@ -54,6 +64,7 @@ zt types journalArticle
 | `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) |
+| `ZOTERO_TRANSLATION_SERVER` | `http://localhost:1969` | Translation Server URL (for `import`) |
 
 **Local mode** (reads only, Zotero desktop must be running):
 ```bash
@@ -83,6 +94,7 @@ export ZOTERO_BASE_URL=https://api.zotero.org
 | `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 |
+| `zt import` | Import from DOI, ISBN, arXiv, URL, BibTeX, or PDF |
 
 ### Create
 
@@ -110,6 +122,7 @@ zt <command> [options]
     -> ZoteroPort (application boundary)
       -> HttpZoteroAdapter
         -> Zotero Local API (localhost:23119) or Web API (api.zotero.org)
+        -> Translation Server (localhost:1969) for import
 ```
 
 ## License

package/dist/adapters/http/HttpZoteroAdapter.js

@@ -7,11 +7,13 @@ export class HttpZoteroAdapter {
     baseUrl;
     apiKey;
     userId;
-    constructor(http, baseUrl, apiKey, userId) {
+    translationServerUrl;
+    constructor(http, baseUrl, apiKey, userId, translationServerUrl) {
         this.http = http;
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.apiKey = apiKey;
         this.userId = userId;
+        this.translationServerUrl = translationServerUrl ?? "http://localhost:1969";
     }
     // ── Query methods ──────────────────────────────────────────────
     async listItems(library, collectionKey, options) {
@@ -228,6 +230,37 @@ export class HttpZoteroAdapter {
         const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/file`);
         return url;
     }
+    // ── Translation Server methods ────────────────────────────────
+    async resolveIdentifier(identifier) {
+        const url = `${this.translationServerUrl}/search`;
+        const response = await this.http.request("POST", url, {
+            headers: { "Content-Type": "text/plain" },
+            body: identifier,
+        });
+        if (response.status === 501) {
+            throw new ExternalToolError("No translator available for this identifier.");
+        }
+        return this.parseResponse(response);
+    }
+    async scrapeUrl(url) {
+        const tsUrl = `${this.translationServerUrl}/web`;
+        const response = await this.http.request("POST", tsUrl, {
+            headers: { "Content-Type": "text/plain" },
+            body: url,
+        });
+        if (response.status === 501) {
+            throw new ExternalToolError("No translator available for this URL.");
+        }
+        return this.parseResponse(response);
+    }
+    async importBibliography(text) {
+        const url = `${this.translationServerUrl}/import`;
+        const response = await this.http.request("POST", url, {
+            headers: { "Content-Type": "text/plain" },
+            body: text,
+        });
+        return this.parseResponse(response);
+    }
     // ── Helpers ────────────────────────────────────────────────────
     libraryPrefix(library) {
         return `/${library.type === "group" ? "groups" : "users"}/${library.id}`;

package/dist/commands/importCommand.js

@@ -0,0 +1,127 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { ValidationError, NotFoundError } from "../application/errors.js";
+import { assertNoMissingOptionValues, assertNoUnknownOptions, getOption, parseArgs, } from "../utils/args.js";
+import { renderJson, resolveLibrary } from "./helpers.js";
+export class ImportCommand {
+    name = "import";
+    category = "Core";
+    description = "Import items from DOI, ISBN, arXiv ID, URL, or BibTeX.";
+    help() {
+        return [
+            "Usage:",
+            '  zt import --doi "10.1234/example"',
+            '  zt import --isbn "978-0-123456-78-9"',
+            '  zt import --arxiv "2301.01234"',
+            '  zt import --url "https://arxiv.org/abs/2301.01234"',
+            "  zt import --bibtex ./references.bib",
+            "  zt import ./paper.pdf",
+            '  zt import ./paper.pdf --doi "10.1234/example"',
+            "",
+            "Import bibliographic metadata via the Zotero Translation Server",
+            "and create items in Zotero. Optionally attach a PDF.",
+            "",
+            "Options:",
+            "  --doi <doi>            DOI to resolve",
+            "  --isbn <isbn>          ISBN to resolve",
+            "  --arxiv <id>           arXiv ID to resolve",
+            "  --url <url>            URL to scrape",
+            "  --bibtex <file>        BibTeX file to import",
+            "  --collection <key>     Add to collection after import",
+            "  --group <id>           Library group ID",
+            "",
+            "Positional:",
+            "  <file>                 PDF file to attach after creating item",
+            "",
+            "Examples:",
+            '  zt import --doi "10.1038/s41586-021-03819-2"',
+            '  zt import --arxiv "2301.01234" --collection ABC12345',
+            "  zt import ./paper.pdf --doi 10.1234/example",
+            "  zt import --bibtex refs.bib --group 123456",
+        ].join("\n");
+    }
+    parse(argv, context) {
+        const parsed = parseArgs(argv);
+        assertNoUnknownOptions(parsed, [
+            "doi", "isbn", "arxiv", "url", "bibtex", "collection", "group",
+        ]);
+        assertNoMissingOptionValues(parsed, [
+            "doi", "isbn", "arxiv", "url", "bibtex", "collection", "group",
+        ]);
+        const library = resolveLibrary(parsed, context?.config ?? { baseUrl: "" });
+        const doi = getOption(parsed, "doi");
+        const isbn = getOption(parsed, "isbn");
+        const arxiv = getOption(parsed, "arxiv");
+        const url = getOption(parsed, "url");
+        const bibtexFile = getOption(parsed, "bibtex");
+        const collection = getOption(parsed, "collection");
+        const filePath = parsed.positionals[0];
+        if (parsed.positionals.length > 1) {
+            throw new ValidationError("import accepts at most one positional argument (file path).");
+        }
+        return { library, doi, isbn, arxiv, url, bibtexFile, collection, filePath };
+    }
+    async execute(input, context) {
+        const library = input.library;
+        let metadata;
+        // Step 1: Resolve metadata
+        if (input.doi) {
+            metadata = await context.zotero.resolveIdentifier(input.doi);
+        }
+        else if (input.isbn) {
+            metadata = await context.zotero.resolveIdentifier(input.isbn);
+        }
+        else if (input.arxiv) {
+            metadata = await context.zotero.resolveIdentifier(`arXiv:${input.arxiv}`);
+        }
+        else if (input.url) {
+            metadata = await context.zotero.scrapeUrl(input.url);
+        }
+        else if (input.bibtexFile) {
+            const content = await readFile(input.bibtexFile, "utf8");
+            metadata = await context.zotero.importBibliography(content);
+        }
+        else if (input.filePath) {
+            // Try to extract DOI from filename (pattern: 10.xxxx/yyyy)
+            const doiMatch = basename(input.filePath).match(/10\.\d{4,}[^\s]*/);
+            if (doiMatch) {
+                metadata = await context.zotero.resolveIdentifier(doiMatch[0]);
+            }
+            else {
+                throw new ValidationError("Cannot determine metadata source. Provide --doi, --url, --isbn, or --arxiv.");
+            }
+        }
+        else {
+            throw new ValidationError("import requires --doi, --url, --isbn, --arxiv, --bibtex, or a file path.");
+        }
+        // Step 2: Create the item
+        // Translation server returns array of items or single item
+        const items = Array.isArray(metadata) ? metadata : [metadata];
+        if (items.length === 0) {
+            throw new NotFoundError("No items found for the given identifier.");
+        }
+        // Add to collection if specified
+        if (input.collection) {
+            for (const item of items) {
+                if (typeof item === "object" && item !== null) {
+                    item["collections"] = [input.collection];
+                }
+            }
+        }
+        const created = await context.zotero.createItem(library, items);
+        // Step 3: Attach PDF if file path provided
+        if (input.filePath && input.filePath.endsWith(".pdf")) {
+            const createdData = created;
+            const successful = (createdData?.["successful"] ?? createdData?.["success"]);
+            if (successful) {
+                const firstKey = Object.values(successful)[0];
+                const itemKey = firstKey?.["key"] ??
+                    firstKey?.["data"]?.["key"];
+                if (itemKey) {
+                    await context.zotero.uploadAttachment(library, itemKey, input.filePath, "application/pdf");
+                }
+            }
+        }
+        context.output.write(renderJson(created));
+    }
+}

package/dist/compositionRoot.js

@@ -16,14 +16,16 @@ import { ExportCommand } from "./commands/exportCommand.js";
 import { FulltextCommand } from "./commands/fulltextCommand.js";
 import { TemplateCommand } from "./commands/templateCommand.js";
 import { TypesInfoCommand } from "./commands/typesInfoCommand.js";
+import { ImportCommand } from "./commands/importCommand.js";
 export function createRuntime() {
     const config = {
         apiKey: process.env["ZOTERO_API_KEY"],
         userId: process.env["ZOTERO_USER_ID"] ?? "0",
-        baseUrl: process.env["ZOTERO_BASE_URL"] ?? "http://localhost:23119/api"
+        baseUrl: process.env["ZOTERO_BASE_URL"] ?? "http://localhost:23119/api",
+        translationServerUrl: process.env["ZOTERO_TRANSLATION_SERVER"] ?? "http://localhost:1969",
     };
     const http = new NodeHttpClient();
-    const zotero = new HttpZoteroAdapter(http, config.baseUrl, config.apiKey, config.userId);
+    const zotero = new HttpZoteroAdapter(http, config.baseUrl, config.apiKey, config.userId, config.translationServerUrl);
     const output = new ConsoleOutputAdapter();
     const registry = new CommandRegistry();
     registry.register(new LibrariesCommand());
@@ -40,5 +42,6 @@ export function createRuntime() {
     registry.register(new FulltextCommand());
     registry.register(new TemplateCommand());
     registry.register(new TypesInfoCommand());
+    registry.register(new ImportCommand());
     return { output, zotero, registry, config };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beomsukoh/zotero-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pure CLI wrapper for the Zotero API.",
   "type": "module",
   "bin": {