feat: enhance PDF export with 4 customizable parameters

Add comprehensive parameter support to /export/pdf endpoint: - lang: Language selection (en/es) - length: CV length (short/long) - icons: Icon visibility (show/hide) - version: Theme variant (extended/clean) Backend Changes: - Enhanced PDF generator with cookie injection for user preferences - Cookies set before chromedp navigation to apply all preferences - Updated filename pattern: CV-{Name}-{lang}-{length}-{version}.pdf - Comprehensive parameter validation with descriptive error messages - All parameters optional with sensible defaults (en, short, show, extended) Testing: - Added pdf_test.go with parameter validation tests - Tests cover all valid/invalid parameter combinations - Tests verify default parameter application Documentation: - Updated API documentation (doc/3-API.md) - Added detailed parameter descriptions and examples - Updated quick reference with all parameter options - Added process flow diagram showing cookie injection - Documented error responses for each invalid parameter Implementation Details: - Cookie domain set to "localhost" for chromedp context - Cookies: cv-language, cv-length, cv-icons, cv-theme - PDF generation leverages existing @media print CSS - No changes to frontend CSS or templates Tested: - Parameter validation (✅ All invalid params rejected correctly) - Default parameters (✅ Applied when params omitted) - PDF generation with all parameter combinations (✅ Working)
2025-11-19 10:43:19 +00:00
parent ddd09f9a16
commit 12bd9c7cd8
4 changed files with 522 additions and 108 deletions
@@ -55,7 +55,7 @@ http://localhost:1999
 |----------|--------|-------------|------------|
 | `/?lang={en\|es}` | GET | Full HTML page with CV content | Initial page load |
 | `/cv?lang={en\|es}` | GET | HTML partial for HTMX swaps | Language switching |
-| `/export/pdf?lang={en\|es}` | GET | Download PDF resume | Export functionality |
+| `/export/pdf?lang={en\|es}&length={short\|long}&icons={show\|hide}&version={extended\|clean}` | GET | Download PDF resume with parameters | Export functionality |
 | `/health` | GET | Health check (JSON) | Monitoring |
 | `/static/{path}` | GET | Static files (CSS, JS, images) | Assets |

@@ -74,8 +74,8 @@ curl "http://localhost:1999/?lang=es"
 # CV content partial (for HTMX)
 curl "http://localhost:1999/cv?lang=en"

-# Export PDF
-curl -O -J "http://localhost:1999/export/pdf?lang=en"
+# Export PDF (short, clean version)
+curl -O -J "http://localhost:1999/export/pdf?lang=en&length=short&version=clean"

 # Static file with headers
 curl -I http://localhost:1999/static/css/main.css
@@ -373,13 +373,16 @@ Content-Type: text/html

 #### Query Parameters

-| Parameter | Type | Required | Default | Description |
+| Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `lang` | string | No | `en` | Language code (`en` or `es`) |
 | `length` | string | No | `short` | CV length (`short` for summary, `long` for detailed) |
 | `icons` | string | No | `show` | Icon visibility (`show` or `hide`) |
 | `version` | string | No | `extended` | CV version (`extended` for default, `clean` for minimal) |
-No special headers required.
+
+#### Request Headers
+
+No special headers required.

 #### Response

@@ -394,7 +397,7 @@ No special headers required.
 Content-Length: [size in bytes]
 ```

-**Response Body:** Binary PDF data
+**Response Body:** Binary PDF data

 #### Examples

@@ -402,25 +405,32 @@ Content-Length: [size in bytes]
 ```bash
 curl -O -J "http://localhost:1999/export/pdf?lang=en&length=short&icons=show&version=clean"
 # Downloads: CV-Juan-Andrés-Moreno-Rubio-en-short-clean.pdf
-```
+```

-**curl - Download Spanish PDF:**
-```bash
+**curl - Download Spanish PDF (long, extended version):**
+```bash
 curl -o cv-es.pdf "http://localhost:1999/export/pdf?lang=es&length=long&icons=hide&version=extended"
 # Downloads: CV-Juan-Andrés-Moreno-Rubio-es-long-extended.pdf
