@supernovae-st/qrcode-ai-scanner 0.2.0

package/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "qrcode-ai-scanner-node"
+version.workspace = true
+edition.workspace = true
+description = "Node.js bindings for QR code validation"
+license.workspace = true
+repository.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+qrcode-ai-scanner-core = { path = "../qrcode-ai-scanner-core" }
+napi = "2"
+napi-derive = "2"
+
+[build-dependencies]
+napi-build = "2"

package/README.md

@@ -0,0 +1,356 @@
+<div align="center">
+
+# @supernovae-st/qrcode-ai-scanner
+
+**Node.js bindings for qrcode-ai-scanner - High-performance QR code validation**
+
+[![npm](https://img.shields.io/npm/v/@supernovae-st/qrcode-ai-scanner?style=flat-square&logo=npm&logoColor=white&color=red)](https://www.npmjs.com/package/@supernovae-st/qrcode-ai-scanner)
+[![License](https://img.shields.io/npm/l/@supernovae-st/qrcode-ai-scanner?style=flat-square&color=blue)](LICENSE)
+
+*Native Rust performance in Node.js via napi-rs.<br/>Validate AI-generated and artistic QR codes that break standard scanners.*
+
+</div>
+
+<br/>
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install @supernovae-st/qrcode-ai-scanner
+# or
+yarn add @supernovae-st/qrcode-ai-scanner
+# or
+pnpm add @supernovae-st/qrcode-ai-scanner
+```
+
+### From GitHub
+
+```bash
+npm install github:supernovae-st/qrcode-ai-scanner
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/supernovae-st/qrcode-ai-scanner.git
+cd qrcode-ai-scanner/crates/qrcode-ai-scanner-node
+npm install
+npm run build
+```
+
+### Local usage (without npm registry)
+
+After building from source, you can use the package locally in several ways:
+
+**Option 1: npm link (symlink)**
+
+```bash
+# In qrcode-ai-scanner-node directory
+npm link
+
+# In your project
+npm link @supernovae-st/qrcode-ai-scanner
+```
+
+**Option 2: npm pack (tarball)**
+
+```bash
+# In qrcode-ai-scanner-node directory
+npm pack  # Creates qrcodeai-qrcode-ai-scanner-0.1.0.tgz
+
+# In your project
+npm install /path/to/qrcodeai-qrcode-ai-scanner-0.1.0.tgz
+```
+
+**Option 3: Direct path in package.json**
+
+```json
+{
+  "dependencies": {
+    "@supernovae-st/qrcode-ai-scanner": "file:../qrcode-ai-scanner/crates/qrcode-ai-scanner-node"
+  }
+}
+```
+
+**Option 4: Direct require**
+
+```javascript
+const scanner = require('/path/to/qrcode-ai-scanner/crates/qrcode-ai-scanner-node');
+```
+
+## Quick Start
+
+```javascript
+import { readFileSync } from 'fs';
+import { validate, isValid, score, summarize } from '@supernovae-st/qrcode-ai-scanner';
+
+const buffer = readFileSync('qr.png');
+
+// Simple check - is the QR valid?
+const content = isValid(buffer);
+if (content) {
+  console.log(`QR contains: ${content}`);
+}
+
+// Get scannability score
+const s = score(buffer);
+console.log(`Score: ${s}/100`);
+
+// Get a summary
+const summary = summarize(buffer);
+console.log(summary);
+// { valid: true, score: 85, rating: 'Excellent', productionReady: true, ... }
+
+// Full validation with stress tests
+const result = validate(buffer);
+console.log(`Score: ${result.score}`);
+console.log(`Content: ${result.content}`);
+console.log(`Stress tests:`, result.stressOriginal, result.stressDownscale50);
+```
+
+## API Reference
+
+### Main Functions
+
+#### `validate(buffer: Buffer): ValidationResult`
+
+Full validation with all stress tests. Returns complete results.
+
+```typescript
+const result = validate(buffer);
+// result.score: 0-100
+// result.decodable: boolean
+// result.content: string | null
+// result.version: number | null
+// result.errorCorrection: 'L' | 'M' | 'Q' | 'H' | null
+// result.stressOriginal: boolean
+// result.stressDownscale50: boolean
+// result.stressBlurLight: boolean
+// ...
+```
+
+#### `validateFast(buffer: Buffer): ValidationResult`
+
+Fast validation with reduced stress tests. ~2x faster.
+
+```typescript
+const result = validateFast(buffer);
+// Same return type, but some stress tests skipped
+```
+
+#### `decode(buffer: Buffer): DecodeResult`
+
+Decode only, no stress tests. Fastest option.
+
+```typescript
+const result = decode(buffer);
+// result.content: string
+// result.version: number | null
+// result.errorCorrection: 'L' | 'M' | 'Q' | 'H' | null
+```
+
+### Convenience Helpers
+
+#### `isValid(buffer: Buffer): string | null`
+
+Check if QR is valid. Returns content or null.
+
+```typescript
+const content = isValid(buffer);
+if (content) {
+  console.log(`Valid! Content: ${content}`);
+} else {
+  console.log('Invalid QR');
+}
+```
+
+#### `score(buffer: Buffer): number`
+
+Get scannability score (0-100).
+
+```typescript
+const s = score(buffer);
+console.log(`${s}/100`);
+```
+
+#### `passesThreshold(buffer: Buffer, minScore: number): boolean`
+
+Check if QR meets minimum score.
+
+```typescript
+if (passesThreshold(buffer, 70)) {
+  console.log('Production ready!');
+}
+```
+
+#### `isProductionReady(buffer: Buffer): boolean`
+
+Check if QR is production-ready (score >= 70).
+
+```typescript
+if (isProductionReady(buffer)) {
+  await uploadToProduction(buffer);
+}
+```
+
+#### `summarize(buffer: Buffer): QrSummary`
+
+Get a simple summary object.
+
+```typescript
+const summary = summarize(buffer);
+// {
+//   valid: true,
+//   score: 85,
+//   content: 'https://example.com',
+//   errorCorrection: 'M',
+//   rating: 'Excellent',
+//   productionReady: true
+// }
+```
+
+#### `getRating(score: number): string`
+
+Convert score to human-readable rating.
+
+```typescript
+getRating(85);  // 'Excellent'
+getRating(75);  // 'Good'
+getRating(55);  // 'Fair'
+getRating(25);  // 'Poor'
+```
+
+## TypeScript
+
+Full TypeScript support included:
+
+```typescript
+import type {
+  ValidationResult,
+  DecodeResult,
+  QrSummary
+} from '@supernovae-st/qrcode-ai-scanner';
+
+const result: ValidationResult = validate(buffer);
+```
+
+## Usage Examples
+
+### Express.js API
+
+```typescript
+import express from 'express';
+import multer from 'multer';
+import { validate, isProductionReady } from '@supernovae-st/qrcode-ai-scanner';
+
+const app = express();
+const upload = multer();
+
+app.post('/validate', upload.single('qr'), (req, res) => {
+  const buffer = req.file.buffer;
+  const result = validate(buffer);
+
+  res.json({
+    score: result.score,
+    content: result.content,
+    productionReady: result.score >= 70
+  });
+});
+
+app.post('/check', upload.single('qr'), (req, res) => {
+  const ok = isProductionReady(req.file.buffer);
+  res.json({ accepted: ok });
+});
+```
+
+### Batch Processing
+
+```typescript
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { score, getRating } from '@supernovae-st/qrcode-ai-scanner';
+
+const qrDir = './qr-codes';
+const files = readdirSync(qrDir).filter(f => f.endsWith('.png'));
+
+for (const file of files) {
+  const buffer = readFileSync(join(qrDir, file));
+  const s = score(buffer);
+  console.log(`${file}: ${s}/100 (${getRating(s)})`);
+}
+```
+
+### Next.js API Route
+
+```typescript
+// pages/api/validate.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { validate } from '@supernovae-st/qrcode-ai-scanner';
+
+export const config = {
+  api: { bodyParser: false }
+};
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  const buffer = Buffer.concat(chunks);
+
+  const result = validate(buffer);
+  res.json(result);
+}
+```
+
+## Score Interpretation
+
+| Score | Rating | Recommendation |
+|-------|--------|----------------|
+| 80-100 | Excellent | Safe for all conditions |
+| 70-79 | Good | Production ready |
+| 60-69 | Acceptable | May fail on older phones |
+| 40-59 | Fair | Consider regenerating |
+| 0-39 | Poor | Needs redesign |
+
+## Platform Support
+
+Pre-built binaries for:
+
+| Platform | Architecture |
+|----------|--------------|
+| macOS | x64, arm64 (M1/M2) |
+| Linux | x64, arm64 |
+| Windows | x64 |
+
+## Performance
+
+| Operation | Clean QR | Artistic QR |
+|-----------|----------|-------------|
+| `decode()` | ~20ms | ~200ms |
+| `validateFast()` | ~50ms | ~500ms |
+| `validate()` | ~80ms | ~1000ms |
+
+## License
+
+MIT
+
+---
+
+<div align="center">
+
+Part of [**QR Code AI**](https://qrcode-ai.com) by **Thibaut MÉLEN** & [**SuperNovae Studio**](https://supernovae.studio)
+
+<br/>
+
+<a href="https://github.com/ThibautMelen">
+  <img src="https://avatars.githubusercontent.com/u/20891897?s=200&v=4" alt="Thibaut MÉLEN" width="32"/>
+</a>
+&nbsp;&nbsp;
+<a href="https://github.com/supernovae-st">
+  <img src="https://avatars.githubusercontent.com/u/33066282?s=200&v=4" alt="SuperNovae Studio" width="32"/>
+</a>
+
+</div>

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,182 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** QR code validation result */
+export interface ValidationResult {
+  /** Scannability score from 0-100 */
+  score: number
+  /** Whether the QR code was successfully decoded */
+  decodable: boolean
+  /** Decoded content of the QR code */
+  content?: string
+  /** QR code version (1-40) */
+  version?: number
+  /** Error correction level (L, M, Q, H) */
+  errorCorrection?: string
+  /** Number of modules in the QR code */
+  modules?: number
+  /** List of decoders that successfully decoded the QR */
+  decodersSuccess: Array<string>
+  /** Whether original image was decodable */
+  stressOriginal: boolean
+  /** Whether 50% downscaled image was decodable */
+  stressDownscale50: boolean
+  /** Whether 25% downscaled image was decodable */
+  stressDownscale25: boolean
+  /** Whether lightly blurred image was decodable */
+  stressBlurLight: boolean
+  /** Whether medium blurred image was decodable */
+  stressBlurMedium: boolean
+  /** Whether low contrast image was decodable */
+  stressLowContrast: boolean
+}
+/** Simple decode result (without stress tests) */
+export interface DecodeResult {
+  /** Decoded content of the QR code */
+  content: string
+  /** QR code version (1-40) */
+  version?: number
+  /** Error correction level (L, M, Q, H) */
+  errorCorrection?: string
+  /** Number of modules in the QR code */
+  modules?: number
+}
+/**
+ * Validate a QR code image and compute scannability score
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns ValidationResult with score, content, and metadata
+ */
+export declare function validate(imageBuffer: Buffer): ValidationResult
+/**
+ * Fast decode without stress tests (for when you only need content)
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns DecodeResult with content and basic metadata
+ */
+export declare function decode(imageBuffer: Buffer): DecodeResult
+/**
+ * Fast validation with reduced stress tests (~2x faster)
+ *
+ * Good for real-time feedback during QR editing.
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns ValidationResult with score, content, and metadata
+ */
+export declare function validateFast(imageBuffer: Buffer): ValidationResult
+/**
+ * Get only the scannability score (0-100)
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns Score from 0 (unreadable) to 100 (highly scannable)
+ */
+export declare function validateScoreOnly(imageBuffer: Buffer): number
+/**
+ * Get score using fast validation (~2x faster)
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns Score from 0 (unreadable) to 100 (highly scannable)
+ */
+export declare function validateScoreFast(imageBuffer: Buffer): number
+/** Simple summary of QR validation */
+export interface QrSummary {
+  /** Whether the QR is valid and decodable */
+  valid: boolean
+  /** Scannability score (0-100) */
+  score: number
+  /** Decoded content (empty if invalid) */
+  content: string
+  /** Error correction level (L/M/Q/H or "N/A") */
+  errorCorrection: string
+  /** Human-readable rating (Excellent/Good/Fair/Poor) */
+  rating: string
+  /** Whether this QR is production-ready (score >= 70) */
+  productionReady: boolean
+}
+/**
+ * Check if QR code is valid (returns content or null)
+ *
+ * @example
+ * ```typescript
+ * const content = isValid(buffer);
+ * if (content) {
+ *   console.log(`QR contains: ${content}`);
+ * }
+ * ```
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns Decoded content string, or null if QR is invalid
+ */
+export declare function isValid(imageBuffer: Buffer): string | null
+/**
+ * Get scannability score (0-100)
+ *
+ * @example
+ * ```typescript
+ * const s = score(buffer);
+ * console.log(`Scannability: ${s}/100`);
+ * ```
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns Score from 0 (unreadable) to 100 (highly scannable)
+ */
+export declare function score(imageBuffer: Buffer): number
+/**
+ * Check if QR meets minimum score threshold
+ *
+ * @example
+ * ```typescript
+ * if (passesThreshold(buffer, 70)) {
+ *   console.log('Production ready!');
+ * }
+ * ```
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @param minScore - Minimum score required (0-100)
+ * @returns true if score >= minScore
+ */
+export declare function passesThreshold(imageBuffer: Buffer, minScore: number): boolean
+/**
+ * Get production readiness (score >= 70)
+ *
+ * @example
+ * ```typescript
+ * if (isProductionReady(buffer)) {
+ *   await uploadQr(buffer);
+ * }
+ * ```
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns true if QR is production-ready
+ */
+export declare function isProductionReady(imageBuffer: Buffer): boolean
+/**
+ * Get simple summary of QR validation
+ *
+ * @example
+ * ```typescript
+ * const summary = summarize(buffer);
+ * console.log(`${summary.rating}: ${summary.score}/100`);
+ * if (summary.productionReady) {
+ *   console.log(`Content: ${summary.content}`);
+ * }
+ * ```
+ *
+ * @param imageBuffer - Raw image bytes (PNG, JPEG, etc.)
+ * @returns QrSummary with all key info
+ */
+export declare function summarize(imageBuffer: Buffer): QrSummary
+/**
+ * Get human-readable rating for a score
+ *
+ * @example
+ * ```typescript
+ * const rating = getRating(85); // "Excellent"
+ * ```
+ *
+ * @param score - Score from 0-100
+ * @returns Rating string (Excellent/Good/Fair/Poor)
+ */
+export declare function getRating(score: number): string