docfast/README.md

# DocFast API

Fast, reliable HTML/Markdown/URL to PDF conversion API. EU-hosted, GDPR compliant.

**Website:** https://docfast.dev
**Docs:** https://docfast.dev/docs
**Status:** https://docfast.dev/status

## Features

- **HTML → PDF** — Full documents or fragments with optional CSS
- **Markdown → PDF** — GitHub-flavored Markdown with syntax highlighting
- **URL → PDF** — Render any public webpage as PDF (SSRF-protected)
- **Invoice Templates** — Built-in professional invoice template
- **PDF Options** — Paper size, orientation, margins, headers/footers, page ranges, scaling

## Quick Start

### 1. Get an API Key

Sign up at https://docfast.dev — free demo available, Pro plan at €9/month for 5,000 PDFs.

### 2. Generate a PDF

```bash
curl -X POST https://docfast.dev/v1/convert/html \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello World</h1><p>Your first PDF.</p>"}' \
  -o output.pdf
```

## API Endpoints

### Convert HTML to PDF

```bash
curl -X POST https://docfast.dev/v1/convert/html \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello</h1>", "format": "A4", "margin": {"top": "20mm"}}' \
  -o output.pdf
```

### Convert Markdown to PDF

```bash
curl -X POST https://docfast.dev/v1/convert/markdown \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nWorld", "css": "body { font-family: sans-serif; }"}' \
  -o output.pdf
```

### Convert URL to PDF

```bash
curl -X POST https://docfast.dev/v1/convert/url \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "A4", "landscape": true}' \
  -o output.pdf
```

### Invoice Template

```bash
curl -X POST https://docfast.dev/v1/templates/invoice/render \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceNumber": "INV-001",
    "date": "2026-02-14",
    "from": {"name": "Your Company", "email": "you@example.com"},
    "to": {"name": "Client", "email": "client@example.com"},
    "items": [{"description": "Consulting", "quantity": 10, "unitPrice": 150, "taxRate": 20}]
  }' \
  -o invoice.pdf
```

### Demo (No Auth Required)

Try the API without signing up:

```bash
curl -X POST https://docfast.dev/v1/demo/html \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Demo PDF</h1><p>No API key needed.</p>"}' \
  -o demo.pdf
```

Demo PDFs include a watermark and are rate-limited.

## PDF Options

All conversion endpoints accept these options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `format` | string | `"A4"` | Paper size: A4, Letter, Legal, A3, etc. |
| `landscape` | boolean | `false` | Landscape orientation |
| `margin` | object | `{top:"0",right:"0",bottom:"0",left:"0"}` | Margins in CSS units (px, mm, in, cm) |
| `printBackground` | boolean | `true` | Include background colors/images |
| `filename` | string | `"document.pdf"` | Suggested filename in Content-Disposition |
| `css` | string | — | Custom CSS (for HTML fragments and Markdown) |
| `scale` | number | `1` | Scale (0.1–2.0) |
| `pageRanges` | string | — | Page ranges, e.g. `"1-3, 5"` |
| `width` | string | — | Custom page width (overrides format) |
| `height` | string | — | Custom page height (overrides format) |
| `headerTemplate` | string | — | HTML template for page header |
| `footerTemplate` | string | — | HTML template for page footer |
| `displayHeaderFooter` | boolean | `false` | Show header/footer |
| `preferCSSPageSize` | boolean | `false` | Use CSS `@page` size over format |

## Authentication

Pass your API key via either:
- `Authorization: Bearer <key>` header
- `X-API-Key: <key>` header

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build
npm run build

# Start production server
npm start
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `STRIPE_SECRET_KEY` | Yes | Stripe API key for billing |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signature secret |
| `SMTP_HOST` | Yes | SMTP server hostname |
| `SMTP_PORT` | Yes | SMTP server port |
| `SMTP_USER` | Yes | SMTP username |
| `SMTP_PASS` | Yes | SMTP password |
| `BASE_URL` | No | Base URL (default: https://docfast.dev) |
| `PORT` | No | Server port (default: 3100) |
| `BROWSER_COUNT` | No | Puppeteer browser instances (default: 2) |
| `PAGES_PER_BROWSER` | No | Pages per browser (default: 8) |
| `LOG_LEVEL` | No | Pino log level (default: info) |

### Architecture

- **Runtime:** Node.js + Express
- **PDF Engine:** Puppeteer (Chromium) with browser pool
- **Database:** PostgreSQL (via pg)
- **Payments:** Stripe
- **Email:** SMTP (nodemailer)

## License

Proprietary — Cloonar Technologies GmbH