npm package: @provassure/special-encrypt
Description: A comprehensive encoding/decoding library that supports multiple encoding types in a single unified interface.
Author: gokulakannan_a
Latest version: 1.0.1

# Special Encrypt Library

A comprehensive encoding/decoding library that supports multiple encoding types in a single unified interface.

## Features

- **Universal Encoder**: Single method for multiple encoding types
- **Special Character Encryption**: Custom token-based encoding for special characters
- **Multiple Encoding Types**: Base64, Hex, Binary, URL, HTML entities, ROT13, Caesar cipher, and custom encoding
- **Detection**: Built-in methods to detect encoded strings
- **Flexible Options**: Support for custom parameters (e.g., Caesar cipher shift)

## Installation

```bash
npm install @provassure/special-encrypt
```

## Usage

### Basic Usage

```javascript
const { encode, decode, process, getSupportedTypes } = require('@provassure/special-encrypt');

// Encode a string
const encoded = encode("Hello World!", "base64");
console.log(encoded); // "SGVsbG8gV29ybGQh"

// Decode a string
const decoded = decode(encoded, "base64");
console.log(decoded); // "Hello World!"

// Using the process method
const result = process("Hello World!", "base64", "encode");
const original = process(result, "base64", "decode");
```

### Supported Encoding Types

1. **base64** - Standard Base64 encoding
2. **hex** - Hexadecimal encoding
3. **binary** - Binary representation
4. **url** - URL encoding
5. **html** - HTML entity encoding
6. **rot13** - ROT13 substitution cipher
7. **caesar** - Caesar cipher (configurable shift)
8. **custom** - Custom special character encoding

### Examples

#### Base64 Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello World! @#$%";
const encoded = encode(text, "base64");
const decoded = decode(encoded, "base64");

console.log(encoded); // "SGVsbG8gV29ybGQhICNAJCQl"
console.log(decoded); // "Hello World! @#$%"
```

#### Hex Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello World!";
const encoded = encode(text, "hex");
const decoded = decode(encoded, "hex");

console.log(encoded); // "48656c6c6f20576f726c6421"
console.log(decoded); // "Hello World!"
```

#### Binary Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hi";
const encoded = encode(text, "binary");
const decoded = decode(encoded, "binary");

console.log(encoded); // "0100100001101001"
console.log(decoded); // "Hi"
```

#### URL Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello World! @#$%";
const encoded = encode(text, "url");
const decoded = decode(encoded, "url");

console.log(encoded); // "Hello%20World!%20%40%23%24%25"
console.log(decoded); // "Hello World! @#$%"
```

#### HTML Entity Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello & World < > \" ' ©";
const encoded = encode(text, "html");
const decoded = decode(encoded, "html");

console.log(encoded); // "Hello &amp; World &lt; &gt; &quot; &#39; &copy;"
console.log(decoded); // "Hello & World < > \" ' ©"
```

#### ROT13 Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello World!";
const encoded = encode(text, "rot13");
const decoded = decode(encoded, "rot13");

console.log(encoded); // "Uryyb Jbeyq!"
console.log(decoded); // "Hello World!"
```

#### Caesar Cipher
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Hello World!";
const encoded = encode(text, "caesar", { shift: 5 });
const decoded = decode(encoded, "caesar", { shift: 5 });

console.log(encoded); // "Mjqqt Btwqi!"
console.log(decoded); // "Hello World!"
```

#### Custom Special Character Encoding
```javascript
const { encode, decode } = require('@provassure/special-encrypt');

const text = "Where is the file @ path /docs . fr ?";
const encoded = encode(text, "custom");
const decoded = decode(encoded, "custom");

console.log(encoded); // "Where is the file _sc40_ path _sc47_docs _sc46_ fr _sc63_"
console.log(decoded); // "Where is the file @ path /docs . fr ?"
```

### Advanced Usage

#### Get Supported Types
```javascript
const { getSupportedTypes } = require('@provassure/special-encrypt');

const types = getSupportedTypes();
console.log(types); // ["base64", "hex", "binary", "url", "html", "rot13", "caesar", "custom"]
```

#### Detect Encoded Strings
```javascript
const { isEncoded } = require('@provassure/special-encrypt');

console.log(isEncoded("SGVsbG8gV29ybGQh", "base64")); // true
console.log(isEncoded("48656c6c6f20576f726c6421", "hex")); // true
console.log(isEncoded("Hello World!", "base64")); // false
```

#### Using the Process Method
```javascript
const { process } = require('@provassure/special-encrypt');

// Encode
const encoded = process("Hello World!", "base64", "encode");

// Decode
const decoded = process(encoded, "base64", "decode");

// With options (for Caesar cipher)
const caesarEncoded = process("Hello", "caesar", "encode", { shift: 3 });
const caesarDecoded = process(caesarEncoded, "caesar", "decode", { shift: 3 });
```

### Legacy Special Character Encryption

The library also includes the original special character encryption methods:

```javascript
const { encryptSpecialChars, decryptSpecialChars } = require('@provassure/special-encrypt');

const text = "Where is the file @ path /docs . fr ?";
const encrypted = encryptSpecialChars(text);
const decrypted = decryptSpecialChars(encrypted);

console.log(encrypted); // "Where is the file _sc40_ path _sc47_docs _sc46_ fr _sc63_"
console.log(decrypted); // "Where is the file @ path /docs . fr ?"
```

## API Reference

### Main Functions

- `encode(input, type, options)` - Encode a string using specified type
- `decode(input, type, options)` - Decode a string using specified type
- `process(input, type, action, options)` - Universal encode/decode method
- `getSupportedTypes()` - Get list of supported encoding types
- `isEncoded(input, type)` - Test if a string is encoded with a specific type

### Legacy Functions

- `encryptSpecialChars(input)` - Encrypt special characters with custom tokens
- `decryptSpecialChars(input)` - Decrypt special character tokens

### Options

- **Caesar Cipher**: `{ shift: number }` - Specify the shift value (default: 3)
- **Other encodings**: No additional options required

## Error Handling

The library throws descriptive errors for unsupported encoding types or invalid actions:

```javascript
try {
  const result = encode("Hello", "unsupported");
} catch (error) {
  console.log(error.message); // "Unsupported encoding type: unsupported. Supported types: base64, hex, binary, url, html, rot13, caesar, custom"
}
```

## Testing

Run the test file to see all encoding types in action:

```bash
node test-universal.js
```

## License

MIT