# PostConvert – Robust Image & PDF → JPEG Conversion Service

PostConvert is a small, production-oriented HTTP service for converting **images and PDFs into JPEGs**, with strong emphasis on **robustness, predictable resource usage, and operational safety**.

It supports:
- JPEG → JPEG (resize + recompress)
- PNG / WebP / TIFF → JPEG
- HEIC / HEIF → JPEG (via WASM fallback)
- PDF → JPEG (first page or all pages as a ZIP)

The service is designed to run well in **containers, serverless-ish environments, and small VMs** where disk, memory, and runaway workloads matter.

---

## Primary Use Cases

- Normalize user uploads (receipts, photos, scans) into JPEG
- Resize and recompress images server-side for storage or ML pipelines
- Convert PDFs (receipts, invoices, statements) into images
- Handle HEIC uploads from iOS devices without native libheif dependencies
- Safely process untrusted user uploads with bounded resource usage

---

## Key Design Goals

- **Always JPEG out**
- **Bounded `/tmp` usage** (PDFs rendered page-by-page)
- **No stack traces leaked to clients**
- **Fast path for common formats**
- **Graceful abort on client disconnect**
- **Predictable limits** (size, pages, DPI, timeouts)

---

## Endpoints

### `POST /convert`

Converts a single image **or the first page of a PDF** to a JPEG.

#### Supported inputs
- JPEG, PNG, WebP, TIFF, etc. (anything Sharp can decode)
- HEIC / HEIF
- PDF (first page only)

#### Response
- `200 image/jpeg` on success
- JSON error on failure

---

### `POST /convert/pdf`

Converts **all pages of a PDF** into JPEGs and returns a ZIP archive.

Pages are rendered **one at a time** to keep disk usage bounded.

---

## Authentication

All endpoints require a bearer token.

```
Authorization: Bearer <CONVERTER_TOKEN>
```

---

## Image Resize & JPEG Options (Headers)

| Header | Type | Default | Description |
|------|-----|--------|-------------|
| `x-jpeg-quality` | `0–100` | `100` | JPEG compression quality |
| `x-max-dimension` | px | none | Max width/height, aspect preserved |
| `x-width` | px | none | Explicit output width |
| `x-height` | px | none | Explicit output height |
| `x-fit` | enum | `inside` | `inside`, `cover`, `contain`, `fill`, `outside` |
| `x-without-enlargement` | bool | `true` | Prevent upscaling smaller images |

---

## Environment Variables

| Variable | Default | Description |
|-------|--------|------------|
| `PORT` | `8080` | Server port |
| `CONVERTER_TOKEN` | (required) | Bearer auth token |

---

## Runtime Dependencies

- Node.js 18+
- `pdftoppm` (Poppler utils) **required for PDFs**
- Sharp native dependencies (per Sharp docs)