quadqr-js 0.7.0 → 1.0.0

package/README.md

@@ -11,11 +11,15 @@
 <p align="center">
   <a href="https://akanshsirohi.github.io/QuadQR/demo/"><strong>Try the Live Demo</strong></a>
   ·
+  <a href="https://akanshsirohi.github.io/QuadQR/docs-site/"><strong>Documentation Site</strong></a>
+  ·
+  <a href="https://www.npmjs.com/package/quadqr-js">npm</a>
+  ·
   <a href="#current-benchmark">Benchmark</a>
   ·
   <a href="#getting-started">Use the Library</a>
   ·
-  <a href="docs/README.md">Documentation</a>
+  <a href="docs/README.md">Markdown Docs</a>
   ·
   <a href="FORMAT.md">Format Specification</a>
 </p>
@@ -550,21 +554,21 @@ QuadQR can be used as an npm package, directly from a CDN, or from this reposito
 
 ### Requirements
 
-- **Node.js 20.19+** for the published Node/CommonJS entry points
-- npm for package workflows
+- **Node.js 20.19+** for Node.js and CommonJS usage
+- npm or another Node package manager for installation
 - A modern browser for the demo and documentation site
 - HTTPS or localhost for browser camera access
 
 ### Install from npm
 
 ```bash
-npm install quadqr
+npm install quadqr-js
 ```
 
 Core usage:
 
 ```js
-import { encodeText, decodeMatrix } from "quadqr";
+import { encodeText, decodeMatrix } from "quadqr-js";
 
 const code = encodeText("Hello from QuadQR", { ecc: "M" });
 const result = decodeMatrix(code.matrix);
@@ -574,8 +578,8 @@ console.log(result.text);
 Node PNG usage:
 
 ```js
-import { encodeText } from "quadqr";
-import { savePNG, scanFile } from "quadqr/node";
+import { encodeText } from "quadqr-js";
+import { savePNG, scanFile } from "quadqr-js/node";
 
 const code = encodeText("Generated on Node.js");
 await savePNG(code, "quadqr.png", { moduleSize: 12, quietZone: 4 });
@@ -586,10 +590,10 @@ console.log(result.text);
 
 ### CDN / script tag
 
-After the package is published to npm, the classic global build can be loaded from npm-backed CDNs:
+The `quadqr-js` package can be loaded directly from npm-backed CDNs:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/quadqr@0.7.0/dist/quadqr.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/quadqr-js@1.0.0/dist/quadqr.min.js"></script>
 <script>
   const code = QuadQR.encodeText("Hello from a script tag");
 </script>
@@ -597,7 +601,25 @@ After the package is published to npm, the classic global build can be loaded fr
 
 The same file is available through unpkg. Pin an exact version in production.
 
-### Clone for development
+### CLI
+
+Encode and decode directly from the terminal:
+
+```bash
+npx quadqr-js encode "Hello QuadQR" -o hello.png
+npx quadqr-js decode hello.png
+```
+
+Password-protected payloads use the same commands:
+
+```bash
+npx quadqr-js encode "Private data" --password "my-password" -o secure.png
+npx quadqr-js decode secure.png --password "my-password"
+```
+
+See [`docs/CLI.md`](docs/CLI.md) for all CLI options, including raw 256-bit key mode.
+
+### Run from source
 
 ```bash
 git clone https://github.com/akanshsirohi/QuadQR.git
@@ -611,7 +633,7 @@ Run the complete test suite:
 npm test
 ```
 
-Build the npm/CDN distribution and prebuilt WASM asset:
+Build the distributable browser, Node.js, CDN, and WASM files:
 
 ```bash
 npm run build
@@ -635,18 +657,12 @@ Run benchmarks:
 npm run benchmark
 ```
 
-Inspect exactly what npm will publish:
-
-```bash
-npm run pack:check
-```
-
 ### Optional WASM acceleration
 
 The package ships a prebuilt WASM helper but never requires it.
 
 ```js
-import { initWasm } from "quadqr";
+import { initWasm } from "quadqr-js";
 
 await initWasm();
 ```
@@ -659,11 +675,11 @@ If WASM cannot load, the normal JavaScript codec remains available.
 
 | Import | Purpose |
 |---|---|
