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!

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

julioamorimdev/QRVerse

Folders and files

Latest commit

History

Repository files navigation