-
+```

-```bash
+**curl - Use defaults:**
+```bash
+curl -O -J "http://localhost:1999/export/pdf"
+# Downloads: CV-Juan-Andrés-Moreno-Rubio-en-short-extended.pdf
+```
+
+**wget:**
+```bash
 wget --content-disposition "http://localhost:1999/export/pdf?lang=en&length=short&version=clean"
 ```

 **HTML Link:**
-```html
+```html
 <a href="/export/pdf?lang=en&length=short&icons=show&version=clean" download>
  Download CV (PDF)
 </a>
 ```
-
+
 **HTMX Button (triggers download):**
 ```html
 <button
@@ -428,7 +438,7 @@ wget --content-disposition "http://localhost:1999/export/pdf?lang=en"
  hx-trigger="click">
  📥 Download PDF
 </button>
-```
+```

 #### Process Flow

@@ -436,13 +446,20 @@ wget --content-disposition "http://localhost:1999/export/pdf?lang=en"
 2. Validates all parameters (lang, length, icons, version)
 3. Sets cookies for user preferences:
   - `cv-language` → `{lang}`
-5. Waits for page load and rendering
-6. Generates PDF with print-optimized settings
-7. Returns PDF as downloadable file
-
-#### Error Responses
-
-**400 Bad Request** - Invalid language:
+   - `cv-length` → `{length}`
+   - `cv-icons` → `{icons}`
+   - `cv-theme` → `default` or `clean` based on `{version}`
+4. Constructs internal URL: `http://localhost:1999/?lang={lang}`
+5. Launches headless Chrome via chromedp
+6. Sets cookies in browser context
+7. Navigates to the CV page
+8. Waits for page load and rendering
+9. Generates PDF with print-optimized settings (A4, @media print CSS)
+10. Returns PDF with filename: `CV-{Name}-{lang}-{length}-{version}.pdf`
+
+#### Error Responses
+
+**400 Bad Request** - Invalid language:
 ```http
 HTTP/1.1 400 Bad Request
 Content-Type: text/plain
@@ -454,6 +471,30 @@ Content-Type: text/plain
 HTTP/1.1 400 Bad Request
 Content-Type: text/plain

+```
+
+**400 Bad Request** - Invalid icons option:
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: text/plain
+
+```
+
+**400 Bad Request** - Invalid version:
+```http
+HTTP/1.1 400 Bad Request
+Content-Type: text/plain
+
+```
+
+**500 Internal Server Error** - PDF generation failed:
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Type: text/plain
+
+```
+
+#### Parameter Details

 **Language (`lang`):**
 - `en` - English content
@@ -462,15 +503,34 @@ Content-Type: text/plain
 **Length (`length`):**
 - `short` - Summary version with concise descriptions
 - `long` - Detailed version with full responsibilities and descriptions
+
+**Icons (`icons`):**
+- `show` - Display company logos, project icons, and section icons
+- `hide` - Hide all icons for a text-only appearance
+
+**Version (`version`):**
+- `extended` - Default theme with full styling
+- `clean` - Minimal theme optimized for print
+
+#### Notes
+
+- **Timeout:** 30-second timeout for PDF generation
+- **Dependencies:** Requires chromedp and a Chrome/Chromium installation
+- **Performance:** PDF generation takes 2-5 seconds typically
+- **Memory:** Uses headless Chrome, requires adequate system memory
+- **Filename Pattern:** `CV-{Name}-{lang}-{length}-{version}.pdf`
+- **Cookie Injection:** Parameters are injected as cookies before page rendering
+- **Print Styles:** Respects `@media print` CSS rules
 - **Size:** Short version ~1.5-2MB, Long version ~2-2.5MB (varies with content)

 ---

 ### 4. GET /health

-### 4. GET /health
-
+**Description:** Health check endpoint returning server status, version, and timestamp in JSON format. Used for monitoring and load balancer health checks.
+
 #### Query Parameters
+
 None.

 #### Request Headers