-| `quadqr` | Runtime-neutral core, secure payloads, rendering, scanning, optional WASM |
-| `quadqr/browser` | Browser ESM entry |
-| `quadqr/node` | Node core plus PNG/file/buffer helpers |
-| `quadqr/benchmark` | Capacity and codec benchmark helpers |
-| `quadqr/quadqr.min.js` | Classic browser global/CDN bundle |
+| `quadqr-js` | Runtime-neutral core, secure payloads, rendering, scanning, optional WASM |
+| `quadqr-js/browser` | Browser ESM entry |
+| `quadqr-js/node` | Node core plus PNG/file/buffer helpers |
+| `quadqr-js/benchmark` | Capacity and codec benchmark helpers |
+| `quadqr-js/quadqr.min.js` | Classic browser global/CDN bundle |
 
 The Node PNG path is dependency-free. For JPEG, WebP, or AVIF input, the Node adapter can use `sharp` when the consuming application already has it installed.
 
@@ -686,7 +702,7 @@ wasm-src/
   quadqr_core.c      Small portable WASM accelerator source
 
 wasm/
-  quadqr-core.wasm   Maintainer build output for direct source usage
+  quadqr-core.wasm   Source-tree WASM build output
 
 dist/
   index.js           ESM package entry
@@ -714,11 +730,11 @@ docs/
   BROWSER_CDN.md
   NODE.md
   SECURITY.md
+  CLI.md
   WASM.md
-  PUBLISHING.md
 
 types/               TypeScript declarations for JavaScript consumers
-bin/                 `npx quadqr` CLI
+bin/                 `quadqr` CLI (`npx quadqr-js`)
 scripts/             Build, benchmark, and local server scripts
 tests/               Codec and package distribution tests
 FORMAT.md             Wire-format specification

package/bin/quadqr.js

