@teamflojo/floimg-qr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Brett Cooke
+
+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,240 @@
+# imgflo-qr
+
+QR code generator for imgflo using the qrcode library.
+
+## Installation
+
+```bash
+npm install imgflo imgflo-qr
+```
+
+## Usage
+
+```typescript
+import createClient from 'imgflo';
+import qr from 'imgflo-qr';
+
+const imgflo = createClient();
+imgflo.registerGenerator(qr());
+
+// Generate a QR code
+const qrCode = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: 'https://github.com/bcooke/imgflo',
+    width: 300,
+    errorCorrectionLevel: 'H'
+  }
+});
+
+// Save to filesystem or S3
+const result = await imgflo.save(qrCode, './output/qr-github.png');
+// Or save to S3:
+// const result = await imgflo.save(qrCode, 's3://my-bucket/qr/github.png');
+console.log(result.location);
+```
+
+## Examples
+
+### Basic QR Code
+
+```typescript
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: 'Hello World!',
+    width: 200
+  }
+});
+```
+
+### URL QR Code
+
+```typescript
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: 'https://example.com',
+    width: 300,
+    errorCorrectionLevel: 'H'  // High error correction
+  }
+});
+```
+
+### Custom Colors
+
+```typescript
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: 'Styled QR Code',
+    width: 400,
+    color: {
+      dark: '#667eea',   // Purple
+      light: '#ffffff'   // White background
+    }
+  }
+});
+```
+
+### SVG Output
+
+```typescript
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: 'https://example.com',
+    format: 'svg',
+    width: 300
+  }
+});
+```
+
+### vCard Contact
+
+```typescript
+const vcard = `BEGIN:VCARD
+VERSION:3.0
+FN:John Doe
+TEL:+1-555-1234
+EMAIL:john@example.com
+END:VCARD`;
+
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: vcard,
+    width: 350,
+    errorCorrectionLevel: 'H'
+  }
+});
+```
+
+### WiFi Network
+
+```typescript
+const wifi = 'WIFI:T:WPA;S:MyNetwork;P:MyPassword;;';
+
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: wifi,
+    width: 300
+  }
+});
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | string | *required* | Text/URL to encode |
+| `width` | number | 300 | Output width in pixels |
+| `errorCorrectionLevel` | 'L'\|'M'\|'Q'\|'H' | 'M' | Error correction level |
+| `margin` | number | 4 | Margin around QR code (in modules) |
+| `color.dark` | string | '#000000' | Dark color |
+| `color.light` | string | '#ffffff' | Light/background color |
+| `format` | 'png'\|'svg' | 'png' | Output format |
+| `version` | number | auto | QR code version (1-40) |
+| `maskPattern` | number | auto | Mask pattern (0-7) |
+
+## Error Correction Levels
+
+- **L (Low)**: ~7% of codewords can be restored
+- **M (Medium)**: ~15% of codewords can be restored (default)
+- **Q (Quartile)**: ~25% of codewords can be restored
+- **H (High)**: ~30% of codewords can be restored
+
+Higher error correction allows QR codes to be read even if partially damaged, but requires more data.
+
+## Configuration
+
+```typescript
+imgflo.registerGenerator(qr({
+  errorCorrectionLevel: 'H',  // Default to high error correction
+  width: 400,                  // Default width
+  margin: 5,                   // Default margin
+  color: {
+    dark: '#000000',
+    light: '#ffffff'
+  }
+}));
+```
+
+## Use Cases
+
+### Event Tickets
+
+```typescript
+const ticketData = JSON.stringify({
+  event: 'Concert',
+  seat: 'A12',
+  code: 'ABC123'
+});
+
+const ticket = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: ticketData,
+    width: 300,
+    errorCorrectionLevel: 'H'
+  }
+});
+```
+
+### Payment QR Codes
+
+```typescript
+const paymentUrl = 'bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=0.01';
+
+const payment = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: paymentUrl,
+    width: 350,
+    errorCorrectionLevel: 'H'
+  }
+});
+```
+
+### App Store Links
+
+```typescript
+const appStore = 'https://apps.apple.com/app/id123456789';
+
+const qr = await imgflo.generate({
+  generator: 'qr',
+  params: {
+    text: appStore,
+    width: 250,
+    margin: 6
+  }
+});
+```
+
+## QR Code Library Documentation
+
+This generator uses the qrcode library directly. For advanced options:
+- https://github.com/soldair/node-qrcode
+- https://github.com/soldair/node-qrcode#qr-code-options
+
+## Performance
+
+- **Generation time**: ~5-50ms depending on data size
+- **Memory**: Minimal (~1-5MB)
+- **No external dependencies**: Pure Node.js
+
+## Limitations
+
+- Maximum data capacity depends on QR version and error correction level
+- QR Version 40 with Low error correction can store ~2,953 bytes
+- Higher error correction = less data capacity
+
+## License
+
+MIT
+
+## See Also
+
+- [imgflo](https://github.com/bcooke/imgflo) - Core library
+- [qrcode](https://github.com/soldair/node-qrcode) - QR code library

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import type { ImageGenerator, GeneratorSchema } from "@teamflojo/floimg";
+/**
+ * Schema for the QR code generator
+ */
+export declare const qrSchema: GeneratorSchema;
+/**
+ * QR code generator using the qrcode library
+ *
+ * This generator accepts qrcode library options directly (pass-through pattern).
+ * No imgflo abstraction - you get full qrcode library capabilities.
+ *
+ * @see https://github.com/soldair/node-qrcode - qrcode library documentation
+ *
+ * @example
+ * ```typescript
+ * import createClient from '@teamflojo/floimg';
+ * import qr from '@teamflojo/floimg-qr';
+ *
+ * const floimg = createClient();
+ * floimg.registerGenerator(qr());
+ *
+ * const qrCode = await floimg.generate({
+ *   generator: 'qr',
+ *   params: {
+ *     text: 'https://github.com/TeamFlojo/floimg',
+ *     errorCorrectionLevel: 'H',
+ *     width: 300
+ *   }
+ * });
+ * ```
+ */
+export interface QRConfig {
+    /** Default error correction level */
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+    /** Default width */
+    width?: number;
+    /** Default margin */
+    margin?: number;
+    /** Default color (dark) */
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+}
+export interface QRParams extends Record<string, unknown> {
+    /** Text/URL to encode (required) */
+    text?: string;
+    /** Error correction level: L (7%), M (15%), Q (25%), H (30%) */
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+    /** Output width in pixels */
+    width?: number;
+    /** Margin around QR code (in modules) */
+    margin?: number;
+    /** Colors */
+    color?: {
+        /** Dark color (default: #000000) */
+        dark?: string;
+        /** Light color (default: #ffffff) */
+        light?: string;
+    };
+    /** Output format: 'png' | 'svg' */
+    format?: 'png' | 'svg';
+    /** QR code version (1-40, auto if not specified) */
+    version?: number;
+    /** Mask pattern (0-7, auto if not specified) */
+    maskPattern?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    /** Output quality for JPEG (0-1) */
+    quality?: number;
+}
+/**
+ * Create a QR code generator instance
+ */
+export default function qr(config?: QRConfig): ImageGenerator;
+export { qr };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpF;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAwDtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,oBAAoB,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7C,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvD,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC7C,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,KAAK,CAAC,EAAE;QACN,oCAAoC;QACpC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,qCAAqC;QACrC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5C,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,EAAE,CAAC,MAAM,GAAE,QAAa,GAAG,cAAc,CA0EhE;AAGD,OAAO,EAAE,EAAE,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,121 @@
+import QRCode from "qrcode";
+/**
+ * Schema for the QR code generator
+ */
+export const qrSchema = {
+    name: "qr",
+    description: "Generate QR codes from text or URLs",
+    category: "Utility",
+    parameters: {
+        text: {
+            type: "string",
+            title: "Content",
+            description: "Text or URL to encode in the QR code",
+        },
+        errorCorrectionLevel: {
+            type: "string",
+            title: "Error Correction",
+            description: "Error correction level: L (7%), M (15%), Q (25%), H (30%)",
+            enum: ["L", "M", "Q", "H"],
+            default: "M",
+        },
+        width: {
+            type: "number",
+            title: "Width",
+            description: "Output width in pixels",
+            default: 300,
+            minimum: 50,
+            maximum: 1000,
+        },
+        margin: {
+            type: "number",
+            title: "Margin",
+            description: "Quiet zone margin (in modules)",
+            default: 4,
+            minimum: 0,
+            maximum: 20,
+        },
+        format: {
+            type: "string",
+            title: "Output Format",
+            description: "Output image format",
+            enum: ["png", "svg"],
+            default: "png",
+        },
+        version: {
+            type: "number",
+            title: "QR Version",
+            description: "QR code version (1-40, auto if not specified)",
+            minimum: 1,
+            maximum: 40,
+        },
+        maskPattern: {
+            type: "number",
+            title: "Mask Pattern",
+            description: "Mask pattern (0-7, auto if not specified)",
+            minimum: 0,
+            maximum: 7,
+        },
+    },
+    requiredParameters: ["text"],
+};
+/**
+ * Create a QR code generator instance
+ */
+export default function qr(config = {}) {
+    const { errorCorrectionLevel: defaultErrorLevel = 'M', width: defaultWidth = 300, margin: defaultMargin = 4, color: defaultColor = { dark: '#000000', light: '#ffffff' }, } = config;
+    return {
+        name: "qr",
+        schema: qrSchema,
+        async generate(params) {
+            const { text, errorCorrectionLevel = defaultErrorLevel, width = defaultWidth, margin = defaultMargin, color = defaultColor, format = 'png', version, maskPattern, quality, } = params;
+            if (!text) {
+                throw new Error("QR code 'text' parameter is required");
+            }
+            // Build qrcode library options (pass-through)
+            const baseOptions = {
+                errorCorrectionLevel,
+                width,
+                margin,
+                color,
+                ...(version && { version }),
+                ...(maskPattern !== undefined && { maskPattern }),
+            };
+            // Generate QR code
+            let bytes;
+            let mime;
+            if (format === 'svg') {
+                // Generate SVG
+                const svgString = await QRCode.toString(text, {
+                    ...baseOptions,
+                    type: 'svg',
+                });
+                bytes = Buffer.from(svgString, 'utf-8');
+                mime = 'image/svg+xml';
+            }
+            else {
+                // Generate PNG
+                bytes = await QRCode.toBuffer(text, {
+                    ...baseOptions,
+                    type: 'png',
+                });
+                mime = 'image/png';
+            }
+            return {
+                bytes,
+                mime,
+                width: width,
+                height: width, // QR codes are square
+                source: "qr",
+                metadata: {
+                    text,
+                    errorCorrectionLevel,
+                    format,
+                },
+            };
+        },
+    };
+}
+// Also export as named export for convenience
+export { qr };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAoB;IACvC,IAAI,EAAE,IAAI;IACV,WAAW,EAAE,qCAAqC;IAClD,QAAQ,EAAE,SAAS;IACnB,UAAU,EAAE;QACV,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,SAAS;YAChB,WAAW,EAAE,sCAAsC;SACpD;QACD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,kBAAkB;YACzB,WAAW,EAAE,2DAA2D;YACxE,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;YAC1B,OAAO,EAAE,GAAG;SACb;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,OAAO;YACd,WAAW,EAAE,wBAAwB;YACrC,OAAO,EAAE,GAAG;YACZ,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,IAAI;SACd;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,gCAAgC;YAC7C,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,EAAE;SACZ;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,eAAe;YACtB,WAAW,EAAE,qBAAqB;YAClC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;YACpB,OAAO,EAAE,KAAK;SACf;QACD,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,YAAY;YACnB,WAAW,EAAE,+CAA+C;YAC5D,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,EAAE;SACZ;QACD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,cAAc;YACrB,WAAW,EAAE,2CAA2C;YACxD,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;SACX;KACF;IACD,kBAAkB,EAAE,CAAC,MAAM,CAAC;CAC7B,CAAC;AAoEF;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,EAAE,CAAC,SAAmB,EAAE;IAC9C,MAAM,EACJ,oBAAoB,EAAE,iBAAiB,GAAG,GAAG,EAC7C,KAAK,EAAE,YAAY,GAAG,GAAG,EACzB,MAAM,EAAE,aAAa,GAAG,CAAC,EACzB,KAAK,EAAE,YAAY,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAC5D,GAAG,MAAM,CAAC;IAEX,OAAO;QACL,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,QAAQ;QAEhB,KAAK,CAAC,QAAQ,CAAC,MAA+B;YAC5C,MAAM,EACJ,IAAI,EACJ,oBAAoB,GAAG,iBAAiB,EACxC,KAAK,GAAG,YAAY,EACpB,MAAM,GAAG,aAAa,EACtB,KAAK,GAAG,YAAY,EACpB,MAAM,GAAG,KAAK,EACd,OAAO,EACP,WAAW,EACX,OAAO,GACR,GAAG,MAAkB,CAAC;YAEvB,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;YAC1D,CAAC;YAED,8CAA8C;YAC9C,MAAM,WAAW,GAAG;gBAClB,oBAAoB;gBACpB,KAAK;gBACL,MAAM;gBACN,KAAK;gBACL,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;gBAC3B,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC;aAClD,CAAC;YAEF,mBAAmB;YACnB,IAAI,KAAa,CAAC;YAClB,IAAI,IAAmC,CAAC;YAExC,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBACrB,eAAe;gBACf,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;oBAC5C,GAAG,WAAW;oBACd,IAAI,EAAE,KAAK;iBACZ,CAAC,CAAC;gBACH,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxC,IAAI,GAAG,eAAe,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,eAAe;gBACf,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;oBAClC,GAAG,WAAW;oBACd,IAAI,EAAE,KAAK;iBACZ,CAAC,CAAC;gBACH,IAAI,GAAG,WAAW,CAAC;YACrB,CAAC;YAED,OAAO;gBACL,KAAK;gBACL,IAAI;gBACJ,KAAK,EAAE,KAAe;gBACtB,MAAM,EAAE,KAAe,EAAE,sBAAsB;gBAC/C,MAAM,EAAE,IAAI;gBACZ,QAAQ,EAAE;oBACR,IAAI;oBACJ,oBAAoB;oBACpB,MAAM;iBACP;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8CAA8C;AAC9C,OAAO,EAAE,EAAE,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@teamflojo/floimg-qr",
+  "version": "0.1.0",
+  "description": "QR code generator for floimg using qrcode library",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "floimg",
+    "qr",
+    "qrcode",
+    "barcode",
+    "image-generation"
+  ],
+  "author": "Brett Cooke",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TeamFlojo/floimg.git",
+    "directory": "packages/floimg-qr"
+  },
+  "peerDependencies": {
+    "@teamflojo/floimg": "^0.1.0"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/qrcode": "^1.5.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@teamflojo/floimg": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}