roxify 1.0.0 → 1.1.0

package/README.md

@@ -1,368 +1,97 @@
-# RoxCompressor Transform
-
-> Encode binary data into PNG images and decode them back. Fast, efficient, with optional encryption.
+# roxify
 
 [![npm version](https://img.shields.io/npm/v/roxify.svg)](https://www.npmjs.com/package/roxify)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-## Features
 
-- 🚀 **Fast**: Optimized Brotli compression (quality 1 by default) — encode 3.8 MB in ~1 second
-- 🔒 **Secure**: AES-256-GCM encryption support with PBKDF2 key derivation
-- 🎨 **Multiple modes**: Compact, chunk, pixel, and screenshot modes
-- 📦 **CLI & API**: Use as command-line tool or JavaScript library
-- 🔄 **Lossless**: Perfect roundtrip encoding/decoding
-- 📊 **Efficient**: Typically 20-30% of original size with compression
-- 📖 **Full TSDoc**: Complete TypeScript documentation
+Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).
 
-## Documentation
+Roxify is a compact, color-based alternative to QR codes, designed specifically for digital-only use (not for printing). It encodes data using color channels (rather than monochrome patterns) for higher density, and is optimized for decoding from approximate screenshots — including nearest-neighbour resize/stretch and solid or gradient backgrounds. It is not intended for printed media and is not resilient to lossy compression or heavy image filtering.
 
-- 📘 **[CLI Documentation](./CLI.md)** - Complete command-line usage guide
-- 📗 **[JavaScript SDK](./JAVASCRIPT_SDK.md)** - Programmatic API reference with examples
-- 📙 **[Quick Start](#quick-start)** - Get started in 2 minutes
+Roxified PNGs are often more space-efficient than ZIP archives for similar payloads and provide a visual indication of the embedded data size.
 
 ## Installation
 
-### As CLI tool (npx)
-
-No installation needed! Use directly with npx:
-
-```bash
-  npx rox encode input.zip output.png
-  npx rox decode output.png original.zip
-```
-
-### As library
-
 ```bash
 npm install roxify
 ```
 
 ## CLI Usage
 
-### Quick Start
-
 ```bash
-# Encode a file
-  npx rox encode document.pdf document.png
-
-# Decode it back
-  npx rox decode document.png document.pdf
-
-# With encryption
-  npx rox encode secret.zip secret.png -p mypassword
-  npx rox decode secret.png secret.zip -p mypassword
-```
-
-### CLI Commands
-
-#### `encode` - Encode file to PNG
+npx rox encode <inputName>.ext (<outputName>.png)
 
-```bash
-  npx rox encode <input> [output] [options]
+npx rox decode <inputName>.png (<outputName>.ext)
 ```
 
-**Options:**
-
-- `-p, --passphrase <pass>` - Encrypt with passphrase (AES-256-GCM)
-- `-m, --mode <mode>` - Encoding mode: `compact|chunk|pixel|screenshot` (default: `screenshot`)
-- `-q, --quality <0-11>` - Brotli compression quality (default: `1`)
-  - `0` = fastest, largest
-  - `11` = slowest, smallest
-- `-e, --encrypt <type>` - Encryption: `auto|aes|xor|none` (default: `aes` if passphrase)
-- `--no-compress` - Disable compression
-- `-o, --output <path>` - Output file path
-
-**Examples:**
-
-```bash
-# Basic encoding
-  npx rox encode data.bin output.png
-
-# Fast compression for large files
-  npx rox encode large-video.mp4 output.png -q 0
+If no output name is provided:
 
-# High compression for small files
-  npx rox encode config.json output.png -q 11
+- Encoding: output defaults to `<inputName>.png`.
+- Decoding: if the image contains the original filename it will be restored; otherwise the output will be `decoded.bin`.
 
-# With encryption
-  npx rox encode secret.pdf secure.png -p "my secure password"
+**Commands:**
 
-# Compact mode (smallest PNG)
-  npx rox encode data.bin tiny.png -m compact
-
-# Screenshot mode (recommended, looks like a real image)
-  npx rox encode archive.tar.gz screenshot.png -m screenshot
-```
-
-#### `decode` - Decode PNG to file
-
-```bash
-  npx rox decode <input> [output] [options]
-```
+- `encode <input> [output]` — Encode file to PNG
+- `decode <input> [output]` — Decode PNG to file
 
 **Options:**
 
-- `-p, --passphrase <pass>` - Decryption passphrase
-- `-o, --output <path>` - Output file path (auto-detected from metadata if not provided)
-
-**Examples:**
+- `-p, --passphrase <pass>` — Encrypt with AES-256-GCM
+- `-m, --mode <mode>` — Encoding mode: `screenshot` (default), `pixel`, `compact`, `chunk`
+- `-q, --quality <0-11>` — Brotli compression quality (default: 11)
+- `--no-compress` — Disable compression
+- `-v, --verbose` — Show detailed errors
 
-```bash
-# Basic decoding
-  npx rox decode encoded.png output.bin
-
-# Auto-detect filename from metadata
-  npx rox decode encoded.png
-
-# With decryption
-  npx rox decode encrypted.png output.pdf -p "my secure password"
-```
+Run `npx rox help` for full options.
 
-## JavaScript API
+## API Usage
 
-### Basic Usage
-
-```typescript
+```js
 import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
-import { readFileSync, writeFileSync } from 'fs';
-
-// Encode
-const input = readFileSync('input.zip');
-const png = await encodeBinaryToPng(input, {
-  mode: 'screenshot',
-  name: 'input.zip',
-});
-writeFileSync('output.png', png);
-
-// Decode
-const encoded = readFileSync('output.png');
-const result = await decodePngToBinary(encoded);
-writeFileSync(result.meta?.name || 'output.bin', result.buf);
-```
-
-### With Encryption
-
-```typescript
-// Encode with AES-256-GCM
-const png = await encodeBinaryToPng(input, {
-  mode: 'screenshot',
-  passphrase: 'my-secret-password',
-  encrypt: 'aes',
-  name: 'secret.zip',
-});
 
-// Decode with passphrase
-const result = await decodePngToBinary(encoded, {
-  passphrase: 'my-secret-password',
-});
-```
-
-### Fast Compression
-
-```typescript
-// Optimize for speed (recommended for large files)
-const png = await encodeBinaryToPng(largeBuffer, {
+const data = Buffer.from('Hello world');
+const png = await encodeBinaryToPng(data, {
   mode: 'screenshot',
-  brQuality: 0, // Fastest
-  name: 'large-file.bin',
+  name: 'message.txt',
 });
 
-// Optimize for size (recommended for small files)
-const png = await encodeBinaryToPng(smallBuffer, {
-  mode: 'compact',
-  brQuality: 11, // Best compression
-  name: 'config.json',
-});
-```
-
-### Encoding Modes
-
-#### `screenshot` (Recommended)
-
-Encodes data as RGB pixel values, optimized for screenshot-like appearance. Best balance of size and compatibility.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'screenshot' });
-```
-
-#### `compact` (Smallest)
-
-Minimal 1x1 PNG with data in custom chunk. Fastest and smallest.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'compact' });
+const { buf, meta } = await decodePngToBinary(png);
+console.log(buf.toString('utf8'));
+console.log(meta?.name);
 ```
 
-#### `pixel`
+**API:**
 
-Encodes data as RGB pixel values without screenshot optimization.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'pixel' });
-```
-
-#### `chunk`
-
-Standard PNG with data in custom rXDT chunk.
-
-```typescript
-const png = await encodeBinaryToPng(data, { mode: 'chunk' });
-```
-
-## API Reference
-
-### `encodeBinaryToPng(input, options)`
-
-Encodes binary data into a PNG image.
-
-**Parameters:**
-
-- `input: Buffer` - The binary data to encode
-- `options?: EncodeOptions` - Encoding options
-
-**Returns:** `Promise<Buffer>` - The encoded PNG
+- `encodeBinaryToPng(input: Buffer, opts?: EncodeOptions): Promise<Buffer>`
+- `decodePngToBinary(pngBuf: Buffer): Promise<{ buf: Buffer, meta?: { name?: string } }>`
 
 **Options:**
 
-```typescript
-interface EncodeOptions {
-  // Compression algorithm ('br' = Brotli, 'none' = no compression)
-  compression?: 'br' | 'none';
-
-  // Passphrase for encryption
-  passphrase?: string;
-
-  // Original filename to embed
-  name?: string;
+- `mode` — `'screenshot'` | `'pixel'` | `'compact'` | `'chunk'` (default: `'screenshot'`)
+- `name` — Original filename (embedded as metadata)
+- `passphrase` — Encryption passphrase (uses AES-256-GCM)
+- `compression` — `'br'` | `'none'` (default: `'br'`)
+- `brQuality` — Brotli quality 0-11 (default: 4)
 
-  // Encoding mode
-  mode?: 'compact' | 'chunk' | 'pixel' | 'screenshot';
-
-  // Encryption method
-  encrypt?: 'auto' | 'aes' | 'xor' | 'none';
-
-  // Output format
-  output?: 'auto' | 'png' | 'rox';
-
-  // Include filename in metadata (default: true)
-  includeName?: boolean;
-
-  // Brotli quality 0-11 (default: 1)
-  brQuality?: number;
-}
-```
-
-### `decodePngToBinary(pngBuf, options)`
-
-Decodes a PNG image back to binary data.
-
-**Parameters:**
-
-- `pngBuf: Buffer` - The PNG image to decode
-- `options?: DecodeOptions` - Decoding options
-
-**Returns:** `Promise<DecodeResult>` - The decoded data and metadata
-
-**Options:**
-
-```typescript
-interface DecodeOptions {
-  // Passphrase for decryption
-  passphrase?: string;
-}
-```
+## Example: Express Endpoint
 
-**Result:**
+```js
+import express from 'express';
+import { encodeBinaryToPng } from 'roxify';
 
-```typescript
-interface DecodeResult {
-  // Decoded binary data
-  buf: Buffer;
-
-  // Extracted metadata
-  meta?: {
-    // Original filename
-    name?: string;
-  };
-}
-```
-
-## Performance Tips
-
-### For Large Files (>10 MB)
-
-```bash
-# Use quality 0 for fastest encoding
-npx rox encode large.bin output.png -q 0
-```
-
-```typescript
-const png = await encodeBinaryToPng(largeFile, {
-  mode: 'screenshot',
-  brQuality: 0, // 10-20x faster than default
+const app = express();
+app.get('/payload.png', async (req, res) => {
+  const payload = Buffer.from('Embedded data');
+  const png = await encodeBinaryToPng(payload, { mode: 'screenshot' });
+  res.setHeader('Content-Type', 'image/png');
+  res.send(png);
 });
+app.listen(3000);
 ```
 
-### For Small Files (<1 MB)
+## Requirements
 
-```bash
-# Use quality 11 for best compression
-npx rox encode small.json output.png -q 11 -m compact
-```
-
-```typescript
-const png = await encodeBinaryToPng(smallFile, {
-  mode: 'compact',
-  brQuality: 11, // Best compression ratio
-});
-```
-
-### Benchmark Results
-
-File: 3.8 MB binary
-
-- **Quality 0**: ~500-800ms, output ~1.2 MB
-- **Quality 1** (default): ~1-2s, output ~800 KB
-- **Quality 5**: ~8-12s, output ~750 KB
-- **Quality 11**: ~20-30s, output ~720 KB
-
-## Error Handling
-
-```typescript
-try {
-  const result = await decodePngToBinary(encoded, {
-    passphrase: 'wrong-password',
-  });
-} catch (err) {
-  if (err.message.includes('Incorrect passphrase')) {
-    console.error('Wrong password!');
-  } else if (err.message.includes('Invalid ROX format')) {
-    console.error('Not a valid RoxCompressor PNG');
-  } else {
-    console.error('Decode failed:', err.message);
-  }
-}
-```
-
-## Security
-
-- **AES-256-GCM**: Authenticated encryption with 100,000 PBKDF2 iterations
-- **XOR cipher**: Simple obfuscation (not cryptographically secure)
-- **No encryption**: Data is compressed but not encrypted
-
-⚠️ **Warning**: Use strong passphrases for sensitive data. The `xor` encryption mode is not secure and should only be used for obfuscation.
+- Node.js 18+ (ESM)
+- Native dependencies: `sharp` (auto-installed)
 
 ## License
 
-MIT © RoxCompressor
-
-## Contributing
-
-Contributions welcome! Please open an issue or PR on GitHub.
-
-## Links
-
-- [GitHub Repository](https://github.com/RoxasYTB/RoxCompressor)
-- [npm Package](https://www.npmjs.com/package/roxify)
-- [Report Issues](https://github.com/RoxasYTB/RoxCompressor/issues)
+This package is proprietary (UNLICENSED). The repository remains private; the package is published to npm for distribution. If there is significant community interest, it may be open-sourced in the future.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roxify",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Encode binary data into PNG images and decode them back. Supports CLI and programmatic API (Node.js ESM).",
   "type": "module",
   "main": "dist/index.js",