diff --git a/README.md b/README.md index 6cd4e54..4052ea8 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,71 @@ # DocFast API -Fast, simple HTML/Markdown to PDF API with built-in invoice templates. +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 -npm install -npm run build -API_KEYS=your-key-here npm start +curl -X POST https://docfast.dev/v1/convert/html \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"html": "

Hello World

Your first PDF.

"}' \ + -o output.pdf ``` -## Endpoints +## API Endpoints ### Convert HTML to PDF + ```bash -curl -X POST http://localhost:3100/v1/convert/html \ +curl -X POST https://docfast.dev/v1/convert/html \ -H "Authorization: Bearer YOUR_KEY" \ -H "Content-Type: application/json" \ - -d '{"html": "

Hello

World

"}' \ + -d '{"html": "

Hello

", "format": "A4", "margin": {"top": "20mm"}}' \ -o output.pdf ``` ### Convert Markdown to PDF + ```bash -curl -X POST http://localhost:3100/v1/convert/markdown \ +curl -X POST https://docfast.dev/v1/convert/markdown \ -H "Authorization: Bearer YOUR_KEY" \ -H "Content-Type: application/json" \ - -d '{"markdown": "# Hello\n\nWorld"}' \ + -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 http://localhost:3100/v1/templates/invoice/render \ +curl -X POST https://docfast.dev/v1/templates/invoice/render \ -H "Authorization: Bearer YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ @@ -40,23 +73,95 @@ curl -X POST http://localhost:3100/v1/templates/invoice/render \ "date": "2026-02-14", "from": {"name": "Your Company", "email": "you@example.com"}, "to": {"name": "Client", "email": "client@example.com"}, - "items": [{"description": "Service", "quantity": 1, "unitPrice": 100, "taxRate": 20}] + "items": [{"description": "Consulting", "quantity": 10, "unitPrice": 150, "taxRate": 20}] }' \ -o invoice.pdf ``` -### Options -- `format`: Paper size (A4, Letter, Legal, etc.) -- `landscape`: true/false -- `margin`: `{top, right, bottom, left}` in CSS units -- `css`: Custom CSS (for markdown/html fragments) -- `filename`: Suggested filename in Content-Disposition header +### Demo (No Auth Required) -## Auth -Pass API key via `Authorization: Bearer `. Set `API_KEYS` env var (comma-separated for multiple keys). +Try the API without signing up: -## Docker ```bash -docker build -t docfast . -docker run -p 3100:3100 -e API_KEYS=your-key docfast +curl -X POST https://docfast.dev/v1/demo/html \ + -H "Content-Type: application/json" \ + -d '{"html": "

Demo PDF

No API key needed.

"}' \ + -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 ` header +- `X-API-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