orator-conversion 1.0.0

package/docs/api-reference.md

@@ -0,0 +1,146 @@
+# API Reference
+
+## Class: OratorFileTranslation
+
+Extends `fable-serviceproviderbase`. Provides file format conversion
+endpoints for an Orator web server.
+
+### Constructor
+
+```javascript
+new OratorFileTranslation(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | object | The Fable instance for the application |
+| `pOptions` | object | Configuration options (see [Configuration](configuration.md)) |
+| `pServiceHash` | string | The service identifier hash |
+
+Typically instantiated through the Fable service manager:
+
+```javascript
+_Fable.serviceManager.addServiceType('OratorFileTranslation', libOratorFileTranslation);
+_Fable.serviceManager.instantiateServiceProvider('OratorFileTranslation', {});
+```
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `serviceType` | string | `"OratorFileTranslation"` | Service type identifier |
+| `RoutePrefix` | string | `"/conversion"` | URL prefix for all endpoints |
+| `Version` | string | `"1.0"` | Version segment in route URLs |
+| `LogLevel` | number | `0` | Logging verbosity |
+| `MaxFileSize` | number | `10485760` | Maximum upload size in bytes |
+| `PdftkPath` | string | `"pdftk"` | Path to the pdftk binary |
+| `PdftoppmPath` | string | `"pdftoppm"` | Path to the pdftoppm binary |
+| `converters` | object | `{}` | Registry of converter functions (populated by `initializeDefaultConverters`) |
+
+## Methods
+
+### connectRoutes()
+
+Register POST endpoints on the Orator service server for each converter
+in the registry. Call this after Orator has been started.
+
+**Returns:** `boolean` - `true` if routes were registered, `false` if
+Orator is not available.
+
+```javascript
+_Fable.Orator.startService(
+	() =>
+	{
+		_Fable.OratorFileTranslation.connectRoutes();
+	});
+```
+
+Routes are versioned: `{RoutePrefix}/{Version}/{converterPath}`
+
+### addConverter(pPath, fConverter)
+
+Register a custom converter function for a given path segment. The path
+becomes part of the endpoint URL. Call this before `connectRoutes()`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPath` | string | Path segment (e.g. `'image/jpg-to-png'` or `'pdf-to-page-png/:Page'`) |
+| `fConverter` | function | Converter function |
+
+The converter function signature is:
+
+```javascript
+function(pInputBuffer, pRequest, fCallback)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pInputBuffer` | Buffer | The raw file data from the request body |
+| `pRequest` | object | The HTTP request object (use `pRequest.params` for route parameters) |
+| `fCallback` | function | Callback: `fCallback(pError, pOutputBuffer, pContentType)` |
+
+**Example:**
+
+```javascript
+_Fable.OratorFileTranslation.addConverter('document/csv-to-json',
+	(pInputBuffer, pRequest, fCallback) =>
+	{
+		let tmpCSV = pInputBuffer.toString('utf8');
+		let tmpJSON = convertCSVToJSON(tmpCSV);
+		return fCallback(null, Buffer.from(JSON.stringify(tmpJSON)), 'application/json');
+	});
+```
+
+### initializeDefaultConverters()
+
+Register the built-in converters (JPG to PNG, PNG to JPG, PDF to Page PNG,
+PDF to Page JPG). Called automatically by the constructor.
+
+### collectRequestBody(pRequest, fCallback)
+
+Collect the raw request body from the HTTP stream, enforcing the
+MaxFileSize limit.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pRequest` | object | The incoming HTTP request |
+| `fCallback` | function | Callback: `fCallback(pError, pBuffer)` |
+
+If the request body has already been parsed as a Buffer (e.g. by a body
+parser middleware), it is used directly. Otherwise the body is collected
+from the stream.
+
+### extractPdfPage(pPdfBuffer, pPageNumber, fCallback)
+
+Extract a single page from a PDF buffer using pdftk, returning the
+single-page PDF as a buffer.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPdfBuffer` | Buffer | The input PDF buffer |
+| `pPageNumber` | number | The 1-based page number to extract |
+| `fCallback` | function | Callback: `fCallback(pError, pSinglePagePdfBuffer)` |
+
+Requires `pdftk` to be installed and accessible at the configured
+`PdftkPath`.
+
+### renderPdfPageToImage(pPdfBuffer, pPageNumber, pFormat, fCallback)
+
+Render a specific page of a PDF to an image buffer. Uses pdftoppm to
+rasterize the page at 150 DPI.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPdfBuffer` | Buffer | The input PDF buffer |
+| `pPageNumber` | number | The 1-based page number to render |
+| `pFormat` | string | Output format: `'png'` or `'jpeg'` |
+| `fCallback` | function | Callback: `fCallback(pError, pImageBuffer)` |
+
+Requires `pdftoppm` to be installed and accessible at the configured
+`PdftoppmPath`.
+
+## Related Documentation
+
+- [Getting Started](getting-started.md) - Setup and installation
+- [Configuration](configuration.md) - All configuration options
+- [Endpoints](endpoints/) - Built-in endpoint reference

package/docs/configuration.md

@@ -0,0 +1,77 @@
+# Configuration
+
+## Constructor Options
+
+Pass options when instantiating the service:
+
+```javascript
+_Fable.serviceManager.instantiateServiceProvider('OratorFileTranslation',
+	{
+		RoutePrefix: '/api/convert',
+		Version: '2.0',
+		LogLevel: 2,
+		MaxFileSize: 5 * 1024 * 1024,  // 5MB
+		PdftkPath: '/usr/local/bin/pdftk',
+		PdftoppmPath: '/usr/local/bin/pdftoppm'
+	});
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `RoutePrefix` | string | `"/conversion"` | URL prefix for all conversion endpoints |
+| `Version` | string | `"1.0"` | Version segment in route URLs |
+| `LogLevel` | number | `0` | Logging verbosity (0 = quiet, higher = more output) |
+| `MaxFileSize` | number | `10485760` | Maximum upload size in bytes (default 10MB) |
+| `PdftkPath` | string | `"pdftk"` | Path to the pdftk binary |
+| `PdftoppmPath` | string | `"pdftoppm"` | Path to the pdftoppm binary |
+
+## Fable Settings Fallback
+
+When options are not provided, the service checks Fable settings:
+
+```javascript
+const _Fable = new libFable({
+	Product: 'MyServer',
+	APIServerPort: 8080,
+	OratorFileTranslationRoutePrefix: '/api/convert',
+	OratorFileTranslationVersion: '2.0',
+	OratorFileTranslationLogLevel: 1,
+	OratorFileTranslationMaxFileSize: 20 * 1024 * 1024,
+	OratorFileTranslationPdftkPath: '/usr/local/bin/pdftk',
+	OratorFileTranslationPdftoppmPath: '/usr/local/bin/pdftoppm'
+});
+```
+
+| Fable Setting | Maps To |
+|---------------|---------|
+| `OratorFileTranslationRoutePrefix` | `RoutePrefix` |
+| `OratorFileTranslationVersion` | `Version` |
+| `OratorFileTranslationLogLevel` | `LogLevel` |
+| `OratorFileTranslationMaxFileSize` | `MaxFileSize` |
+| `OratorFileTranslationPdftkPath` | `PdftkPath` |
+| `OratorFileTranslationPdftoppmPath` | `PdftoppmPath` |
+
+## Configuration Priority
+
+Settings are resolved in this order:
+
+1. **Constructor options** (highest priority)
+2. **Fable settings**
+3. **Default values** (lowest priority)
+
+## JSON Configuration File
+
+When using a Fable configuration file:
+
+```json
+{
+	"Product": "MyConversionServer",
+	"APIServerPort": 8080,
+	"OratorFileTranslationRoutePrefix": "/conversion",
+	"OratorFileTranslationVersion": "1.0",
+	"OratorFileTranslationLogLevel": 0,
+	"OratorFileTranslationMaxFileSize": 10485760,
+	"OratorFileTranslationPdftkPath": "pdftk",
+	"OratorFileTranslationPdftoppmPath": "pdftoppm"
+}
+```

