QRVerse 🎯

A comprehensive QR code generation framework with advanced features including dynamic QR codes, analytics, security, and extensive customization options.

✨ Features

• 🔄 Static & Dynamic QR Codes - Generate traditional static QR codes or dynamic ones with changeable destinations
• 🔐 Security Features - Password protection and AES encryption for sensitive data
• ⏰ Expiration Control - Set expiration dates for time-sensitive QR codes
• 🎨 Visual Customization - Colors, gradients, logos, frames, and various shapes
• 📱 Pre-built Templates - 12+ beautiful templates ready to use
• 📊 Analytics Dashboard - Track scans, locations, devices, and performance metrics
• 📧 Automated Reports - Schedule daily, weekly, or monthly email reports
• 🎫 Single-Use Codes - Perfect for tickets, coupons, and vouchers
• 🌍 Geographic Tracking - Track scan locations by country, region, and city
• 📱 Device Detection - Identify device types, OS, and browsers
• 🔒 Encryption Support - Encrypt QR code content with custom keys
• ⚡ Batch Processing - Generate multiple QR codes efficiently

🚀 Quick Start

Installation

npm install qrverse

Basic Usage

import QRVerse from 'qrverse';

// Initialize QRVerse
const qrverse = new QRVerse({
  baseUrl: 'https://your-domain.com',
  analytics: {
    enabled: true,
    trackLocation: true,
    trackDevice: true,
  },
});

// Generate a simple QR code
const result = await qrverse.generateQR({
  data: 'https://example.com',
  size: 300,
});

console.log('QR Code generated:', result.id);
// result.qrCode contains the PNG buffer

📖 Comprehensive Examples

1. Static QR Code with Customization

const customQR = await qrverse.generateQR({
  data: 'https://mywebsite.com',
  type: 'static',
  size: 400,
  customization: {
    foregroundColor: '#2C3E50',
    backgroundColor: '#ECF0F1',
    logo: {
      src: './logo.png',
      size: 60,
      margin: 10,
    },
    frame: {
      type: 'rounded',
      color: '#3498DB',
      thickness: 5,
    },
    dotStyle: 'circle',
    shape: 'rounded',
  },
});

2. Dynamic QR Code with Security

const dynamicQR = await qrverse.generateQR({
  data: 'https://changeable-destination.com',
  type: 'dynamic',
  security: {
    password: 'mySecretPassword',
    encryption: true,
    encryptionKey: 'my-custom-key-32-chars-long',
  },
  expiration: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
});

// Later, update the destination
await qrverse.updateDynamicQR(dynamicQR.id, 'https://new-destination.com');

3. Using Templates

// Get all available templates
const templates = qrverse.getTemplates();

// Use a pre-built template
const templateQR = await qrverse.generateQR({
  data: 'https://business-site.com',
  template: 'corporate-gray',
  customization: {
    logo: {
      src: './company-logo.png',
      size: 50,
    },
  },
});

// Get business-specific templates
const businessTemplates = qrverse.getBusinessTemplates();

4. Single-Use QR Code for Tickets

const ticketQR = await qrverse.generateQR({
  data: 'TICKET-12345',
  singleUse: true,
  template: 'golden-luxury',
  expiration: new Date('2024-12-31T23:59:59Z'),
  security: {
    encryption: true,
  },
});

5. Batch Generation

const batchOptions = [
  { data: 'https://product1.com', template: 'modern-blue' },
  { data: 'https://product2.com', template: 'vibrant-sunset' },
  { data: 'https://product3.com', template: 'forest-green' },
];

const batchResults = await qrverse.generateBatch(batchOptions);
console.log(`Generated ${batchResults.length} QR codes`);

📊 Analytics & Tracking

Recording Scans

// Record a scan (typically called from your redirect endpoint)
const scanRecorded = await qrverse.recordScan(
  qrId,
  req.ip,
  req.headers['user-agent']
);

Getting Analytics

// Get analytics for a specific QR code
const analytics = await qrverse.getAnalytics(qrId);
console.log({
  totalScans: analytics.totalScans,
  uniqueScans: analytics.uniqueScans,
  scansByDate: analytics.scansByDate,
  scansByLocation: analytics.scansByLocation,
  scansByDevice: analytics.scansByDevice,
});

// Get top performers
const topQRs = await qrverse.getTopPerformers(10);

// Get scan trends
const trends = await qrverse.getScanTrends(30); // Last 30 days

// Get geographic distribution
const geoDistribution = await qrverse.getGeographicDistribution();

📧 Automated Reports

Setup Email Configuration

const qrverse = new QRVerse({
  email: {
    service: 'gmail', // or 'outlook', 'yahoo', etc.
    user: 'your-email@gmail.com',
    pass: 'your-app-password',
  },
});

Schedule Reports

// Schedule a weekly report
qrverse.scheduleReport('weekly-report', {
  frequency: 'weekly',
  email: 'manager@company.com',
  qrIds: ['qr1', 'qr2', 'qr3'], // Optional: specific QR codes
  includeCharts: true,
});

// Generate immediate report
await qrverse.generateReport({
  frequency: 'daily',
  email: 'admin@company.com',
});

