siteforge-pdf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SiteForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# SiteForge PDF
+
+Official Node.js SDK for [SiteForge PDF](https://pdf.siteforge.build) — simple HTML to PDF conversion API.
+
+- ⚡ **100 free conversions/month**
+- 💳 **Pay-as-you-go**: $0.02 per conversion after free tier
+- 🚀 **Fast**: Sub-second conversion times
+- 📄 **Simple**: Just send HTML, get PDF
+
+## Installation
+
+```bash
+npm install siteforge-pdf
+```
+
+## Quick Start
+
+```javascript
+const pdf = require('siteforge-pdf');
+const fs = require('fs');
+
+// Initialize with your API key
+const client = pdf('sf_pdf_your_api_key');
+
+// Convert HTML to PDF
+const buffer = await client.convert('<h1>Hello World</h1>');
+fs.writeFileSync('hello.pdf', buffer);
+```
+
+## Get Your API Key
+
+1. Sign up at [pdf.siteforge.build](https://pdf.siteforge.build)
+2. Get your API key from the dashboard
+3. Start converting!
+
+## Usage
+
+### Convert HTML
+
+```javascript
+const pdf = require('siteforge-pdf');
+const client = pdf('sf_pdf_your_key');
+
+// Simple HTML
+const buffer = await client.convert('<h1>Invoice #123</h1><p>Amount: $100</p>');
+
+// With options
+const buffer = await client.convert(html, {
+    format: 'Letter',      // A4, Letter, Legal
+    landscape: true,       // Landscape orientation
+    margin: 'small',       // none, small, default, large
+    printBackground: true  // Include background colors/images
+});
+
+fs.writeFileSync('invoice.pdf', buffer);
+```
+
+### Convert URL
+
+```javascript
+// Convert any public URL to PDF
+const buffer = await client.convertUrl('https://example.com');
+
+// With options
+const buffer = await client.convertUrl('https://example.com', {
+    format: 'A4',
+    waitMs: 1000  // Wait for JS to render
+});
+
+fs.writeFileSync('example.pdf', buffer);
+```
+
+### Check Usage
+
+```javascript
+const usage = await client.usage();
+console.log(usage);
+// {
+//   plan: 'free',
+//   period: '2024-01',
+//   currentMonth: { conversions: 42, ... },
+//   limits: { monthly: 100, remaining: 58 }
+// }
+```
+
+## CLI
+
+The package includes a command-line tool:
+
+```bash
+# Set your API key
+export SITEFORGE_PDF_KEY=sf_pdf_your_key
+
+# Convert HTML
+siteforge-pdf --html "<h1>Hello</h1>" -o hello.pdf
+
+# Convert a file
+siteforge-pdf --file invoice.html -o invoice.pdf
+
+# Convert a URL
+siteforge-pdf --url https://example.com -o example.pdf
+
+# With options
+siteforge-pdf --html "<h1>Report</h1>" -o report.pdf --landscape --format Letter
+
+# Check usage
+siteforge-pdf --usage
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import pdf, { SiteForgePDF, ConvertOptions } from 'siteforge-pdf';
+
+const client: SiteForgePDF = pdf('sf_pdf_your_key');
+
+const options: ConvertOptions = {
+    format: 'A4',
+    landscape: false
+};
+
+const buffer: Buffer = await client.convert('<h1>Hello</h1>', options);
+```
+
+## Options
+
+### Client Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | string | `https://pdf.siteforge.build` | API base URL |
+| `timeout` | number | `60000` | Request timeout in ms |
+
+### Convert Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | string | `'A4'` | Page format: A4, Letter, Legal |
+| `landscape` | boolean | `false` | Landscape orientation |
+| `margin` | string | `'default'` | Margin: none, small, default, large |
+| `printBackground` | boolean | `true` | Include background graphics |
+| `waitMs` | number | `0` | Wait before capture (for JS rendering) |
+
+## Error Handling
+
+```javascript
+const pdf = require('siteforge-pdf');
+const client = pdf('sf_pdf_your_key');
+
+try {
+    const buffer = await client.convert('<h1>Hello</h1>');
+    fs.writeFileSync('output.pdf', buffer);
+} catch (err) {
+    if (err.statusCode === 401) {
+        console.error('Invalid API key');
+    } else if (err.statusCode === 429) {
+        console.error('Rate limit exceeded');
+    } else {
+        console.error('Conversion failed:', err.message);
+    }
+}
+```
+
+## Pricing
+
+| Plan | Monthly Conversions | Price |
+|------|---------------------|-------|
+| Free | 100 | $0 |
+| Pay-as-you-go | Unlimited | $0.02 each |
+
+Free tier includes a small watermark. Upgrade to PAYG for watermark-free PDFs.
+
+## Links
+
+- 🌐 [Website](https://pdf.siteforge.build)
+- 📖 [API Docs](https://pdf.siteforge.build/docs)
+- 🐛 [Issues](https://github.com/rmoen/siteforge-pdf-node/issues)
+
+## License
+
+MIT © [SiteForge](https://siteforge.build)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "siteforge-pdf",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for SiteForge PDF - HTML to PDF conversion API",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "bin": {
+    "siteforge-pdf": "src/cli.js"
+  },
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "pdf",
+    "html-to-pdf",
+    "html2pdf",
+    "pdf-generation",
+    "siteforge",
+    "convert",
+    "document",
+    "api"
+  ],
+  "author": "SiteForge <support@siteforge.build>",
+  "license": "MIT",
+  "homepage": "https://pdf.siteforge.build",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmoen/siteforge-pdf-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rmoen/siteforge-pdf-node/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "src/cli.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+/**
+ * SiteForge PDF CLI
+ * 
+ * Usage:
+ *   siteforge-pdf --html "<h1>Hello</h1>" -o output.pdf
+ *   siteforge-pdf --url https://example.com -o output.pdf
+ *   siteforge-pdf --usage
+ */
+
+const fs = require('fs');
+const path = require('path');
+const createClient = require('./index');
+
+const HELP = `
+SiteForge PDF - HTML to PDF Conversion
+
+Usage:
+  siteforge-pdf [options]
+
+Options:
+  --html <string>     HTML content to convert
+  --file <path>       HTML file to convert
+  --url <url>         URL to convert
+  -o, --output <path> Output PDF path (default: output.pdf)
+  --format <format>   Page format: A4, Letter, Legal (default: A4)
+  --landscape         Use landscape orientation
+  --no-background     Disable background graphics
+  --usage             Show usage statistics
+  --key <key>         API key (or set SITEFORGE_PDF_KEY env var)
+  -h, --help          Show this help
+
+Examples:
+  siteforge-pdf --html "<h1>Hello World</h1>" -o hello.pdf
+  siteforge-pdf --file invoice.html -o invoice.pdf
+  siteforge-pdf --url https://example.com -o example.pdf --landscape
+  siteforge-pdf --usage
+
+Get your API key at https://pdf.siteforge.build
+`;
+
+function parseArgs(args) {
+    const opts = {
+        output: 'output.pdf',
+        format: 'A4',
+        landscape: false,
+        printBackground: true
+    };
+    
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        
+        switch (arg) {
+            case '-h':
+            case '--help':
+                opts.help = true;
+                break;
+            case '--html':
+                opts.html = next;
+                i++;
+                break;
+            case '--file':
+                opts.file = next;
+                i++;
+                break;
+            case '--url':
+                opts.url = next;
+                i++;
+                break;
+            case '-o':
+            case '--output':
+                opts.output = next;
+                i++;
+                break;
+            case '--format':
+                opts.format = next;
+                i++;
+                break;
+            case '--landscape':
+                opts.landscape = true;
+                break;
+            case '--no-background':
+                opts.printBackground = false;
+                break;
+            case '--usage':
+                opts.usage = true;
+                break;
+            case '--key':
+                opts.key = next;
+                i++;
+                break;
+        }
+    }
+    
+    return opts;
+}
+
+async function main() {
+    const args = process.argv.slice(2);
+    
+    if (args.length === 0) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    
+    const opts = parseArgs(args);
+    
+    if (opts.help) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    
+    // Get API key
+    const apiKey = opts.key || process.env.SITEFORGE_PDF_KEY;
+    if (!apiKey) {
+        console.error('Error: API key required. Use --key or set SITEFORGE_PDF_KEY env var');
+        console.error('Get your key at https://pdf.siteforge.build');
+        process.exit(1);
+    }
+    
+    const client = createClient(apiKey);
+    
+    try {
+        // Usage check
+        if (opts.usage) {
+            const usage = await client.usage();
+            console.log('\nSiteForge PDF Usage\n');
+            console.log(`Plan: ${usage.plan}`);
+            console.log(`Period: ${usage.period}`);
+            console.log(`Conversions this month: ${usage.currentMonth.conversions}`);
+            if (usage.limits.monthly) {
+                console.log(`Remaining: ${usage.limits.remaining}/${usage.limits.monthly}`);
+            }
+            if (usage.plan === 'payg') {
+                console.log(`Estimated cost: $${usage.currentMonth.estimatedCost}`);
+            }
+            console.log(`All-time conversions: ${usage.allTime.conversions}`);
+            return;
+        }
+        
+        // Get HTML content
+        let html = opts.html;
+        if (opts.file) {
+            html = fs.readFileSync(opts.file, 'utf8');
+        }
+        
+        // Convert
+        let buffer;
+        const convertOpts = {
+            format: opts.format,
+            landscape: opts.landscape,
+            printBackground: opts.printBackground
+        };
+        
+        if (opts.url) {
+            console.log(`Converting URL: ${opts.url}`);
+            buffer = await client.convertUrl(opts.url, convertOpts);
+        } else if (html) {
+            console.log('Converting HTML...');
+            buffer = await client.convert(html, convertOpts);
+        } else {
+            console.error('Error: Provide --html, --file, or --url');
+            process.exit(1);
+        }
+        
+        // Write output
+        const outputPath = path.resolve(opts.output);
+        fs.writeFileSync(outputPath, buffer);
+        console.log(`✓ PDF saved: ${outputPath} (${(buffer.length / 1024).toFixed(1)} KB)`);
+        
+    } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+main();

package/src/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * SiteForge PDF - TypeScript Definitions
+ */
+
+export interface ConvertOptions {
+    /** Page format: A4, Letter, Legal (default: A4) */
+    format?: 'A4' | 'Letter' | 'Legal';
+    /** Landscape orientation (default: false) */
+    landscape?: boolean;
+    /** Margin size (default: 'default') */
+    margin?: 'none' | 'small' | 'default' | 'large';
+    /** Include background graphics (default: true) */
+    printBackground?: boolean;
+    /** Wait time before capture in ms (for convertUrl) */
+    waitMs?: number;
+}
+
+export interface ClientOptions {
+    /** API base URL (default: https://pdf.siteforge.build) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 60000) */
+    timeout?: number;
+}
+
+export interface UsageStats {
+    plan: 'free' | 'payg' | 'pro';
+    period: string;
+    currentMonth: {
+        conversions: number;
+        totalBytes: number;
+        avgProcessingMs: number;
+        estimatedCost: string;
+    };
+    allTime: {
+        conversions: number;
+        totalBytes: number;
+    };
+    limits: {
+        monthly: number | null;
+        remaining: number | null;
+    };
+}
+
+export interface HealthStatus {
+    status: 'ok' | 'error';
+    service: string;
+}
+
+export declare class SiteForgePDF {
+    constructor(apiKey: string, options?: ClientOptions);
+    
+    /**
+     * Convert HTML to PDF
+     */
+    convert(html: string, options?: ConvertOptions): Promise<Buffer>;
+    
+    /**
+     * Convert a URL to PDF
+     */
+    convertUrl(url: string, options?: ConvertOptions): Promise<Buffer>;
+    
+    /**
+     * Get usage statistics
+     */
+    usage(): Promise<UsageStats>;
+    
+    /**
+     * Health check
+     */
+    health(): Promise<HealthStatus>;
+}
+
+/**
+ * Create a SiteForge PDF client
+ */
+declare function createClient(apiKey: string, options?: ClientOptions): SiteForgePDF;
+
+export { createClient };
+export default createClient;

package/src/index.js

@@ -0,0 +1,179 @@
+/**
+ * SiteForge PDF - Official Node.js SDK
+ * https://pdf.siteforge.build
+ * 
+ * Simple HTML to PDF conversion API
+ */
+
+const https = require('https');
+const http = require('http');
+
+const DEFAULT_BASE_URL = 'https://pdf.siteforge.build';
+
+class SiteForgePDF {
+    /**
+     * Create a SiteForge PDF client
+     * @param {string} apiKey - Your API key (starts with sf_pdf_)
+     * @param {object} options - Optional configuration
+     * @param {string} options.baseUrl - API base URL (default: https://pdf.siteforge.build)
+     * @param {number} options.timeout - Request timeout in ms (default: 60000)
+     */
+    constructor(apiKey, options = {}) {
+        if (!apiKey) {
+            throw new Error('API key is required. Get one at https://pdf.siteforge.build');
+        }
+        if (!apiKey.startsWith('sf_pdf_')) {
+            throw new Error('Invalid API key format. Keys start with sf_pdf_');
+        }
+        
+        this.apiKey = apiKey;
+        this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+        this.timeout = options.timeout || 60000;
+    }
+
+    /**
+     * Make an API request
+     * @private
+     */
+    _request(method, path, body = null, expectBinary = false) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(path, this.baseUrl);
+            const isHttps = url.protocol === 'https:';
+            const client = isHttps ? https : http;
+            
+            const options = {
+                hostname: url.hostname,
+                port: url.port || (isHttps ? 443 : 80),
+                path: url.pathname + url.search,
+                method,
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': 'siteforge-pdf-node/1.0.0'
+                },
+                timeout: this.timeout
+            };
+
+            const req = client.request(options, (res) => {
+                const chunks = [];
+                
+                res.on('data', chunk => chunks.push(chunk));
+                res.on('end', () => {
+                    const buffer = Buffer.concat(chunks);
+                    
+                    if (res.statusCode >= 400) {
+                        let error;
+                        try {
+                            const json = JSON.parse(buffer.toString());
+                            error = new Error(json.error || `HTTP ${res.statusCode}`);
+                        } catch {
+                            error = new Error(`HTTP ${res.statusCode}: ${buffer.toString()}`);
+                        }
+                        error.statusCode = res.statusCode;
+                        reject(error);
+                        return;
+                    }
+                    
+                    if (expectBinary) {
+                        resolve(buffer);
+                    } else {
+                        try {
+                            resolve(JSON.parse(buffer.toString()));
+                        } catch {
+                            resolve(buffer.toString());
+                        }
+                    }
+                });
+            });
+
+            req.on('error', reject);
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Request timed out'));
+            });
+
+            if (body) {
+                req.write(JSON.stringify(body));
+            }
+            req.end();
+        });
+    }
+
+    /**
+     * Convert HTML to PDF
+     * @param {string} html - HTML content to convert
+     * @param {object} options - Conversion options
+     * @param {string} options.format - Page format: A4, Letter, Legal (default: A4)
+     * @param {boolean} options.landscape - Landscape orientation (default: false)
+     * @param {string} options.margin - Margin size: none, small, default, large
+     * @param {boolean} options.printBackground - Include background graphics (default: true)
+     * @returns {Promise<Buffer>} PDF as a Buffer
+     */
+    async convert(html, options = {}) {
+        if (!html || typeof html !== 'string') {
+            throw new Error('HTML content is required');
+        }
+
+        const body = {
+            html,
+            ...options
+        };
+
+        return this._request('POST', '/v1/convert', body, true);
+    }
+
+    /**
+     * Convert a URL to PDF
+     * @param {string} url - URL to convert
+     * @param {object} options - Conversion options
+     * @param {string} options.format - Page format: A4, Letter, Legal (default: A4)
+     * @param {boolean} options.landscape - Landscape orientation (default: false)
+     * @param {string} options.margin - Margin size: none, small, default, large
+     * @param {boolean} options.printBackground - Include background graphics (default: true)
+     * @param {number} options.waitMs - Wait time before capture in ms (default: 0)
+     * @returns {Promise<Buffer>} PDF as a Buffer
+     */
+    async convertUrl(url, options = {}) {
+        if (!url || typeof url !== 'string') {
+            throw new Error('URL is required');
+        }
+
+        const body = {
+            url,
+            ...options
+        };
+
+        return this._request('POST', '/v1/convert', body, true);
+    }
+
+    /**
+     * Get usage statistics
+     * @returns {Promise<object>} Usage stats including conversions, limits, costs
+     */
+    async usage() {
+        return this._request('GET', '/v1/usage');
+    }
+
+    /**
+     * Health check
+     * @returns {Promise<object>} Service status
+     */
+    async health() {
+        return this._request('GET', '/health');
+    }
+}
+
+/**
+ * Create a SiteForge PDF client
+ * @param {string} apiKey - Your API key
+ * @param {object} options - Optional configuration
+ * @returns {SiteForgePDF}
+ */
+function createClient(apiKey, options) {
+    return new SiteForgePDF(apiKey, options);
+}
+
+// Allow both: require('siteforge-pdf')('key') and require('siteforge-pdf').createClient('key')
+module.exports = createClient;
+module.exports.createClient = createClient;
+module.exports.SiteForgePDF = SiteForgePDF;