paper-manager 0.11.2 → 0.12.1

package/README.md

@@ -8,10 +8,11 @@ A CLI tool for managing academic papers with knowledge base and vector search su
 ## Features
 
 - **Semantic search** — FAISS vector indexing with configurable embedding models, query your papers by meaning rather than keywords
+- **Add papers by DOI** — automatically download Open Access PDFs via [Unpaywall API](https://unpaywall.org/products/api) with `--doi` ([integration guide](paper-cli/unpaywall.md))
 - **PDF metadata extraction** — automatically extracts title, author, keywords, DOI, and more from PDF files
 - **DOI deduplication** — detects duplicate papers by DOI before adding, with `--force` override
 - **Multi-format support** — import from PDF, TXT, MD, TEX, and other text-based formats
-- **PDF-to-Markdown conversion** — optional high-quality conversion via [opendataloader-pdf](https://github.com/nicobailon/opendataloader-pdf) with image extraction
+- **PDF-to-Markdown conversion** — optional high-quality conversion via [opendataloader-pdf](https://github.com/opendataloader-project/opendataloader-pdf) with image extraction ([integration guide](paper-cli/opendataloader-pdf.md))
 - **Dual-scope data model** — user-level (`~/.paper-manager/`) for global collections and project-level (`./.paper-manager/`) for project-specific papers, with automatic scope resolution
 - **DOI-to-BibTeX** — convert DOI to BibTeX citation in one command
 - **Machine-readable output** — `--json` and `--jq` flags on all read commands for scripting and automation
@@ -49,6 +50,10 @@ paper kb create my-papers -d "My research papers"
 # Add a paper (supports PDF, TXT, MD, TEX, etc.)
 paper lit add <knowledge-base-id> ./paper.pdf
 
+# Or add an Open Access paper by DOI
+paper config set email '"you@example.com"' --user  # one-time setup for Unpaywall API
+paper lit add <knowledge-base-id> --doi 10.1038/nature12373
+
 # Search across papers
 paper kb query <knowledge-base-id> "attention mechanism"
 ```
@@ -78,7 +83,8 @@ paper kb query <id> <query-text> [--json] [--jq <expr>]  # Query a knowledge bas
 ### Literature (`paper lit`)
 
 ```bash
-paper lit add <kb-id> <file-path> [-f] # Add a literature (auto-extracts PDF metadata, rejects duplicate DOI)
+paper lit add <kb-id> <file-path> [-f] # Add a literature from file (auto-extracts PDF metadata)
+paper lit add <kb-id> --doi <doi> [-f] # Add an Open Access paper by DOI via Unpaywall
 paper lit remove <kb-id> <id>         # Remove a literature
 paper lit update <kb-id> <id> [opts]  # Update literature metadata
 paper lit list <kb-id> [--json] [--jq <expr>]       # List literatures
@@ -96,6 +102,72 @@ paper util doi2bib <doi>             # Convert a DOI to BibTeX citation
 paper util pdf-meta <file> [--json] [--jq <expr>]  # Extract metadata from a PDF file
 ```
 
+## Usage Scenarios
+
+### Building a paper collection for a research project
+
+```bash
+# Initialize a project-scoped data directory (version-controllable)
+paper config init
+
+# Create a knowledge base for your topic
+paper kb create "llm-agents" -d "Papers on LLM-based autonomous agents"
+# Output: Knowledge base created: 9f3a...
+
+# Add papers — by file or by DOI
+paper lit add 9f3a ./downloaded-paper.pdf
+paper lit add 9f3a --doi 10.48550/arXiv.2305.10601
+
+# Ask questions across all your papers
+paper kb query 9f3a "how do agents handle long-term memory?"
+```
+
+### Quick-adding Open Access papers you find online
+
+```bash
+# Spot a DOI in a reference list? One command to ingest it.
+paper lit add <kb-id> --doi 10.1038/nature12373
+
+# Unpaywall checks OA status, downloads the PDF, extracts metadata,
+# and builds a vector index — all in one step.
+# If the paper is not OA, you'll get a clear error with instructions.
+```
+
+### Generating BibTeX citations for your bibliography
+
+```bash
+paper util doi2bib 10.1145/3586183.3606763
+# @inproceedings{...}
+
+# Combine with jq to batch-extract DOIs from your knowledge base
+paper lit list <kb-id> --jq '.[].doi | select(. != null)'
+```
+
+### Scripting with JSON output
+
+```bash
+# Export all papers in a knowledge base as JSON
+paper lit list <kb-id> --json > papers.json
+
+# Filter with jq expressions inline
+paper lit list <kb-id> --jq '[.[] | {title, doi, author}]'
+
+# Find papers by a specific author
+paper lit search <kb-id> -a "Vaswani" --json
+```
+
+### Annotating papers for a literature review
+
+```bash
+# Attach notes to track your reading progress
+paper lit note set <lit-id> status "read"
+paper lit note set <lit-id> relevance "high"
+paper lit note set <lit-id> summary "Proposes transformer architecture..."
+
+# Review all notes
+paper lit note list <lit-id>
+```
+
 ## Configuration
 
 See [Configuration Reference](docs/configuration.md) for all available config fields and detailed usage.

package/config.schema.json

@@ -47,6 +47,11 @@
     "defaultEmbeddingModelId": {
       "type": "string",
       "minLength": 1
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
     }
   },
   "required": ["embeddingModels"],

package/dist/commands/literature.js

@@ -1,17 +1,20 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import chalk from "chalk";
 import cliProgress from "cli-progress";
 import { Command } from "commander";
-import { getFilesDir, getModelConfig, getProjectDataDir, getUserDataDir, getVectorStoreDir, } from "../config/index.js";
+import { getConfig, getFilesDir, getModelConfig, getProjectDataDir, getUserDataDir, getVectorStoreDir, } from "../config/index.js";
 import * as projectKb from "../db/project/knowledge-bases.js";
 import * as projectLit from "../db/project/literatures.js";
 import * as userKb from "../db/user/knowledge-bases.js";
 import * as userLit from "../db/user/literatures.js";
+import { isHybridBackendAvailable } from "../dep/index.js";
 import { extractContent, extractPdfMetadata } from "../extractor/index.js";
 import { convertPdfToMarkdown, isOpendataLoaderAvailable, removeImageDir, saveConvertResult, } from "../extractor/markdown.js";
 import { log } from "../logger.js";
 import { splitDocuments } from "../text-splitter.js";
+import { downloadPdf, lookupDoi, normalizeDoi, UnpaywallError } from "../unpaywall/index.js";
 import { addDocuments, createVectorStore } from "../vector-store/index.js";
 import { outputJson } from "./output.js";
 function resolveKnowledgeBase(id) {
@@ -33,11 +36,21 @@ export function createLiteratureCommand() {
     const lit = new Command("lit").description("Manage literatures");
     // ─── lit add ───────────────────────────────────────────────
     lit
-        .command("add <knowledge-base-id> <lit-path>")
-        .description("Add a literature from a file (PDF, TXT, MD, TEX, etc.)")
+        .command("add <knowledge-base-id> [lit-path]")
+        .description("Add a literature from a file (PDF, TXT, MD, TEX, etc.) or by DOI via Unpaywall")
         .option("-t, --title <title>", "Literature title")
         .option("-f, --force", "Force add even if a literature with the same DOI already exists")
+        .option("-d, --doi <doi>", "Add paper by DOI (downloads Open Access PDF via Unpaywall)")
         .action(async (kbId, litPath, options) => {
+        // Mutual exclusivity check
+        if (litPath && options.doi) {
+            log.error("Cannot specify both <lit-path> and --doi. Use one or the other.");
+            process.exit(1);
+        }
+        if (!litPath && !options.doi) {
+            log.error("Either <lit-path> or --doi is required.");
+            process.exit(1);
+        }
         const resolved = resolveKnowledgeBase(kbId);
         if (!resolved) {
             log.error(`Knowledge base not found: ${kbId}`);
@@ -46,108 +59,214 @@ export function createLiteratureCommand() {
         const { kb, scope } = resolved;
         const baseDir = getBaseDir(scope);
         const litOps = getLitOps(scope);
-        // Resolve file path
-        const absolutePath = path.resolve(litPath);
-        if (!fs.existsSync(absolutePath)) {
-            log.error(`File not found: ${absolutePath}`);
-            process.exit(1);
-        }
-        log.info("Extracting content...");
-        const docs = await extractContent(absolutePath);
-        log.step(`Extracted ${String(docs.length)} pages.`);
-        // Extract PDF metadata if available
-        const isPdf = absolutePath.toLowerCase().endsWith(".pdf");
-        const pdfMeta = isPdf ? await extractPdfMetadata(absolutePath) : null;
-        if (pdfMeta) {
-            const hasAny = pdfMeta.title ?? pdfMeta.author ?? pdfMeta.doi ?? pdfMeta.subject;
-            if (hasAny || pdfMeta.keywords.length > 0) {
-                log.info("Extracted PDF metadata:");
-                if (pdfMeta.title)
-                    log.step(`Title: ${pdfMeta.title}`);
-                if (pdfMeta.author)
-                    log.step(`Author: ${pdfMeta.author}`);
-                if (pdfMeta.subject)
-                    log.step(`Subject: ${pdfMeta.subject}`);
-                if (pdfMeta.doi)
-                    log.step(`DOI: ${pdfMeta.doi}`);
-                if (pdfMeta.keywords.length > 0)
-                    log.step(`Keywords: ${pdfMeta.keywords.join(", ")}`);
-                if (pdfMeta.creationDate)
-                    log.step(`Created: ${pdfMeta.creationDate.toISOString()}`);
-                if (pdfMeta.creator)
-                    log.step(`Creator: ${pdfMeta.creator}`);
+        let absolutePath;
+        let tempDir = null;
+        let doiFromFlag = null;
+        let unpaywallMeta = null;
+        if (options.doi) {
+            // ─── DOI mode: lookup Unpaywall and download OA PDF ───
+            const normalizedDoi = normalizeDoi(options.doi);
+            doiFromFlag = normalizedDoi;
+            const email = getConfig("email");
+            if (!email) {
+                log.error('Email is required for Unpaywall API. Set it with: paper config set email "you@example.com"');
+                process.exit(1);
             }
-        }
-        // Check for duplicate DOI in the knowledge base
-        if (pdfMeta?.doi && !options.force) {
-            const existing = litOps.findLiteratureByDoi(kbId, pdfMeta.doi);
-            if (existing) {
-                log.error(`A literature with DOI "${pdfMeta.doi}" already exists in this knowledge base: ${existing.id} (${existing.title})`);
-                log.info("Use --force to add anyway.");
+            // Check for duplicate DOI before downloading
+            if (!options.force) {
+                const existing = litOps.findLiteratureByDoi(kbId, normalizedDoi);
+                if (existing) {
+                    log.error(`A literature with DOI "${normalizedDoi}" already exists in this knowledge base: ${existing.id} (${existing.title})`);
+                    log.info("Use --force to add anyway.");
+                    process.exit(1);
+                }
+            }
+            log.info(`Looking up DOI: ${normalizedDoi}`);
+            try {
+                unpaywallMeta = await lookupDoi(normalizedDoi, email);
+            }
+            catch (err) {
+                if (err instanceof UnpaywallError) {
+                    log.error(err.message);
+                }
+                else {
+                    log.error(`Unpaywall lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                process.exit(1);
+            }
+            if (!unpaywallMeta.is_oa) {
+                log.error(`Paper is not Open Access (status: ${unpaywallMeta.oa_status}).`);
+                log.info(`Add it manually: paper lit add ${kbId} <file>`);
+                process.exit(1);
+            }
+            const pdfUrl = unpaywallMeta.best_oa_location?.url_for_pdf;
+            if (!pdfUrl) {
+                const landingPage = unpaywallMeta.best_oa_location?.url_for_landing_page;
+                log.error("Paper is Open Access but no direct PDF URL is available.");
+                if (landingPage) {
+                    log.info(`Landing page: ${landingPage}`);
+                }
+                log.info(`Download the PDF manually and use: paper lit add ${kbId} <file>`);
                 process.exit(1);
             }
+            // Show Unpaywall metadata
+            log.info("Unpaywall metadata:");
+            if (unpaywallMeta.title)
+                log.step(`Title: ${unpaywallMeta.title}`);
+            if (unpaywallMeta.z_authors && unpaywallMeta.z_authors.length > 0) {
+                log.step(`Authors: ${unpaywallMeta.z_authors.map((a) => a.raw_author_name).join(", ")}`);
+            }
+            if (unpaywallMeta.journal_name)
+                log.step(`Journal: ${unpaywallMeta.journal_name}`);
+            if (unpaywallMeta.year)
+                log.step(`Year: ${String(unpaywallMeta.year)}`);
+            log.step(`OA Status: ${unpaywallMeta.oa_status}`);
+            // Download PDF to temp location
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paper-unpaywall-"));
+            absolutePath = path.join(tempDir, `${normalizedDoi.replace(/\//g, "_")}.pdf`);
+            log.info("Downloading PDF...");
+            try {
+                await downloadPdf(pdfUrl, absolutePath);
+            }
+            catch (err) {
+                fs.rmSync(tempDir, { recursive: true, force: true });
+                if (err instanceof UnpaywallError) {
+                    log.error(err.message);
+                }
+                else {
+                    log.error(`PDF download failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                process.exit(1);
+            }
+            log.step("PDF downloaded.");
         }
-        const title = options.title ?? pdfMeta?.title ?? path.basename(litPath, path.extname(litPath));
-        // Create literature record
-        const literature = litOps.createLiterature({
-            title,
-            titleTranslation: null,
-            author: pdfMeta?.author ?? null,
-            abstract: pdfMeta?.subject ?? null,
-            summary: null,
-            keywords: pdfMeta?.keywords ?? [],
-            url: null,
-            doi: pdfMeta?.doi ?? null,
-            notes: {},
-            knowledgeBaseId: kbId,
-        });
-        // Copy file to storage
-        const filesDir = getFilesDir(baseDir);
-        const ext = path.extname(litPath);
-        fs.mkdirSync(filesDir, { recursive: true });
-        fs.copyFileSync(absolutePath, path.join(filesDir, `${literature.id}${ext}`));
-        // Convert PDF to Markdown if opendataloader is available
-        if (isPdf && (await isOpendataLoaderAvailable())) {
-            const result = await convertPdfToMarkdown(absolutePath);
-            if (result) {
-                saveConvertResult(filesDir, literature.id, result);
-                log.step("Converted to Markdown via opendataloader-pdf.");
+        else {
+            // ─── File mode (existing behavior) ────────────────────
+            // litPath is guaranteed to be defined here by the mutual exclusivity check above
+            const filePath = litPath ?? "";
+            absolutePath = path.resolve(filePath);
+            if (!fs.existsSync(absolutePath)) {
+                log.error(`File not found: ${absolutePath}`);
+                process.exit(1);
             }
         }
-        // Split text and add to vector store
-        log.info("Splitting text...");
-        const splitDocs = splitDocuments(docs, { chunkSize: 1000, chunkOverlap: 200 });
-        log.step(`Created ${String(splitDocs.length)} chunks.`);
-        // Add literature ID metadata to each chunk
-        for (const doc of splitDocs) {
-            doc.metadata = { ...doc.metadata, literatureId: literature.id };
-        }
-        const vectorDir = path.join(getVectorStoreDir(baseDir), kbId);
-        const modelConfig = getModelConfig(kb.embeddingModelId);
-        log.info("Embedding and storing vectors...");
-        const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
-        bar.start(splitDocs.length, 0);
-        // Check if both FAISS index files exist (not just the directory)
-        const hasIndex = fs.existsSync(path.join(vectorDir, "faiss.index")) &&
-            fs.existsSync(path.join(vectorDir, "docstore.json"));
-        if (hasIndex) {
-            await addDocuments(splitDocs, modelConfig, vectorDir);
+        // ─── Shared flow ──────────────────────────────────────
+        try {
+            log.info("Extracting content...");
+            const docs = await extractContent(absolutePath);
+            log.step(`Extracted ${String(docs.length)} pages.`);
+            // Extract PDF metadata if available
+            const isPdf = absolutePath.toLowerCase().endsWith(".pdf");
+            const pdfMeta = isPdf ? await extractPdfMetadata(absolutePath) : null;
+            if (pdfMeta) {
+                const hasAny = pdfMeta.title ?? pdfMeta.author ?? pdfMeta.doi ?? pdfMeta.subject;
+                if (hasAny || pdfMeta.keywords.length > 0) {
+                    log.info("Extracted PDF metadata:");
+                    if (pdfMeta.title)
+                        log.step(`Title: ${pdfMeta.title}`);
+                    if (pdfMeta.author)
+                        log.step(`Author: ${pdfMeta.author}`);
+                    if (pdfMeta.subject)
+                        log.step(`Subject: ${pdfMeta.subject}`);
+                    if (pdfMeta.doi)
+                        log.step(`DOI: ${pdfMeta.doi}`);
+                    if (pdfMeta.keywords.length > 0)
+                        log.step(`Keywords: ${pdfMeta.keywords.join(", ")}`);
+                    if (pdfMeta.creationDate)
+                        log.step(`Created: ${pdfMeta.creationDate.toISOString()}`);
+                    if (pdfMeta.creator)
+                        log.step(`Creator: ${pdfMeta.creator}`);
+                }
+            }
+            // Check for duplicate DOI (file mode only — DOI mode already checked above)
+            const effectiveDoi = doiFromFlag ?? pdfMeta?.doi ?? null;
+            if (effectiveDoi && !doiFromFlag && !options.force) {
+                const existing = litOps.findLiteratureByDoi(kbId, effectiveDoi);
+                if (existing) {
+                    log.error(`A literature with DOI "${effectiveDoi}" already exists in this knowledge base: ${existing.id} (${existing.title})`);
+                    log.info("Use --force to add anyway.");
+                    process.exit(1);
+                }
+            }
+            // Resolve metadata: CLI option > Unpaywall > PDF metadata > fallback
+            const unpaywallAuthors = unpaywallMeta?.z_authors && unpaywallMeta.z_authors.length > 0
+                ? unpaywallMeta.z_authors.map((a) => a.raw_author_name).join(", ")
+                : null;
+            const title = options.title ??
+                unpaywallMeta?.title ??
+                pdfMeta?.title ??
+                (litPath
+                    ? path.basename(litPath, path.extname(litPath))
+                    : (effectiveDoi ?? "Untitled"));
+            // Create literature record
+            const literature = litOps.createLiterature({
+                title,
+                titleTranslation: null,
+                author: pdfMeta?.author ?? unpaywallAuthors,
+                abstract: pdfMeta?.subject ?? null,
+                summary: null,
+                keywords: pdfMeta?.keywords ?? [],
+                url: null,
+                doi: effectiveDoi,
+                notes: {},
+                knowledgeBaseId: kbId,
+            });
+            // Copy file to storage
+            const filesDir = getFilesDir(baseDir);
+            const ext = path.extname(absolutePath);
+            fs.mkdirSync(filesDir, { recursive: true });
+            fs.copyFileSync(absolutePath, path.join(filesDir, `${literature.id}${ext}`));
+            // Convert PDF to Markdown if opendataloader is available
+            if (isPdf && (await isOpendataLoaderAvailable())) {
+                if (!(await isHybridBackendAvailable())) {
+                    log.step("Hybrid backend (localhost:5002) is not running; using basic conversion. Start the backend for better quality.");
+                }
+                const result = await convertPdfToMarkdown(absolutePath);
+                if (result) {
+                    saveConvertResult(filesDir, literature.id, result);
+                    log.step("Converted to Markdown via opendataloader-pdf.");
+                }
+            }
+            // Split text and add to vector store
+            log.info("Splitting text...");
+            const splitDocs = splitDocuments(docs, { chunkSize: 1000, chunkOverlap: 200 });
+            log.step(`Created ${String(splitDocs.length)} chunks.`);
+            // Add literature ID metadata to each chunk
+            for (const doc of splitDocs) {
+                doc.metadata = { ...doc.metadata, literatureId: literature.id };
+            }
+            const vectorDir = path.join(getVectorStoreDir(baseDir), kbId);
+            const modelConfig = getModelConfig(kb.embeddingModelId);
+            log.info("Embedding and storing vectors...");
+            const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
+            bar.start(splitDocs.length, 0);
+            // Check if both FAISS index files exist (not just the directory)
+            const hasIndex = fs.existsSync(path.join(vectorDir, "faiss.index")) &&
+                fs.existsSync(path.join(vectorDir, "docstore.json"));
+            if (hasIndex) {
+                await addDocuments(splitDocs, modelConfig, vectorDir);
+            }
+            else {
+                await createVectorStore(splitDocs, modelConfig, vectorDir);
+            }
+            bar.update(splitDocs.length);
+            bar.stop();
+            log.success(`Literature added: ${literature.id}`);
+            log.label("Title:", literature.title);
+            if (literature.author)
+                log.label("Author:", literature.author);
+            if (literature.abstract)
+                log.label("Abstract:", literature.abstract);
+            if (literature.doi)
+                log.label("DOI:", literature.doi);
+            if (literature.keywords.length > 0)
+                log.label("Keywords:", literature.keywords.join(", "));
+        }
+        finally {
+            if (tempDir) {
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            }
         }
-        else {
-            await createVectorStore(splitDocs, modelConfig, vectorDir);
-        }
-        bar.update(splitDocs.length);
-        bar.stop();
-        log.success(`Literature added: ${literature.id}`);
-        log.label("Title:", literature.title);
-        if (literature.author)
-            log.label("Author:", literature.author);
-        if (literature.abstract)
-            log.label("Abstract:", literature.abstract);
-        if (literature.doi)
-            log.label("DOI:", literature.doi);
-        if (literature.keywords.length > 0)
-            log.label("Keywords:", literature.keywords.join(", "));
     });
     // ─── lit convert ────────────────────────────────────────────
     lit

package/dist/config/index.js

@@ -61,6 +61,7 @@ function getProjectConfigPath() {
 const configSchemas = {
     embeddingModels: z.record(z.string().min(1), EmbeddingModelConfigSchema),
     defaultEmbeddingModelId: z.string().min(1),
+    email: z.email(),
 };
 // ─── Config File I/O ────────────────────────────────────────
 export function readConfigFile(filePath) {

package/dist/dep/index.js

@@ -0,0 +1,19 @@
+import { request } from "node:http";
+const HYBRID_BACKEND_URL = "http://localhost:5002";
+const HYBRID_PROBE_TIMEOUT_MS = 1500;
+/** Check if the opendataloader hybrid backend is reachable at localhost:5002. */
+export function isHybridBackendAvailable() {
+    return new Promise((resolve) => {
+        const req = request(HYBRID_BACKEND_URL, { method: "GET", timeout: HYBRID_PROBE_TIMEOUT_MS }, (res) => {
+            // Any response means the server is running
+            res.resume();
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.end();
+    });
+}

package/dist/extractor/markdown.js

@@ -1,8 +1,8 @@
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { request } from "node:http";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
+import { isHybridBackendAvailable } from "../dep/index.js";
 /**
  * Check whether opendataloader-pdf is available (package installed + Java runtime).
  * Result is cached after the first call.
@@ -124,24 +124,6 @@ export async function checkOpendataLoaderStatus() {
         hybridBackendAvailable,
     };
 }
-const HYBRID_BACKEND_URL = "http://localhost:5002";
-const HYBRID_PROBE_TIMEOUT_MS = 1500;
-/** Check if the opendataloader hybrid backend is reachable at localhost:5002. */
-function isHybridBackendAvailable() {
-    return new Promise((resolve) => {
-        const req = request(HYBRID_BACKEND_URL, { method: "GET", timeout: HYBRID_PROBE_TIMEOUT_MS }, (res) => {
-            // Any response means the server is running
-            res.resume();
-            resolve(true);
-        });
-        req.on("error", () => resolve(false));
-        req.on("timeout", () => {
-            req.destroy();
-            resolve(false);
-        });
-        req.end();
-    });
-}
 // execFile is safe — arguments are passed as an array, no shell interpolation.
 function getJavaVersion() {
     return new Promise((resolve) => {

package/dist/types/index.js

@@ -32,4 +32,5 @@ export const ConfigSchema = z.object({
     $schema: z.string().optional(),
     embeddingModels: z.record(z.string().min(1), EmbeddingModelConfigSchema).default({}),
     defaultEmbeddingModelId: z.string().min(1).optional(),
+    email: z.email().optional(),
 });

package/dist/unpaywall/index.js

@@ -0,0 +1,71 @@
+import { writeFile } from "node:fs/promises";
+import * as z from "zod";
+// ─── Unpaywall Response Schema ─────────────────────────────
+const UnpaywallOaLocationSchema = z.object({
+    url_for_pdf: z.string().nullable(),
+    url_for_landing_page: z.string().nullable(),
+    license: z.string().nullable(),
+    version: z.string().nullable(),
+    host_type: z.string().nullable(),
+});
+const UnpaywallAuthorSchema = z.object({
+    raw_author_name: z.string(),
+});
+const UnpaywallResponseSchema = z.object({
+    is_oa: z.boolean(),
+    oa_status: z.string(),
+    title: z.string().nullable().optional(),
+    z_authors: z.array(UnpaywallAuthorSchema).nullable().optional(),
+    published_date: z.string().nullable().optional(),
+    journal_name: z.string().nullable().optional(),
+    year: z.number().nullable().optional(),
+    publisher: z.string().nullable().optional(),
+    best_oa_location: UnpaywallOaLocationSchema.nullable(),
+    doi: z.string(),
+});
+export class UnpaywallError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "UnpaywallError";
+        this.code = code;
+    }
+}
+// ─── DOI Normalization ─────────────────────────────────────
+export function normalizeDoi(input) {
+    return input.replace(/^https?:\/\/(dx\.)?doi\.org\//, "").replace(/^doi:/i, "");
+}
+// ─── API Client ────────────────────────────────────────────
+export async function lookupDoi(doi, email) {
+    const url = `https://api.unpaywall.org/v2/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`;
+    const response = await fetch(url, {
+        headers: { Accept: "application/json" },
+        redirect: "follow",
+    });
+    if (response.status === 404) {
+        throw new UnpaywallError(`DOI not found in Unpaywall: ${doi}`, "not_found");
+    }
+    if (!response.ok) {
+        throw new UnpaywallError(`Unpaywall API error: HTTP ${String(response.status)}`, "api_error");
+    }
+    const json = await response.json();
+    const result = UnpaywallResponseSchema.safeParse(json);
+    if (!result.success) {
+        throw new UnpaywallError(`Invalid Unpaywall API response: ${result.error.message}`, "parse_error");
+    }
+    return result.data;
+}
+// ─── PDF Download ──────────────────────────────────────────
+export async function downloadPdf(url, destPath) {
+    const response = await fetch(url, { redirect: "follow" });
+    if (!response.ok) {
+        throw new UnpaywallError(`Failed to download PDF: HTTP ${String(response.status)}`, "download_error");
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/pdf") &&
+        !contentType.includes("application/octet-stream")) {
+        throw new UnpaywallError(`Expected PDF but received: ${contentType}`, "download_error");
+    }
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    await writeFile(destPath, buffer);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-manager",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "description": "A paper management system.",
   "keywords": [],
   "homepage": "https://github.com/EurFelux/paper-manager",