// Generate CSV export
const csvData = await qrverse.generateCSVReport({
  frequency: 'monthly',
  email: 'data@company.com',
});

🎨 Available Templates

QRVerse comes with 12+ pre-built templates:

• classic - Traditional black and white
• modern-blue - Clean blue gradient with rounded corners
• vibrant-sunset - Warm sunset gradient with circular design
• corporate-gray - Professional gray theme for business
• neon-purple - Futuristic neon purple with glow effect
• forest-green - Natural green theme inspired by nature
• ocean-blue - Deep ocean blue with wave-like gradient
• fire-red - Bold red gradient with dynamic energy
• golden-luxury - Elegant gold gradient for premium brands
• minimalist - Clean and simple design
• retro-wave - 80s inspired neon colors
• pastel-dream - Soft pastel colors for gentle look

// Create custom template
const customTemplate = qrverse.createCustomTemplate(
  'my-brand',
  'My Brand Template',
  'Custom template for my brand',
  {
    gradient: {
      type: 'linear',
      colors: ['#FF6B6B', '#4ECDC4'],
      direction: 45,
    },
    frame: {
      type: 'rounded',
      color: '#FF6B6B',
      thickness: 4,
    },
  }
);

🔐 Security Features

Password Protection

const protectedQR = await qrverse.generateQR({
  data: 'Sensitive information',
  security: {
    password: 'strongPassword123',
  },
});

// Verify password when scanning
const verifiedData = qrverse.verifyPassword(protectedData, 'strongPassword123');

Encryption

const encryptedQR = await qrverse.generateQR({
  data: 'Top secret data',
  security: {
    encryption: true,
    encryptionKey: 'your-32-character-encryption-key',
  },
});

// Decrypt data
const decryptedData = qrverse.decrypt(encryptedData, 'your-32-character-encryption-key');

🛠️ Configuration Options

interface QRVerseConfig {
  baseUrl?: string; // Base URL for dynamic QR codes
  database?: DatabaseConfig; // Database configuration
  analytics?: {
    enabled: boolean;
    trackLocation: boolean;
    trackDevice: boolean;
  };
  security?: {
    defaultEncryption: boolean;
    hashAlgorithm: string;
  };
  email?: EmailConfig; // Email configuration for reports
}

🎯 Use Cases

E-commerce

• Product QR codes with analytics
• Dynamic pricing and promotions
• Inventory tracking

Events & Tickets

• Single-use ticket validation
• Event check-in systems
• Promotional campaigns

Marketing

• Campaign performance tracking
• A/B testing with different designs
• Geographic market analysis

Business Cards

• Dynamic contact information
• Professional templates
• Analytics on networking effectiveness

Restaurants

• Digital menus with analytics
• Table-specific QR codes
• Promotional offers tracking

📚 API Reference

Core Methods

generateQR(options: QRCodeOptions): Promise<QRCodeResult>

Generate a QR code with specified options.

updateDynamicQR(id: string, newDestination: string): Promise<boolean>

Update the destination URL of a dynamic QR code.

recordScan(qrId: string, ip: string, userAgent: string): Promise<boolean>

Record a QR code scan for analytics.

Analytics Methods

getAnalytics(qrId: string): Promise<AnalyticsData | null>

Get comprehensive analytics for a QR code.

getTopPerformers(limit?: number): Promise<AnalyticsData[]>

Get the best performing QR codes.

getScanTrends(days?: number): Promise<Record<string, number>>

Get scan trends over time.

Template Methods

getTemplates(): Template[]

Get all available templates.

getTemplate(id: string): Template | null

Get a specific template by ID.

createCustomTemplate(id: string, name: string, description: string, customization: QRCustomization): Template

Create a custom template.

Security Methods

encrypt(data: string, key?: string): string

Encrypt data with optional custom key.

decrypt(encryptedData: string, key: string): string

Decrypt previously encrypted data.

verifyPassword(protectedData: string, password: string): string | null

Verify password for protected data.

🧪 Testing

npm test

🏗️ Building

npm run build

📝 Examples Repository

Check out our examples repository for complete implementation examples:

• Express.js server integration
• React frontend components
• Next.js full-stack application
• Analytics dashboard
• Batch processing scripts

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/julioamorimdev/qrverse.git
cd qrverse
npm install
npm run dev

Running Tests

npm test
npm run test:coverage

Code Style

We use ESLint and Prettier for code formatting:

npm run lint
npm run lint:fix

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🐛 Issue Tracker
• 📧 Email Support

🙏 Acknowledgments

• qrcode - Core QR code generation
• canvas - Image manipulation
• sharp - High-performance image processing
• crypto-js - Cryptographic functions

🔄 Changelog

See CHANGELOG.md for a detailed history of changes.

🚀 Roadmap

• React/Vue/Angular components
• WebAssembly support for better performance
• Machine learning for QR code optimization
• Blockchain integration for verification
• Mobile SDK (React Native, Flutter)
• Advanced analytics with AI insights

---

Made with ❤️ by the QRVerse Team

If you find QRVerse useful, please consider giving it a ⭐ on GitHub!