npm package: @jeninho/snapforge
Description: Official Node.js client for SnapForge API. Generate QR codes, OG images, PDFs, extract metadata, resize images, and create placeholders from one API.
Author: Jerome T.
Latest version: 1.0.3

# SnapForge — Six image tools. One URL.

Official Node.js client for [SnapForge](https://usesnapforge.com), the 6-in-1 developer API.

Generate QR codes, OG images, PDFs, extract URL metadata, resize images, and create placeholders — all from a single API.

**URL mode** means you can generate assets by constructing a URL. No API key, no SDK, no signup. Just paste a URL into an `<img>` tag and it works.

## Install

```bash
npm install @jeninho/snapforge
```

## URL Mode (no API key needed)

The simplest way to use SnapForge. These static methods build URLs you can use directly in HTML:

```javascript
const SnapForge = require('@jeninho/snapforge');

// QR code
const qrUrl = SnapForge.qrUrl('https://example.com', { size: 300, fg: '6366F1' });
// → https://api.usesnapforge.com/qr?text=https%3A%2F%2Fexample.com&size=300&fg=6366F1

// Placeholder image
const phUrl = SnapForge.placeholderUrl(400, 200, '6366F1', 'ffffff', 'Hello');
// → https://api.usesnapforge.com/placeholder/400x200/6366F1/ffffff?text=Hello

// OG image
const ogUrl = SnapForge.ogUrl('blog', { title: 'Hello World', theme: 'dark' });
// → https://api.usesnapforge.com/og/blog?title=Hello+World&theme=dark
```

Use in your HTML:

```html
<img src="https://api.usesnapforge.com/qr?text=hello&size=200" alt="QR code" />
<img src="https://api.usesnapforge.com/placeholder/600x400/6366F1/ffffff" alt="Placeholder" />
<img src="https://api.usesnapforge.com/og/blog?title=My+Post&theme=dark" alt="OG image" />
```

## API Mode (with API key)

For higher rate limits, no watermark, and access to PDF generation:

```javascript
const SnapForge = require('@jeninho/snapforge');
const fs = require('fs');

const snap = new SnapForge('sk_live_YOUR_KEY');

// Generate a QR code (returns Buffer)
const qr = await snap.qr('https://example.com', { size: 300 });
fs.writeFileSync('qr.png', qr);

// Generate an OG image
const og = await snap.og('blog', { title: 'My Post', theme: 'dark' });
fs.writeFileSync('og.png', og);

// Generate a PDF from HTML
const pdf = await snap.pdf({ html: '<h1>Invoice #1042</h1><p>Total: $44.00</p>' });
fs.writeFileSync('invoice.pdf', pdf);

// Extract URL metadata
const meta = await snap.metadata('https://github.com');
console.log(meta.title);       // "GitHub: Let's build from here"
console.log(meta.description);  // "GitHub is where over 100 million..."

// Resize an image
const thumb = await snap.resize('https://picsum.photos/1000', { w: 200, h: 200 });
fs.writeFileSync('thumb.webp', thumb);

// Generate a placeholder
const ph = await snap.placeholder(800, 400, '6366F1', 'ffffff', { text: 'Banner' });
fs.writeFileSync('placeholder.png', ph);
```

## Available Methods

| Method | Auth required | Returns |
|--------|--------------|---------|
| `snap.qr(text, options)` | Yes | Buffer (PNG/SVG) |
| `snap.og(template, data)` | Yes | Buffer (PNG) |
| `snap.pdf(options)` | Yes | Buffer (PDF) |
| `snap.metadata(url)` | Yes | JSON object |
| `snap.resize(imageUrl, options)` | Yes | Buffer (image) |
| `snap.placeholder(w, h, bg, fg, options)` | Yes | Buffer (PNG) |
| `SnapForge.qrUrl(text, options)` | No | URL string |
| `SnapForge.ogUrl(template, params)` | No | URL string |
| `SnapForge.placeholderUrl(w, h, bg, fg, text)` | No | URL string |

## Links

- Website: [usesnapforge.com](https://usesnapforge.com)
- Documentation: [usesnapforge.com/docs](https://usesnapforge.com/docs)
- Playground: [usesnapforge.com/playground](https://usesnapforge.com/playground)

## License

MIT