@@ -1,102 +1,102 @@
-#!/usr/bin/env node
-
-import { readFile } from "node:fs/promises";
-import process from "node:process";
-import {
-  bytesToHex,
-  decryptDecoded,
-  encodeSecureText,
-  encodeText,
-  generateRaw256Key
-} from "../dist/index.js";
-import { savePNG, scanFile } from "../dist/node.js";
-
-function help() {
-  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png] [--ecc M] [--version auto|1..40]\n  quadqr encode <text> --password <password> [-o file.png]\n  quadqr encode <text> --key <64-hex-key> [-o file.png]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>]\n  quadqr keygen\n\nOptions:\n  -o, --output <file>       Output PNG path (default: quadqr.png)\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --module-size <px>        PNG module size (default: 12)\n  --quiet-zone <modules>    PNG quiet zone (default: 4)\n  -h, --help                Show help\n`);
-}
-
-function parse(argv) {
-  const args = [];
-  const flags = {};
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    if (token === "-h" || token === "--help") flags.help = true;
-    else if (token === "-o" || token === "--output") flags.output = argv[++i];
-    else if (token === "--ecc") flags.ecc = argv[++i];
-    else if (token === "--version") flags.version = argv[++i];
-    else if (token === "--password") flags.password = argv[++i];
-    else if (token === "--key") flags.key = argv[++i];
-    else if (token === "--module-size") flags.moduleSize = Number(argv[++i]);
-    else if (token === "--quiet-zone") flags.quietZone = Number(argv[++i]);
-    else args.push(token);
-  }
-  return { args, flags };
-}
-
-async function main() {
-  const { args, flags } = parse(process.argv.slice(2));
-  if (flags.help || !args.length) {
-    help();
-    return;
-  }
-
-  const command = args.shift();
-  if (command === "keygen") {
-    console.log(bytesToHex(generateRaw256Key()));
-    return;
-  }
-
-  if (command === "encode") {
-    const text = args.join(" ");
-    if (!text) throw new Error("encode requires text.");
-    if (flags.password && flags.key) throw new Error("Choose password mode or raw-key mode, not both.");
-
-    const options = {
-      ecc: flags.ecc || "M",
-      ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
-    };
-    const code = flags.password
-      ? await encodeSecureText(text, { ...options, security: { mode: "password", password: flags.password } })
-      : flags.key
-        ? await encodeSecureText(text, { ...options, security: { mode: "raw-key", key: flags.key } })
-        : encodeText(text, options);
-
-    const output = flags.output || "quadqr.png";
-    const saved = await savePNG(code, output, {
-      moduleSize: flags.moduleSize || 12,
-      quietZone: Number.isFinite(flags.quietZone) ? flags.quietZone : 4
-    });
-    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ECC ${code.eccLevel}).`);
-    return;
-  }
-
-  if (command === "decode") {
-    const filename = args[0];
-    if (!filename) throw new Error("decode requires an image filename.");
-    let result = await scanFile(filename);
-    if (result.secure) {
-      if (!flags.password && !flags.key) {
-        console.log(JSON.stringify({
-          secure: true,
-          mode: result.security?.mode,
-          algorithm: result.security?.algorithm,
-          keyId: result.security?.keyId || result.security?.keyIdHex || null,
-          requiresDecryption: true
-        }, null, 2));
-        process.exitCode = 2;
-        return;
-      }
-      result = await decryptDecoded(result, flags.password ? { password: flags.password } : { key: flags.key });
-    }
-    if (result.text != null) console.log(result.text);
-    else process.stdout.write(Buffer.from(result.payload));
-    return;
-  }
-
-  throw new Error(`Unknown command: ${command}`);
-}
-
-main().catch((error) => {
-  console.error(`QuadQR: ${error.message}`);
-  process.exitCode = 1;
-});
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import {
+  bytesToHex,
+  decryptDecoded,
+  encodeSecureText,
+  encodeText,
+  generateRaw256Key
+} from "../dist/index.js";
+import { savePNG, scanFile } from "../dist/node.js";
+
+function help() {
+  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png] [--ecc M] [--version auto|1..40]\n  quadqr encode <text> --password <password> [-o file.png]\n  quadqr encode <text> --key <64-hex-key> [-o file.png]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>]\n  quadqr keygen\n\nOptions:\n  -o, --output <file>       Output PNG path (default: quadqr.png)\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --module-size <px>        PNG module size (default: 12)\n  --quiet-zone <modules>    PNG quiet zone (default: 4)\n  -h, --help                Show help\n`);
+}
+
+function parse(argv) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "-h" || token === "--help") flags.help = true;
+    else if (token === "-o" || token === "--output") flags.output = argv[++i];
+    else if (token === "--ecc") flags.ecc = argv[++i];
+    else if (token === "--version") flags.version = argv[++i];
+    else if (token === "--password") flags.password = argv[++i];
+    else if (token === "--key") flags.key = argv[++i];
+    else if (token === "--module-size") flags.moduleSize = Number(argv[++i]);
+    else if (token === "--quiet-zone") flags.quietZone = Number(argv[++i]);
+    else args.push(token);
+  }
+  return { args, flags };
+}
+
+async function main() {
+  const { args, flags } = parse(process.argv.slice(2));
+  if (flags.help || !args.length) {
+    help();
+    return;
+  }
+
+  const command = args.shift();
+  if (command === "keygen") {
+    console.log(bytesToHex(generateRaw256Key()));
+    return;
+  }
+
+  if (command === "encode") {
+    const text = args.join(" ");
+    if (!text) throw new Error("encode requires text.");
+    if (flags.password && flags.key) throw new Error("Choose password mode or raw-key mode, not both.");
+
+    const options = {
+      ecc: flags.ecc || "M",
+      ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
+    };
+    const code = flags.password
+      ? await encodeSecureText(text, { ...options, security: { mode: "password", password: flags.password } })
+      : flags.key
+        ? await encodeSecureText(text, { ...options, security: { mode: "raw-key", key: flags.key } })
+        : encodeText(text, options);
+
+    const output = flags.output || "quadqr.png";
+    const saved = await savePNG(code, output, {
+      moduleSize: flags.moduleSize || 12,
+      quietZone: Number.isFinite(flags.quietZone) ? flags.quietZone : 4
+    });
+    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ECC ${code.eccLevel}).`);
+    return;
+  }
+
+  if (command === "decode") {
+    const filename = args[0];
+    if (!filename) throw new Error("decode requires an image filename.");
+    let result = await scanFile(filename);
+    if (result.secure) {
+      if (!flags.password && !flags.key) {
+        console.log(JSON.stringify({
+          secure: true,
+          mode: result.security?.mode,
+          algorithm: result.security?.algorithm,
+          keyId: result.security?.keyId || result.security?.keyIdHex || null,
+          requiresDecryption: true
+        }, null, 2));
+        process.exitCode = 2;
+        return;
+      }
+      result = await decryptDecoded(result, flags.password ? { password: flags.password } : { key: flags.key });
+    }
+    if (result.text != null) console.log(result.text);
+    else process.stdout.write(Buffer.from(result.payload));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`QuadQR: ${error.message}`);
+  process.exitCode = 1;
+});