@qr-styled/node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Manuel Yerena Sosa
+
+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,691 @@
+# 🎨 @qr-styled/node
+
+**Professional QR Code Generator for Node.js**
+
+A powerful Node.js/TypeScript library for generating QR codes with advanced styling options including gradients, rounded modules, and logo support.
+
+> 💡 **Looking for browser support?** Check out [@qr-styled/browser](https://github.com/Luisma92/qr-styled-browser) for frontend/React/Vue applications.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+
+## ✨ Features
+
+- 🎨 **Customizable Styles**: Solid colors or multi-color gradients
+- 🔷 **Rounded Modules**: Smooth, modern edges with radius control
+- 🖼️ **Logo Support**: Add logos with circular or square backgrounds
+- � **Specialized QR Types**: vCard, WiFi, Email, SMS, Geo location
+- 📄 **SVG Export**: Vector format for perfect scalability
+- 👁️ **Eye Customization**: Custom colors and shapes for finder patterns
+- 📏 **Proper Margins**: Standard QR quiet zone support
+- 📦 **Multiple Output Formats**: PNG, JPEG, SVG, Buffer, Data URL, or Canvas
+- 🛠️ **CLI & API**: Use from command line or programmatically
+- ✅ **Built-in Validation**: Options validated automatically
+- 🎯 **Full TypeScript Support**: Complete type definitions included
+- 🔧 **Modular Architecture**: Clean, maintainable code
+
+## �️ Visual Examples
+
+### Advanced Features
+
+<table>
+  <tr>
+    <td align="center" valign="top">
+      <img src="docs/images/vcard-contact.png" width="180" alt="vCard Contact QR"/>
+      <br/>
+      <b>vCard Contact</b>
+      <br/>
+      <sub>Purple gradient with custom eyes</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/wifi-network.png" width="180" alt="WiFi Network QR"/>
+      <br/>
+      <b>WiFi Network</b>
+      <br/>
+      <sub>Green gradient with rounded modules</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/email-contact.png" width="180" alt="Email Contact QR"/>
+      <br/>
+      <b>Email Contact</b>
+      <br/>
+      <sub>Pink gradient with eye customization</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/custom-eyes.png" width="180" alt="Custom Eyes QR"/>
+      <br/>
+      <b>Custom Eyes</b>
+      <br/>
+      <sub>Red eye accents (square modules)</sub>
+    </td>
+  </tr>
+</table>
+
+### Basic Styles
+
+<table>
+  <tr>
+    <td align="center" valign="top">
+      <img src="docs/images/basic-classic.png" width="150" alt="Classic Black & White QR"/>
+      <br/>
+      <b>Classic</b>
+      <br/>
+      <sub>Traditional black & white</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/basic-blue.png" width="150" alt="Professional Blue QR"/>
+      <br/>
+      <b>Professional</b>
+      <br/>
+      <sub>Blue rounded design</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/basic-green.png" width="150" alt="Eco Green QR"/>
+      <br/>
+      <b>Eco</b>
+      <br/>
+      <sub>Green with custom eyes</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/basic-red.png" width="150" alt="Alert Red QR"/>
+      <br/>
+      <b>Alert</b>
+      <br/>
+      <sub>Red attention-grabbing</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/basic-purple.png" width="150" alt="Creative Purple QR"/>
+      <br/>
+      <b>Creative</b>
+      <br/>
+      <sub>Purple artistic</sub>
+    </td>
+  </tr>
+</table>
+
+### With Logos
+
+<table>
+  <tr>
+    <td align="center" valign="top">
+      <img src="docs/images/logo-corporate.png" width="160" alt="Corporate QR with Logo"/>
+      <br/>
+      <b>Corporate</b>
+      <br/>
+      <sub>Circle logo, professional blue</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/logo-eco.png" width="160" alt="Eco Brand QR with Logo"/>
+      <br/>
+      <b>Eco Brand</b>
+      <br/>
+      <sub>Square logo, green gradient</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/logo-tech.png" width="160" alt="Tech Startup QR with Logo"/>
+      <br/>
+      <b>Tech Startup</b>
+      <br/>
+      <sub>Circle logo, purple gradient</sub>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/logo-restaurant.png" width="160" alt="Restaurant QR with Logo"/>
+      <br/>
+      <b>Restaurant</b>
+      <br/>
+      <sub>Square logo, red gradient</sub>
+    </td>
+  </tr>
+</table>
+
+> 💡 **Tip**: All examples shown above were generated with this library! Check the [`examples/`](examples/) directory for source code.
+
+## �📦 Installation
+
+```bash
+npm install @qr-styled/node
+```
+
+Or for global CLI usage:
+
+```bash
+npm install -g @qr-styled/node
+```
+
+## 🚀 Quick Start
+
+### CLI Usage
+
+```bash
+# Basic QR code
+qr-styled --url "https://github.com"
+
+# QR with gradient
+qr-styled --url "https://github.com" --gradient
+
+# QR with logo
+qr-styled --url "https://github.com" --logo ./my-logo.png --out my-qr.png
+```
+
+### Library Usage
+
+```typescript
+import { QRGenerator, generateQRToFile } from '@qr-styled/node';
+
+// Basic URL QR code
+const generator = new QRGenerator({
+  url: 'https://github.com',
+  gradient: true,
+  gradientColors: '#667eea,#764ba2'
+});
+
+await generator.generateToFile('qr-output.png');
+
+// vCard contact QR code
+const vCardGenerator = new QRGenerator({
+  type: 'vcard',
+  data: {
+    firstName: 'John',
+    lastName: 'Doe',
+    phone: '+1234567890',
+    email: 'john@example.com',
+    organization: 'Tech Corp'
+  }
+});
+
+await vCardGenerator.generateToFile('contact-qr.png');
+
+// WiFi QR code
+const wifiGenerator = new QRGenerator({
+  type: 'wifi',
+  data: {
+    ssid: 'MyNetwork',
+    password: 'SecurePassword123',
+    encryption: 'WPA'
+  }
+});
+
+await wifiGenerator.generateToFile('wifi-qr.png');
+
+// SVG export for scalability
+const svgGenerator = new QRGenerator({
+  url: 'https://example.com',
+  foregroundColor: '#2196F3',
+  eyeColor: '#FF5722',
+  eyeRadius: 0.4
+});
+
+const svg = await svgGenerator.generateToSVG();
+await svgGenerator.generateToSVGFile('qr.svg');
+
+// Helper function
+await generateQRToFile(
+  {
+    url: 'https://github.com',
+    foregroundColor: '#2d3748'
+  },
+  'qr-output.png'
+);
+```
+
+## 📖 Documentation
+
+### Configuration Options
+
+#### Basic Options
+
+| Option            | Type         | Default      | Description                                            |
+| ----------------- | ------------ | ------------ | ------------------------------------------------------ |
+| `url`             | `string`     | _optional_   | URL or text content                                    |
+| `type`            | `QRDataType` | `'text'`     | QR data type (url, text, vcard, wifi, email, sms, geo) |
+| `data`            | `object`     | _optional_   | Structured data for specialized types                  |
+| `size`            | `number`     | `600`        | Canvas size in pixels                                  |
+| `margin`          | `number`     | `4`          | Quiet zone margin (4 modules standard)                 |
+| `padding`         | `number`     | `40`         | Canvas padding in pixels                               |
+| `foregroundColor` | `string`     | `'#000000'`  | QR code color (hex format)                             |
+| `color`           | `string`     | _deprecated_ | Use `foregroundColor` instead                          |
+| `rounded`         | `boolean`    | `true`       | Use rounded module corners                             |
+| `moduleRadius`    | `number`     | `0.35`       | Corner radius (0.0 - 0.5)                              |
+| `cornerRadius`    | `number`     | `60`         | Background corner radius                               |
+| `backgroundColor` | `string`     | `'#ffffff'`  | Background color                                       |
+
+#### Eye Customization
+
+| Option      | Type     | Default | Description                       |
+| ----------- | -------- | ------- | --------------------------------- |
+| `eyeColor`  | `string` | `''`    | Custom eye (finder pattern) color |
+| `eyeRadius` | `number` | `0`     | Eye corner radius (0.0 - 0.5)     |
+
+#### Gradient Options
+
+| Option           | Type      | Default                 | Description              |
+| ---------------- | --------- | ----------------------- | ------------------------ |
+| `gradient`       | `boolean` | `false`                 | Enable gradient          |
+| `gradientColors` | `string`  | `'#FEDA75,#FA7E1E,...'` | Comma-separated colors   |
+| `gradientAngle`  | `number`  | `45`                    | Angle in degrees (0-360) |
+
+#### Logo Options
+
+| Option                | Type                 | Default     | Description                    |
+| --------------------- | -------------------- | ----------- | ------------------------------ |
+| `logo`                | `string`             | `''`        | Logo image path or URL         |
+| `logoSize`            | `number`             | `120`       | Logo size in pixels            |
+| `logoPadding`         | `number`             | `10`        | Padding around logo            |
+| `logoShape`           | `'circle'\|'square'` | `'circle'`  | Logo background shape          |
+| `logoBackgroundColor` | `string`             | `'#ffffff'` | Logo background color          |
+| `logoRadius`          | `number`             | `20`        | Corner radius for square logos |
+
+### Specialized QR Codes
+
+#### vCard (Contact Card)
+
+```typescript
+{
+  type: 'vcard',
+  data: {
+    firstName: 'John',
+    lastName: 'Doe',
+    organization: 'Tech Corp',
+    title: 'CEO',
+    phone: '+1234567890',
+    email: 'john@example.com',
+    url: 'https://example.com',
+    address: '123 Main St',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'USA'
+  }
+}
+```
+
+#### WiFi Network
+
+```typescript
+{
+  type: 'wifi',
+  data: {
+    ssid: 'MyNetwork',
+    password: 'SecurePassword123',
+    encryption: 'WPA', // 'WPA' | 'WEP' | 'nopass'
+    hidden: false      // optional
+  }
+}
+```
+
+#### Email
+
+```typescript
+{
+  type: 'email',
+  data: {
+    email: 'contact@example.com',
+    subject: 'Hello',    // optional
+    body: 'Message text' // optional
+  }
+}
+```
+
+#### SMS
+
+```typescript
+{
+  type: 'sms',
+  data: {
+    phone: '+1234567890',
+    message: 'Hello!'  // optional
+  }
+}
+```
+
+#### Geo Location
+
+```typescript
+{
+  type: 'geo',
+  data: {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+}
+```
+
+| `logoRadius` | `number` | `20` | Corner radius (for square) |
+
+### API Reference
+
+#### `QRGenerator`
+
+Main class for generating QR codes.
+
+```typescript
+import { QRGenerator } from '@qr-styled/node';
+
+const generator = new QRGenerator(options);
+```
+
+##### Methods
+
+###### `generate()`
+
+Generates QR code and returns the canvas.
+
+```typescript
+const canvas = await generator.generate();
+```
+
+###### `generateToFile(outputPath)`
+
+Generates and saves QR code to file.
+
+```typescript
+await generator.generateToFile('output.png');
+```
+
+###### `generateToBuffer(format)`
+
+Generates and returns a Buffer (useful for APIs/servers).
+
+```typescript
+const buffer = await generator.generateToBuffer('png');
+// In Express: res.type('png').send(buffer)
+```
+
+###### `generateToDataURL(format)`
+
+Generates and returns a Data URL (useful for HTML).
+
+```typescript
+const dataURL = await generator.generateToDataURL('png');
+// In HTML: <img src="${dataURL}" />
+```
+
+###### `updateOptions(options)`
+
+Updates generator options.
+
+```typescript
+generator.updateOptions({ gradient: true });
+await generator.generateToFile('updated.png');
+```
+
+#### Helper Functions
+
+##### `generateQR(options)`
+
+Quickly generate a QR code and return the canvas.
+
+```typescript
+import { generateQR } from '@qr-styled/node';
+
+const canvas = await generateQR({ url: 'https://example.com' });
+```
+
+##### `generateQRToFile(options, outputPath)`
+
+Generate and save a QR code to file.
+
+```typescript
+import { generateQRToFile } from '@qr-styled/node';
+
+await generateQRToFile(
+  { url: 'https://example.com', gradient: true },
+  'output.png'
+);
+```
+
+## 💻 Usage Examples
+
+### Example 1: Instagram Gradient QR
+
+```typescript
+const generator = new QRGenerator({
+  url: 'https://instagram.com/your-profile',
+  gradient: true,
+  gradientColors: '#FEDA75,#FA7E1E,#D62976,#962FBF,#4F5BD5',
+  gradientAngle: 45,
+  rounded: true
+});
+
+await generator.generateToFile('instagram-qr.png');
+```
+
+### Example 2: Corporate QR with Logo
+
+```typescript
+const generator = new QRGenerator({
+  url: 'https://your-company.com',
+  foregroundColor: '#1a365d',
+  logo: './company-logo.png',
+  logoShape: 'square',
+  logoRadius: 15,
+  backgroundColor: '#f7fafc'
+});
+
+await generator.generateToFile('company-qr.png');
+```
+
+### Example 3: QR for HTTP API
+
+```typescript
+import express from 'express';
+import { QRGenerator } from '@qr-styled/node';
+
+const app = express();
+
+app.get('/qr', async (req, res) => {
+  const generator = new QRGenerator({
+    url: req.query.url,
+    gradient: true,
+    gradientColors: '#667eea,#764ba2'
+  });
+
+  const buffer = await generator.generateToBuffer('png');
+  res.type('png').send(buffer);
+});
+
+app.listen(3000);
+```
+
+### Example 4: Dynamic QR in Frontend
+
+```typescript
+// In your Node.js server
+app.get('/api/qr-data', async (req, res) => {
+  const generator = new QRGenerator({
+    url: 'https://example.com',
+    gradient: true
+  });
+
+  const dataURL = await generator.generateToDataURL('png');
+  res.json({ qrCode: dataURL });
+});
+
+// In your frontend (React, Vue, etc.)
+fetch('/api/qr-data')
+  .then(res => res.json())
+  .then(data => {
+    document.getElementById('qr').src = data.qrCode;
+  });
+```
+
+## 🔧 CLI
+
+### Global Installation
+
+```bash
+npm install -g @qr-styled/node
+```
+
+### Available Commands
+
+```bash
+# Available commands
+qr-styled [options]
+qrgen [options]  # Short alias
+```
+
+### CLI Examples
+
+```bash
+# Basic QR
+qr-styled --url "https://github.com"
+
+# Custom filename
+qr-styled --url "https://github.com" --out my-code.png
+
+# QR with gradient
+qr-styled --url "https://github.com" --gradient --gradientColors "#ff6b6b,#ee5a6f"
+
+# QR with logo
+qr-styled --url "https://github.com" --logo ./logo.png --logoShape square
+
+# QR with all options
+qr-styled \
+  --url "https://github.com" \
+  --size 800 \
+  --gradient \
+  --gradientColors "#667eea,#764ba2" \
+  --gradientAngle 90 \
+  --logo ./logo.png \
+  --logoShape circle \
+  --out custom-qr.png
+```
+
+### Help
+
+```bash
+qr-styled --help
+```
+
+## 🏗️ Architecture
+
+```
+src/
+├── index.ts                    # Main entry point
+├── lib/
+│   ├── QRGenerator.ts         # Main class
+│   ├── renderers/             # Rendering modules
+│   │   ├── BackgroundRenderer.ts
+│   │   ├── GradientRenderer.ts
+│   │   ├── ModuleRenderer.ts
+│   │   └── LogoRenderer.ts
+│   └── utils/                 # Utilities
+│       ├── types.ts
+│       └── validators.ts
+└── cli/
+    └── index.ts               # Command line interface
+```
+
+### Design Principles
+
+- **Separation of Concerns**: Each renderer handles a specific function
+- **Composition over Inheritance**: Renderers are composed in QRGenerator
+- **Input Validation**: All options validated before processing
+- **Flexible API**: Supports multiple output formats
+- **Clean Code**: Complete TypeScript types and documentation
+
+## 🧪 Included Examples
+
+The project includes complete examples you can run:
+
+```bash
+# Basic examples
+npm run example:basic
+
+# Programmatic usage examples
+npm run example:programmatic
+```
+
+Examples will generate files in `examples/output/` for you to review.
+
+## 🤝 Framework Integration
+
+### Express.js
+
+```typescript
+app.get('/qr/:text', async (req, res) => {
+  const generator = new QRGenerator({ url: req.params.text });
+  const buffer = await generator.generateToBuffer();
+  res.type('png').send(buffer);
+});
+```
+
+### Next.js (API Route)
+
+```typescript
+// pages/api/qr.ts
+import { QRGenerator } from '@qr-styled/node';
+
+export default async function handler(req, res) {
+  const { url } = req.query;
+  const generator = new QRGenerator({ url });
+  const buffer = await generator.generateToBuffer();
+
+  res.setHeader('Content-Type', 'image/png');
+  res.send(buffer);
+}
+```
+
+### Fastify
+
+```typescript
+fastify.get('/qr', async (request, reply) => {
+  const generator = new QRGenerator({ url: request.query.url });
+  const buffer = await generator.generateToBuffer();
+
+  reply.type('image/png').send(buffer);
+});
+```
+
+## 🛠️ Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev -- --url "https://example.com"
+```
+
+### Run Examples
+
+```bash
+npm run example:basic
+npm run example:programmatic
+```
+
+## 📄 License
+
+MIT © Luis Manuel Yerena Sosa
+
+## 🙏 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the project
+2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## 🐛 Report Issues
+
+If you find a bug or have a suggestion, please [open an issue](https://github.com/Luisma92/@qr-styled/node/issues).
+
+## 📚 Resources
+
+- [QRCode Documentation](https://github.com/soldair/node-qrcode)
+- [Canvas API](https://github.com/Automattic/node-canvas)
+- [QR Code Specification](https://www.qrcode.com/en/about/)
+
+---
+
+**⭐ If you find this project useful, consider giving it a star on GitHub!**