package/docs/cover.md

@@ -0,0 +1,13 @@
+# Orator File Translation <small>1</small>
+
+> File format conversion endpoints for Orator service servers
+
+- Built-in image conversion (JPG to PNG, PNG to JPG)
+- PDF page extraction (PDF to PNG, PDF to JPEG)
+- Versioned route endpoints
+- Extensible converter registry
+- Configurable via options or Fable settings
+- Size-limited uploads for safety
+
+[GitHub](https://github.com/stevenvelozo/orator-conversion)
+[Get Started](#orator-file-translation)

package/docs/endpoints/001-jpg-to-png.md

@@ -0,0 +1,60 @@
+# JPG to PNG
+
+The JPG to PNG endpoint converts JPEG images to PNG format using the
+Sharp image processing library.
+
+## Endpoint Information
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Default Route | `/conversion/1.0/image/jpg-to-png` |
+| Converter Path | `image/jpg-to-png` |
+| Input Content Type | `application/octet-stream` |
+| Output Content Type | `image/png` |
+
+## Usage
+
+```bash
+curl -X POST --data-binary @photo.jpg \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/image/jpg-to-png \
+	-o photo.png
+```
+
+## How It Works
+
+1. The client sends a JPEG image as raw binary data in the POST body
+2. The service collects the request body and validates the file size
+3. Sharp decodes the JPEG buffer and re-encodes it as PNG
+4. The PNG buffer is returned with `Content-Type: image/png`
+
+## Response
+
+### Success (200)
+
+Returns the converted PNG image as binary data.
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `image/png` |
+| `Content-Length` | Size of the PNG output in bytes |
+
+### Error Responses
+
+| Status | Condition | Response Body |
+|--------|-----------|---------------|
+| 400 | Empty request body | `{"error": "No file data provided in request body."}` |
+| 413 | File exceeds MaxFileSize | `{"error": "File size exceeds maximum allowed size of ... bytes."}` |
+| 500 | Invalid image data | `{"error": "Conversion failed: ..."}` |
+
+## Notes
+
+- PNG output is lossless, so the output file will typically be larger than the JPEG input
+- The conversion preserves image dimensions and color data
+- Transparent pixels are not present in JPEG input, so the output PNG will have no transparency
+
+## Related Documentation
+
+- [PNG to JPG](002-png-to-jpg.md) - The reverse conversion
+- [Configuration](../configuration.md) - MaxFileSize and route settings

package/docs/endpoints/002-png-to-jpg.md

@@ -0,0 +1,60 @@
+# PNG to JPG
+
+The PNG to JPG endpoint converts PNG images to JPEG format using the
+Sharp image processing library.
+
+## Endpoint Information
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Default Route | `/conversion/1.0/image/png-to-jpg` |
+| Converter Path | `image/png-to-jpg` |
+| Input Content Type | `application/octet-stream` |
+| Output Content Type | `image/jpeg` |
+
+## Usage
+
+```bash
+curl -X POST --data-binary @image.png \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/image/png-to-jpg \
+	-o image.jpg
+```
+
+## How It Works
+
+1. The client sends a PNG image as raw binary data in the POST body
+2. The service collects the request body and validates the file size
+3. Sharp decodes the PNG buffer and re-encodes it as JPEG
+4. The JPEG buffer is returned with `Content-Type: image/jpeg`
+
+## Response
+
+### Success (200)
+
+Returns the converted JPEG image as binary data.
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `image/jpeg` |
+| `Content-Length` | Size of the JPEG output in bytes |
+
+### Error Responses
+
+| Status | Condition | Response Body |
+|--------|-----------|---------------|
+| 400 | Empty request body | `{"error": "No file data provided in request body."}` |
+| 413 | File exceeds MaxFileSize | `{"error": "File size exceeds maximum allowed size of ... bytes."}` |
+| 500 | Invalid image data | `{"error": "Conversion failed: ..."}` |
+
+## Notes
+
+- JPEG is a lossy format, so some image quality is lost during conversion
+- Any transparency in the PNG input will be flattened (alpha channel is removed)
+- The output file will typically be smaller than the PNG input
+
+## Related Documentation
+
+- [JPG to PNG](001-jpg-to-png.md) - The reverse conversion
+- [Configuration](../configuration.md) - MaxFileSize and route settings

package/docs/endpoints/003-pdf-to-page-png.md

@@ -0,0 +1,93 @@
+# PDF to Page PNG
+
+The PDF to Page PNG endpoint extracts a single page from a PDF document
+and renders it as a PNG image using pdftoppm.
+
+## Endpoint Information
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Default Route | `/conversion/1.0/pdf-to-page-png/:Page` |
+| Converter Path | `pdf-to-page-png/:Page` |
+| Input Content Type | `application/octet-stream` |
+| Output Content Type | `image/png` |
+
+## Usage
+
+```bash
+# Extract page 1
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-png/1 \
+	-o page1.png
+
+# Extract page 5
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-png/5 \
+	-o page5.png
+```
+
+## Route Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `:Page` | integer | The 1-based page number to extract (must be >= 1) |
+
+## How It Works
+
+1. The client sends a PDF file as raw binary data in the POST body
+2. The page number is parsed from the URL parameter
+3. The PDF buffer is written to a temporary file
+4. `pdftoppm` renders the specified page at 150 DPI as PNG
+5. The PNG output is read back into a buffer
+6. Temporary files are cleaned up
+7. The PNG buffer is returned with `Content-Type: image/png`
+
+## System Dependencies
+
+This endpoint requires `pdftoppm` from the poppler-utils package:
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+apt-get install poppler-utils
+```
+
+The path to pdftoppm can be configured via the `PdftoppmPath` setting.
+
+## Response
+
+### Success (200)
+
+Returns the rendered page as a PNG image.
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `image/png` |
+| `Content-Length` | Size of the PNG output in bytes |
+
+### Error Responses
+
+| Status | Condition | Response Body |
+|--------|-----------|---------------|
+| 400 | Empty request body | `{"error": "No file data provided in request body."}` |
+| 413 | File exceeds MaxFileSize | `{"error": "File size exceeds maximum allowed size of ... bytes."}` |
+| 500 | Invalid page number (0, negative, or non-integer) | `{"error": "Conversion failed: Invalid page number. Must be a positive integer."}` |
+| 500 | Page number exceeds document page count | `{"error": "Conversion failed: pdftoppm failed: ..."}` |
+| 500 | Invalid PDF data | `{"error": "Conversion failed: pdftoppm failed: ..."}` |
+
+## Notes
+
+- Pages are rendered at 150 DPI by default
+- The rendering process has a 30-second timeout
+- Page numbering is 1-based (first page is 1, not 0)
+- Temporary files are created in the system temp directory and cleaned up after each request
+
+## Related Documentation
+
+- [PDF to Page JPG](004-pdf-to-page-jpg.md) - Same extraction in JPEG format
+- [Configuration](../configuration.md) - PdftoppmPath and MaxFileSize settings

package/docs/endpoints/004-pdf-to-page-jpg.md

@@ -0,0 +1,94 @@
+# PDF to Page JPG
+
+The PDF to Page JPG endpoint extracts a single page from a PDF document
+and renders it as a JPEG image using pdftoppm.
+
+## Endpoint Information
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Default Route | `/conversion/1.0/pdf-to-page-jpg/:Page` |
+| Converter Path | `pdf-to-page-jpg/:Page` |
+| Input Content Type | `application/octet-stream` |
+| Output Content Type | `image/jpeg` |
+
+## Usage
+
+```bash
+# Extract page 1
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-jpg/1 \
+	-o page1.jpg
+
+# Extract page 3
+curl -X POST --data-binary @document.pdf \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/pdf-to-page-jpg/3 \
+	-o page3.jpg
+```
+
+## Route Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `:Page` | integer | The 1-based page number to extract (must be >= 1) |
+
+## How It Works
+
+1. The client sends a PDF file as raw binary data in the POST body
+2. The page number is parsed from the URL parameter
+3. The PDF buffer is written to a temporary file
+4. `pdftoppm` renders the specified page at 150 DPI as JPEG
+5. The JPEG output is read back into a buffer
+6. Temporary files are cleaned up
+7. The JPEG buffer is returned with `Content-Type: image/jpeg`
+
+## System Dependencies
+
+This endpoint requires `pdftoppm` from the poppler-utils package:
+
+```bash
+# macOS
+brew install poppler
+
+# Debian/Ubuntu
+apt-get install poppler-utils
+```
+
+The path to pdftoppm can be configured via the `PdftoppmPath` setting.
+
+## Response
+
+### Success (200)
+
+Returns the rendered page as a JPEG image.
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `image/jpeg` |
+| `Content-Length` | Size of the JPEG output in bytes |
+
+### Error Responses
+
+| Status | Condition | Response Body |
+|--------|-----------|---------------|
+| 400 | Empty request body | `{"error": "No file data provided in request body."}` |
+| 413 | File exceeds MaxFileSize | `{"error": "File size exceeds maximum allowed size of ... bytes."}` |
+| 500 | Invalid page number (0, negative, or non-integer) | `{"error": "Conversion failed: Invalid page number. Must be a positive integer."}` |
+| 500 | Page number exceeds document page count | `{"error": "Conversion failed: pdftoppm failed: ..."}` |
+| 500 | Invalid PDF data | `{"error": "Conversion failed: pdftoppm failed: ..."}` |
+
+## Notes
+
+- Pages are rendered at 150 DPI by default
+- JPEG output will be smaller than the equivalent PNG but with lossy compression
+- The rendering process has a 30-second timeout
+- Page numbering is 1-based (first page is 1, not 0)
+- Temporary files are created in the system temp directory and cleaned up after each request
+
+## Related Documentation
+
+- [PDF to Page PNG](003-pdf-to-page-png.md) - Same extraction in PNG format
+- [Configuration](../configuration.md) - PdftoppmPath and MaxFileSize settings

package/docs/endpoints/README.md

@@ -0,0 +1,75 @@
+# Endpoints
+
+Orator File Translation registers HTTP POST endpoints for file format
+conversion. Each endpoint accepts raw binary data in the request body
+and returns the converted file in the response.
+
+## Endpoint Reference
+
+| # | Endpoint | Input | Output | Description |
+|---|----------|-------|--------|-------------|
+| 001 | [JPG to PNG](001-jpg-to-png.md) | JPEG image | PNG image | Convert JPEG images to PNG format |
+| 002 | [PNG to JPG](002-png-to-jpg.md) | PNG image | JPEG image | Convert PNG images to JPEG format |
+| 003 | [PDF to Page PNG](003-pdf-to-page-png.md) | PDF document | PNG image | Extract a PDF page as a PNG image |
+| 004 | [PDF to Page JPG](004-pdf-to-page-jpg.md) | PDF document | JPEG image | Extract a PDF page as a JPEG image |
+
+## Endpoint Categories
+
+### Image Conversion
+
+Convert between common image formats using Sharp:
+
+- **[JPG to PNG](001-jpg-to-png.md)** - Lossless output from lossy input
+- **[PNG to JPG](002-png-to-jpg.md)** - Lossy compression from lossless input
+
+### PDF Page Extraction
+
+Extract individual pages from PDF documents as images using pdftoppm:
+
+- **[PDF to Page PNG](003-pdf-to-page-png.md)** - Lossless page extraction
+- **[PDF to Page JPG](004-pdf-to-page-jpg.md)** - Lossy page extraction
+
+## Route Structure
+
+All endpoints follow the same versioned route pattern:
+
+```
+POST {RoutePrefix}/{Version}/{converterPath}
+```
+
+With default settings this becomes:
+
+```
+POST /conversion/1.0/{converterPath}
+```
+
+## Common Request Format
+
+All endpoints accept binary data via HTTP POST:
+
+```bash
+curl -X POST --data-binary @inputfile \
+	-H "Content-Type: application/octet-stream" \
+	http://localhost:8080/conversion/1.0/{converterPath} \
+	-o outputfile
+```
+
+## Common Response Codes
+
+| Status | Meaning |
+|--------|---------|
+| 200 | Conversion successful, response body contains the converted file |
+| 400 | No file data provided in the request body |
+| 413 | File exceeds the configured maximum file size |
+| 500 | Conversion failed (invalid input data, missing dependencies, etc.) |
+
+## Custom Endpoints
+
+You can register additional endpoints using `addConverter()`. See the
+[API Reference](../api-reference.md) for details.
+
+## Related Documentation
+
+- [Getting Started](../getting-started.md) - Setup and installation
+- [Configuration](../configuration.md) - Route prefix, version, and size limits
+- [API Reference](../api-reference.md) - Full method documentation