pdf-toolkit

# pdf-toolkit

Self-hosted PDF processing tool. Merge, split, rotate, compress, watermark, and protect PDF files through a web UI or API.

## When to use

- Merging multiple PDF files into one document
- Extracting specific pages or page ranges from a PDF
- Rotating pages that are sideways or upside-down
- Reducing PDF file size for email or web sharing
- Adding a CONFIDENTIAL or DRAFT watermark to all pages
- Password-protecting a PDF before sharing
- Batch processing multiple PDFs in sequence

## Quick Start

```bash
docker compose up -d
open http://localhost:3000
```

## API Usage

All operations accept multipart form data. Responses return a token for downloading the result.

### Merge

```bash
curl -X POST http://localhost:3000/api/merge \
  -F "files[]=@first.pdf" \
  -F "files[]=@second.pdf" \
  -F "files[]=@third.pdf"
# Returns: { "token": "abc123", "filename": "merged.pdf", "pages": 62 }
```

### Split

```bash
curl -X POST http://localhost:3000/api/split \
  -F "file=@document.pdf" \
  -F "ranges=1-8,9-16"
# Returns: { "token": "abc123", "files": [...] }
```

### Compress

```bash
curl -X POST http://localhost:3000/api/compress \
  -F "file=@large.pdf" \
  -F "level=medium"
# level: low | medium | high
```

### Watermark

```bash
curl -X POST http://localhost:3000/api/watermark \
  -F "file=@document.pdf" \
  -F "text=CONFIDENTIAL" \
  -F "opacity=0.2" \
  -F "position=diagonal" \
  -F "fontSize=48"
```

### Password protect

```bash
curl -X POST http://localhost:3000/api/password \
  -F "file=@document.pdf" \
  -F "userPassword=secretpass" \
  -F "allowPrint=true" \
  -F "allowCopy=false"
```

### Download result

```bash
curl -o output.pdf http://localhost:3000/api/download/abc123
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | Server port | 3000 |
| TEMP_DIR | Temp file storage | ./tmp |
| MAX_UPLOAD_MB | Max upload size per file in MB | 100 |
| MAX_FILES | Max files per merge | 20 |
| JOB_TTL_MINUTES | Temp file retention | 60 |
| LOG_LEVEL | debug, info, warn, error | info |

## Compression Levels

| Level | Typical reduction | Use case |
|---|---|---|
| low | ~20% | Print-quality documents |
| medium | ~50% | Email sharing |
| high | ~75% | Web thumbnails, previews |

## Troubleshooting

### "PDF is encrypted" error

The file is password-protected. Remove the password using the Password tool first (you will need the current password), then retry the operation.

### File too large

Files over MAX_UPLOAD_MB are rejected with HTTP 413. Lower the file size before uploading, or increase MAX_UPLOAD_MB in your environment.

### Download link not working

Download tokens expire after JOB_TTL_MINUTES (default 60). Process the file again to get a fresh token.