annas-downloader 1.0.0

package/README.md

@@ -0,0 +1,200 @@
+# Anna's Archive Book Downloader
+
+CLI tool to search and download books from Anna's Archive mirror sites.
+
+## Features
+
+- 🔍 **Search** — Search books without downloading
+- 📥 **Download** — Interactive selection or MD5-based download
+- 📊 **Batch** — Batch download from Excel files with JSON output
+- 🔄 **Smart Matching** — Auto-select best match, with LLM-assisted fallback
+- 🛡️ **Error Handling** — CAPTCHA detection, rate limiting, timeout retry
+
+## Requirements
+
+- Node.js 18+
+- Anna's Archive API key
+- `cookies.json` file (for downloads)
+
+## Installation
+
+```bash
+npm install -g @zheyao/annas-book-downloader
+```
+
+**Install the Claude Code skill (optional but recommended):**
+
+```bash
+annas-download install
+```
+
+This installs the `anna-downloader` skill to `~/.claude/skills/`, enabling Claude Code to help with book searches and downloads.
+
+## Quick Start
+
+### 1. Initialize config
+
+```bash
+annas-download config init
+```
+
+Edit `~/.annasbook/config.json` with your API key and mirror URL.
+
+### 2. Search for a book
+
+```bash
+annas-download search --title "The Great Gatsby"
+```
+
+### 3. Download a book
+
+```bash
+annas-download download --md5 <md5-hash>
+```
+
+## Usage
+
+### Search
+
+```bash
+annas-download search --title "Book Title" --author "Author"
+annas-download search --title "Dune" --format pdf
+annas-download search --title "1984" --format epub --lang en
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--title <string>` | Book title keywords (required) |
+| `--author <string>` | Author name |
+| `--format <pdf\|epub>` | Filter by format |
+| `--lang <en\|zh>` | Language preference (default: en) |
+| `--limit <number>` | Max results (default: 5) |
+| `--json` | JSON output |
+
+### Download
+
+**Interactive (search first):**
+```bash
+annas-download download --title "The Great Gatsby"
+```
+
+**By MD5 directly:**
+```bash
+annas-download download --md5 a1b2c3d4e5f6...
+annas-download download --md5 a1b2c3d4e5f6... --filename "My Book"
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--md5 <string>` | Book MD5 hash (bypasses search) |
+| `--title <string>` | Book title keywords (for search) |
+| `--author <string>` | Author name |
+| `--format <pdf\|epub>` | Filter by format |
+| `--lang <en\|zh>` | Language preference |
+| `--filename <string>` | Output filename (MD5 mode only) |
+| `--output <dir>` | Output directory |
+| `--json` | JSON output |
+
+### Batch Download
+
+```bash
+annas-download batch --excel ./books.xlsx
+annas-download batch --excel ./books.xlsx --output ./downloads --limit 10
+annas-download batch --excel ./books.xlsx --json
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--excel <file>` | Excel file path (required) |
+| `--output <dir>` | Output directory |
+| `--limit <n>` | Max downloads |
+| `--json` | JSON output |
+
+**Excel Format:**
+| Column | Description |
+|--------|-------------|
+| 语言 | "en" to use English title, otherwise Chinese |
+| 书名 | Chinese title |
+| Book title | English title |
+| 作者 | Chinese author |
+| Author | English author |
+| 下载状态 | Status (updated automatically) |
+| 书籍链接 | Optional MD5 link to skip search |
+
+### Config Management
+
+```bash
+annas-download config list    # Show config paths and values
+annas-download config path    # Show active config file path
+annas-download config init    # Create default config in ~/.annasbook/
+```
+
+### Convert EPUB to PDF
+
+```bash
+annas-download convert ./book.epub
+annas-download convert ./book.epub --output ./pdfs
+```
+
+### Generate PDF Preview
+
+```bash
+annas-download preview ./book.pdf
+annas-download preview ./book.pdf --output ./previews
+```
+
+Requires `pdftoppm` from poppler (macOS: `brew install poppler`)
+
+## Configuration
+
+Edit `~/.annasbook/config.json`:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "baseUrl": "https://annas-archive.gl",
+  "downloadDir": "./downloads",
+  "rateLimitMs": 10000,
+  "requestTimeoutMs": 30000,
+  "downloadTimeoutMs": 300000,
+  "maxRetries": 3,
+  "proxy": "http://127.0.0.1:7892",
+  "downloadLimit": 10,
+  "openai": {
+    "enable": true,
+    "apiKey": "sk-...",
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `apiKey` | required | API key for Anna's Archive |
+| `baseUrl` | required | Base URL for mirror |
+| `downloadDir` | ./downloads | Download directory |
+| `rateLimitMs` | 10000 | Delay between requests (ms) |
+| `requestTimeoutMs` | 30000 | HTTP request timeout (ms) |
+| `downloadTimeoutMs` | 300000 | Download timeout (ms) |
+| `maxRetries` | 3 | Max retry attempts |
+| `proxy` | - | Optional proxy URL |
+| `downloadLimit` | unlimited | Max downloads per run |
+| `openai.apiKey` | - | OpenAI API key for LLM matching |
+| `openai.enable` | true | Enable LLM fallback |
+
+## Error Handling
+
+| Error | Meaning | Solution |
+|-------|---------|----------|
+| `CAPTCHA_DETECTED` | CAPTCHA challenge triggered | Visit search URL in browser, solve CAPTCHA, update `cookies.json` |
+| `NO_DOWNLOADS_LEFT` | Account has no downloads remaining | Use a different account |
+| `RATE_LIMITED` | Too many requests | Tool waits 60 seconds automatically |
+| 502 Bad Gateway | Rate limit too aggressive | Increase `rateLimitMs` to 10000 or higher |
+
+## License
+
+ISC

package/assets/skills/anna-downloader/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: anna-downloader
+description: |
+  Download, search, batch process, convert, and preview books from Anna's Archive using the CLI tool. Use this skill whenever the user wants to search for, download, batch download from Excel, convert ebook formats, or generate PDF previews from Anna's Archive. Triggers on requests like "download a book", "find a PDF of", "search for ebook", "get a book from Anna's Archive", "batch download books from Excel", "convert epub to pdf", "generate PDF preview", or any mention of downloading books/ebooks/PDFs/EPUBs. The skill provides complete CLI commands for searching, downloading, batch processing, format conversion, and PDF preview generation.
+---
+
+# Anna's Archive Book Downloader
+
+A CLI tool to search and download books from Anna's Archive mirror sites.
+
+## Prerequisites
+
+Before using this tool, you need a config file. The tool searches for config in this order:
+
+1. `ANNASBOOK_CONFIG` environment variable
+2. `~/.annasbook/config.json` (default location)
+
+**Initialize config:**
+```bash
+annas-download config init
+```
+
+**Config file format:**
+```json
+{
+  "apiKey": "your-api-key",
+  "baseUrl": "https://annas-archive.gl",
+  "downloadDir": "./downloads",
+  "rateLimitMs": 10000,
+  "requestTimeoutMs": 30000,
+  "downloadTimeoutMs": 300000,
+  "maxRetries": 3,
+  "proxy": "http://127.0.0.1:7892",
+  "downloadLimit": 10,
+  "openai": {
+    "enable": true,
+    "apiKey": "sk-...",
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+**Config fields:**
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `apiKey` | string | required | API key for Anna's Archive |
+| `baseUrl` | string | required | Base URL for Anna's Archive mirror |
+| `downloadDir` | string | ./downloads | Directory for downloaded files |
+| `rateLimitMs` | number | 10000 | Delay between requests (ms) - **important: 10s default to avoid 502 errors** |
+| `requestTimeoutMs` | number | 30000 | HTTP request timeout (ms) |
+| `downloadTimeoutMs` | number | 300000 | Download timeout (ms) |
+| `maxRetries` | number | 3 | Max retry attempts |
+| `proxy` | string | - | Optional proxy URL |
+| `downloadLimit` | number | - | Max downloads per run (0 = unlimited) |
+| `openai.apiKey` | string | - | OpenAI API key for LLM-assisted matching |
+| `openai.baseUrl` | string | https://api.openai.com/v1 | OpenAI API base URL |
+| `openai.model` | string | gpt-4o-mini | OpenAI model for matching |
+| `openai.enable` | boolean | true | Enable LLM fallback when traditional matching fails |
+| `excelFile` | string | - | Path to Excel file for batch mode |
+
+**Environment variables** (override config file):
+- `ANNASBOOK_API_KEY` - API key
+- `ANNASBOOK_BASE_URL` - Mirror URL
+- `ANNASBOOK_DOWNLOAD_DIR` - Download directory
+- `ANNASBOOK_PROXY` - Proxy URL
+
+**cookies.json** (in project root or `~/.annasbook/`) - Authentication cookies:
+```json
+"name1=value1; name2=value2"
+```
+
+## CLI Commands
+
+### Search for Books
+
+```bash
+annas-download search --title "Book Title"
+annas-download search --title "Book Title" --author "Author Name"
+annas-download search --title "Dune" --format epub
+annas-download search --title "1984" --author "Orwell" --format pdf --lang en
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--title <string>` | Book title keywords (required) |
+| `--author <string>` | Author name |
+| `--format <pdf\|epub>` | Filter by format |
+| `--lang <en\|zh>` | Language preference (default: en) |
+| `--limit <number>` | Max results (default: 5) |
+| `--json` | JSON output |
+
+### Download Books
+
+**Method 1: Search and Download Interactively**
+
+```bash
+annas-download download --title "The Great Gatsby"
+annas-download download --title "1984" --author "Orwell" --format pdf
+```
+
+**Method 2: Download by MD5 Directly**
+
+```bash
+annas-download download --md5 a1b2c3d4e5f6...
+annas-download download --md5 a1b2c3d4e5f6... --filename "My Book Title"
+```
+
+**Download Options:**
+| Option | Description |
+|--------|-------------|
+| `--md5 <string>` | Book MD5 hash (bypasses search) |
+| `--title <string>` | Book title keywords (for search) |
+| `--author <string>` | Author name |
+| `--format <pdf\|epub>` | Filter by format |
+| `--lang <en\|zh>` | Language preference |
+| `--filename <string>` | Output filename (MD5 mode only) |
+| `--output <dir>` | Output directory |
+| `--json` | JSON output |
+
+### Batch Download from Excel
+
+```bash
+annas-download batch --excel ./books.xlsx
+annas-download batch --excel ./books.xlsx --output ./downloads --limit 10
+annas-download batch --excel ./books.xlsx --json
+```
+
+**Batch Options:**
+| Option | Description |
+|--------|-------------|
+| `--excel <file>` | Excel file path (required) |
+| `--output <dir>` | Output directory |
+| `--limit <n>` | Max downloads |
+| `--json` | JSON output |
+
+**Excel Format Requirements:**
+| Column | Description |
+|--------|-------------|
+| 语言 | "en" to use English title, otherwise Chinese |
+| 书名 | Chinese title |
+| Book title | English title |
+| 作者 | Chinese author |
+| Author | English author |
+| 下载状态 | Status (updated automatically) |
+| 书籍链接 | Optional MD5 link to skip search |
+
+### Config Management
+
+```bash
+annas-download config list    # Show config paths and current values
+annas-download config path    # Show active config file path
+annas-download config init    # Create default config in ~/.annasbook/
+```
+
+### Convert EPUB to PDF
+
+```bash
+annas-download convert ./book.epub
+annas-download convert ./book.epub --output ./pdfs
+annas-download convert ./book.epub --output ./pdfs/mybook.pdf
+```
+
+**Convert Options:**
+| Option | Description |
+|--------|-------------|
+| `<input.epub>` | Path to EPUB file (required, position arg) |
+| `--output <path>` | Output path or directory for PDF |
+
+### Generate PDF Preview
+
+Generate a PNG preview of the first page of a PDF file.
+
+```bash
+annas-download preview ./book.pdf
+annas-download preview ./book.pdf --output ./previews
+annas-download preview ./book.pdf --output ./previews/cover.png
+```
+
+**Preview Options:**
+| Option | Description |
+|--------|-------------|
+| `<input.pdf>` | Path to PDF file (required, positional arg) |
+| `--input <path>` | Alternative way to specify input PDF |
+| `--output <path>` | Output path or directory for PNG (default: same dir as input, .pdf → .png) |
+
+**Requirements:** Requires `pdftoppm` from poppler (macOS: `brew install poppler`)
+
+### Global Options
+
+```bash
+annas-download --config /path/to/config.json search --title "Book"
+annas-download --output ./my-downloads download --md5 abc123
+annas-download --json search --title "Book"
+annas-download --help
+annas-download --version
+```
+
+## Error Handling
+
+| Error | Meaning | Solution |
+|-------|---------|----------|
+| `CAPTCHA_DETECTED` | CAPTCHA challenge triggered | Visit search URL in browser, solve CAPTCHA, update `cookies.json` |
+| `NO_DOWNLOADS_LEFT` | Account has no downloads remaining | Use a different account |
+| `RATE_LIMITED` | Too many requests | Tool waits 60 seconds automatically |
+| 502 Bad Gateway | Rate limit too aggressive | Increase `rateLimitMs` to 10000 or higher (default is 10s) |
+
+## Typical Workflow
+
+1. **First, search to see available editions:**
+   ```bash
+   annas-download search --title "Book Name" --author "Author" --format pdf
+   ```
+
+2. **Review results** - Note the MD5 of desired edition
+
+3. **Download either interactively or by MD5:**
+   ```bash
+   # Interactive
+   annas-download download --title "Book Name" --format pdf
+
+   # Direct by MD5
+   annas-download download --md5 <the-md5-hash>
+   ```
+
+4. **Files are saved to** `downloadDir` (default: `./downloads`)
+
+## Notes
+
+- The tool auto-detects actual file format from download header (may differ from search result)
+- Downloaded files are named: `{ChineseTitle} - {EnglishTitle}.{extension}`
+- For Chinese books, set `--lang zh` to use Chinese title for search
+- The tool retries on timeout (up to `maxRetries` in config)
+- When traditional title matching fails, the tool can use OpenAI LLM to find the best match (requires `openai.apiKey` in config)
+- EPUB files are automatically converted to PDF after download if `openai` is configured

package/assets/skills/anna-downloader/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "anna-downloader",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我下载《了不起的盖茨比》这本书",
+      "expected_output": "应使用 annas-download download --title \"The Great Gatsby\" --lang en 命令搜索并下载",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Search for a PDF of \"Designing Data-Intensive Applications\"",
+      "expected_output": "应使用 annas-download search --title \"Designing Data-Intensive Applications\" --format pdf 命令搜索",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I have an MD5 hash a1b2c3d4e5f6g7h8, download that book for me",
+      "expected_output": "应使用 annas-download download --md5 a1b2c3d4e5f6g7h8 命令直接下载",
+      "files": []
+    }
+  ]
+}

package/bin/annas-download.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/commands/cli.js');

package/dist/commands/batch.d.ts

@@ -0,0 +1,9 @@
+import { Config } from '../src/types.js';
+interface BatchArgs {
+    excel?: string;
+    output?: string;
+    json?: boolean;
+    limit?: number;
+}
+export declare function runBatch(args: BatchArgs, config: Config): Promise<void>;
+export {};