# 🛡️ QuantShield JS SDK

> **Post-quantum encryption toolkit for web applications with transparent HTTP interception**

[![npm version](https://badge.fury.io/js/qclair-quantshield.svg)](https://www.npmjs.com/package/qclair-quantshield)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

QuantShield provides **end-to-end encryption** for web applications using **post-quantum cryptography**. It transparently intercepts HTTP requests (fetch, XMLHttpRequest, Axios) and encrypts them before sending to a QuantShield proxy server.

## � Prerequisites

**QuantShield Proxy Server Required**: This SDK requires a QuantShield proxy server to handle encryption/decryption. The proxy server:
- Deploys alongside your backend API server
- Handles ML-KEM-1024 key exchange
- Decrypts incoming requests and forwards to your API
- Encrypts API responses before returning to client

> **Note**: The proxy server is typically deployed at `https://quantshield-proxy.yourcompany.com` or during development at `http://localhost:7000`

## ✨ Features

- 🔒 **Post-Quantum Security**: ML-KEM-1024 (Module-Lattice-Based Key Encapsulation Mechanism)
- � **AES-GCM-256 Encryption**: Symmetric encryption for request/response data
- �🚀 **Zero-Code Integration**: Drop-in replacement for existing HTTP clients  
- 🌐 **Universal Support**: Works in browsers (Chrome, Firefox, Safari, Edge)
- ⚡ **WebAssembly Performance**: Go-compiled crypto functions for speed
- 🎯 **Domain Filtering**: Only encrypts requests to specified domains
- 🔄 **Automatic Decryption**: Seamlessly decrypts responses
- 🔑 **Session Persistence**: Keys survive page navigation (sessionStorage)
- ⏰ **Auto-Refresh**: Optional automatic key rotation

## 🚀 Quick Start

### Installation

```bash
npm install qclair-quantshield
```

### ⚠️ **One-Time Setup Required**

Add 3 lines to your bundler config:

**Vite/React/Vue/Svelte** - Add to `vite.config.js`:
```javascript
export default {
  server: { fs: { allow: ['.', '../node_modules/qclair-quantshield/wasm'] } },
  assetsInclude: ['**/*.wasm.gz']
}
```

**Next.js** - Add to `next.config.js`:
```javascript
module.exports = {
  webpack: (config) => { 
    config.experiments = { asyncWebAssembly: true }; 
    return config; 
  }
}
```

That's it! Restart your dev server.

### Usage

```javascript
import QuantShield from 'qclair-quantshield';

// One-step initialization with automatic protection
await QuantShield.initialize('https://your-quantshield-proxy.com', {
  autoProtect: true,  // Automatically apply patches (default)
  allowedDomains: ['api.example.com', 'secure.api.com']
});

// That's it! All fetch/XHR/Axios requests are now encrypted
const response = await fetch('https://api.example.com/data');
console.log(await response.json()); // Automatically decrypted
```

### Manual Setup (Advanced)

```javascript
import QuantShield from 'qclair-quantshield';

// Step 1: Initialize WASM module
await QuantShield.init();

// Step 2: Perform ML-KEM handshake with your QuantShield proxy server
await QuantShield.initializeHandshake('https://your-quantshield-proxy.com');

// Step 3: Apply HTTP patches
const proxyUrl = 'https://your-quantshield-proxy.com/decrypt-and-forward';
const allowedDomains = ['api.example.com'];

QuantShield.applyPatchFetch(proxyUrl, allowedDomains);
QuantShield.applyPatchXHR(proxyUrl, allowedDomains);

// Now make requests as usual
const response = await fetch('https://api.example.com/users');
```

## 📦 Module System Support

QuantShield is an **ES Module (ESM) package**. It works with modern JavaScript build tools.

### ✅ **ES Modules (Recommended)**

```javascript
import QuantShield from 'qclair-quantshield';

await QuantShield.initialize('https://your-quantshield-proxy.com', {
  autoProtect: true,
  allowedDomains: ['api.example.com']
});
```

### ✅ **TypeScript Support**

```typescript
import QuantShield from 'qclair-quantshield';

// Full type definitions included - no @types package needed!
await QuantShield.initialize('https://your-quantshield-proxy.com', {
  autoProtect: true,
  allowedDomains: ['api.example.com']
});
```

### 🎯 **Build Tool Compatibility**

| Build Tool | Support | Notes |
|------------|---------|-------|
| **Vite** | ✅ Full | Zero config needed |
| **Webpack 5** | ✅ Full | Zero config needed |
| **Rollup** | ✅ Full | Zero config needed |
| **esbuild** | ✅ Full | Zero config needed |
| **Create React App** | ✅ Full | Zero config needed |
| **Next.js** | ✅ Full | Use in client components |
| **Parcel** | ✅ Full | Zero config needed |

**Note**: This package is browser-only (not for Node.js servers). Use it in frontend applications only.

## 🌟 Framework Integration

### React (Recommended Pattern)

```jsx
import React, { useEffect, useState } from 'react';
import QuantShield from 'qclair-quantshield';

function App() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    async function initSecurity() {
      try {
        await QuantShield.initialize('https://your-quantshield-proxy.com', {
          autoProtect: true,
          allowedDomains: ['api.example.com']
        });
        
        // Optional: Enable automatic key rotation every 10 minutes
        QuantShield.enableAutoRefresh(10);
        
        setIsReady(true);
      } catch (error) {
        console.error('QuantShield initialization failed:', error);
        setIsReady(true); // Allow app to load even if encryption fails
      }
    }
    
    initSecurity();
    
    // Cleanup on unmount
    return () => {
      QuantShield.disableAutoRefresh();
    };
  }, []);

  if (!isReady) {
    return <div>Loading security layer...</div>;
  }

  return <div>Your App Content</div>;
}
```

### Vue.js

```javascript
import { onMounted } from 'vue';
import QuantShield from 'qclair-quantshield';

export default {
  setup() {
    onMounted(async () => {
      await QuantShield.initialize('https://your-quantshield-proxy.com', {
        autoProtect: true,
        allowedDomains: ['api.example.com']
      });
    });
  }
};
```

### Next.js (Client Component)

```tsx
'use client'; // Mark as client component

import { useEffect, useState } from 'react';
import QuantShield from 'qclair-quantshield';

export default function RootLayout({ children }) {
  const [ready, setReady] = useState(false);
  
  useEffect(() => {
    QuantShield.initialize('https://your-quantshield-proxy.com', {
      autoProtect: true,
      allowedDomains: ['api.example.com']
    }).then(() => setReady(true));
  }, []);

  return <html><body>{children}</body></html>;
}
```javascript
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import QuantShield from 'qclair-quantshield';

async function startApp() {
  // Initialize QuantShield before creating Vue app
  await QuantShield.init();
  await QuantShield.initializeHandshake();
  QuantShield.applyPatchFetch();
  QuantShield.applyPatchXHR();
  
  const app = createApp(App);
  app.mount('#app');
}

startApp();
```

```vue
<!-- Any component - requests automatically encrypted -->
<template>
  <div>{{ userData }}</div>
</template>

<script>
export default {
  async mounted() {
    // Automatically encrypted request
    const response = await fetch('/api/user/data');
    this.userData = await response.json();
  }
}
</script>
```

### Svelte / SvelteKit

```javascript
// src/routes/+layout.js
import QuantShield from 'qclair-quantshield';

export async function load() {
  // Initialize before any page loads
  await QuantShield.init();
  await QuantShield.initializeHandshake();
  QuantShield.applyPatchFetch();
  QuantShield.applyPatchXHR();
  
  return { quantshieldReady: true };
}
```

```svelte
<!-- Any Svelte component -->
<script>
  import { onMount } from 'svelte';
  
  let users = [];
  
  onMount(async () => {
    // Automatically encrypted request
    const response = await fetch('/api/users');
    users = await response.json();
  });
</script>

{#each users as user}
  <div>{user.name}</div>
{/each}
```

### Vanilla JavaScript

```html
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Secure App</title>
</head>
<body>
    <div id="app"></div>
    
    <script type="module">
        import QuantShield from 'qclair-quantshield';
        
        // Initialize immediately
        async function init() {
            await QuantShield.init();
            await QuantShield.initializeHandshake();
            QuantShield.applyPatchFetch();
            QuantShield.applyPatchXHR();
            
            console.log('🛡️ All requests now encrypted');
            
            // Load your app after QuantShield is ready
            loadApp();
        }
        
        function loadApp() {
            // All these requests are automatically encrypted
            fetch('/api/data').then(res => res.json());
            
            const xhr = new XMLHttpRequest();
            xhr.open('GET', '/api/users');
            xhr.send();
        }
        
        init();
    </script>
</body>
</html>
```

## �️ Global Protection Scope

**Once initialized, QuantShield automatically protects ALL HTTP traffic in your application:**

| Request Type | Automatically Protected | Example |
|--------------|------------------------|---------|
| **fetch()** | ✅ Yes | `fetch('/api/data')` |
| **XMLHttpRequest** | ✅ Yes | `xhr.open('GET', '/api')` |
| **Axios** | ✅ Yes | `axios.get('/api')` |
| **jQuery AJAX** | ✅ Yes | `$.get('/api')` |
| **Third-party libraries** | ✅ Yes | Any library using fetch/XHR |

### 🎯 Key Benefits

- **�🔧 Zero Code Changes**: No need to modify existing API calls
- **🌐 Global Coverage**: Protects requests from ANY component or library
- **📦 Framework Agnostic**: Works with React, Vue, Svelte, Vanilla JS
- **🚀 Initialize Once**: Set up in your main app file and forget about it
- **🔒 Transparent Encryption**: Developers use normal fetch/XHR syntax

### ⚡ Third-Party Library Support

QuantShield automatically encrypts requests from popular libraries:

```javascript
// All of these are automatically encrypted after QuantShield.init()

// Axios
import axios from 'axios';
const response = await axios.get('/api/users'); // ✅ Encrypted

// jQuery  
import $ from 'jquery';
$.get('/api/data', (data) => console.log(data)); // ✅ Encrypted

// Superagent
import superagent from 'superagent';
const res = await superagent.get('/api/posts'); // ✅ Encrypted

// Any custom HTTP library using fetch/XHR under the hood
```

## 🔧 Configuration

### Custom Server and Domains

```javascript
// Custom QuantShield server
await QuantShield.initializeHandshake('https://your-server.com');

// Specify which domains to encrypt
QuantShield.applyPatchFetch('https://your-proxy.com/decrypt-and-forward');

QuantShield.applyPatchXHR(
  'https://your-proxy.com/decrypt-and-forward',
  ['api.example.com', 'secure.mysite.com'] // Only these domains
);
```

### Environment-Based Configuration

```javascript
// Production vs Development setup
const config = {
  production: {
    serverUrl: 'https://quantshield-proxy.yourcompany.com',
    proxyUrl: 'https://quantshield-proxy.yourcompany.com/decrypt-and-forward',
    allowedDomains: ['api.yourcompany.com', 'secure.yourcompany.com']
  },
  development: {
    serverUrl: 'http://localhost:7000',  // Local QuantShield proxy during development
    proxyUrl: 'http://localhost:7000/decrypt-and-forward', 
    allowedDomains: ['localhost:3001', 'dev.api.com']
  }
};

const env = process.env.NODE_ENV || 'development';
const { serverUrl, proxyUrl, allowedDomains } = config[env];

await QuantShield.initializeHandshake(serverUrl);
QuantShield.applyPatchFetch(proxyUrl);
QuantShield.applyPatchXHR(proxyUrl, allowedDomains);
```

### Conditional Initialization

```javascript
// Only enable in production or when explicitly enabled
async function initQuantShieldIfNeeded() {
  if (process.env.NODE_ENV === 'production' || process.env.ENABLE_QUANTSHIELD) {
    try {
      await QuantShield.init();
      await QuantShield.initializeHandshake();
      QuantShield.applyPatchFetch();
      QuantShield.applyPatchXHR();
      console.log('🛡️ QuantShield enabled');
      return true;
    } catch (error) {
      console.warn('⚠️ QuantShield failed to initialize:', error);
      return false;
    }
  } else {
    console.log('🔓 QuantShield disabled in development');
    return false;
  }
}
```

### Environment Detection

```javascript
// Works in both browser and Node.js
if (typeof window !== 'undefined') {
  // Browser environment
  console.log('Running in browser');
} else {
  // Node.js environment  
  console.log('Running in Node.js');
}

await QuantShield.init(); // Works in both environments
```

## 📚 API Reference

### Core Methods

#### `QuantShield.initialize(serverUrl, options?)`
**Recommended**: All-in-one initialization method.

```typescript
await QuantShield.initialize(serverUrl: string, options?: {
  autoProtect?: boolean;     // Auto-apply patches (default: true)
  allowedDomains?: string[]; // Domains to intercept (default: [])
}): Promise<boolean>
```

**Example:**
```javascript
await QuantShield.initialize('https://your-quantshield-proxy.com', {
  autoProtect: true,
  allowedDomains: ['api.example.com', 'secure.api.com']
});
```

---

#### `QuantShield.init()`
Initialize the WebAssembly crypto module.

```javascript
await QuantShield.init(): Promise<boolean>
```

---

#### `QuantShield.initializeHandshake(serverUrl, forceNew?)`
Perform ML-KEM-1024 key exchange with the QuantShield server.

```typescript
await QuantShield.initializeHandshake(
  serverUrl: string,
  forceNew?: boolean  // Force new handshake even if session exists
): Promise<HandshakeResult>
```

**Returns:**
```typescript
{
  success: boolean;
  uid: string;      // Session unique identifier
  cached: boolean;  // Whether session was restored from cache
}
```

---

#### `QuantShield.applyPatchFetch(proxyUrl, allowedDomains?)`
Patch the global `fetch()` function for automatic encryption.

```javascript
QuantShield.applyPatchFetch(
  'http://localhost:7000/decrypt-and-forward',
  ['api.example.com']  // Optional: filter by domain
): void
```

---

#### `QuantShield.applyPatchXHR(proxyUrl, allowedDomains?)`
Patch `XMLHttpRequest` (also intercepts Axios requests) for automatic encryption.

```javascript
QuantShield.applyPatchXHR(
  'http://localhost:7000/decrypt-and-forward',
  ['api.example.com', 'secure.api.com']
): void
```

---

### Key Rotation Methods

#### `QuantShield.enableAutoRefresh(intervalMinutes?)`
**New in v1.0.12**: Enable automatic key rotation.

```javascript
QuantShield.enableAutoRefresh(10); // Refresh every 10 minutes (default)
```

**Features:**
- Automatically performs new handshake at specified interval
- Generates new UID + encryption key
- Non-blocking (doesn't interrupt ongoing requests)
- Prevents concurrent refreshes

---

#### `QuantShield.disableAutoRefresh()`
Disable automatic key rotation.

```javascript
QuantShield.disableAutoRefresh();
```

---

### Session Management (Internal)

These methods are used internally by the SDK. Most users won't need them.

#### `hasValidSession()` 
Check if a valid session exists (has UID + encryption key).

#### `clearSession()`
Clear current session from sessionStorage.

#### `getUID()`
Get current session UID.

#### `getStatus()`
Get initialization status object.

## 🔒 Security Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client App    │───▶│ QuantShield SDK │───▶│ QuantShield     │
│                 │    │ (This Package)  │    │ Proxy Server    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                ▲                       │
                                │                       ▼
                         ┌─────────────┐         ┌─────────────────┐
                         │   ML-KEM    │         │   Target API    │
                         │ Handshake   │         │    Server       │
                         └─────────────┘         └─────────────────┘
```

1. **Handshake**: Client and server exchange keys using post-quantum ML-KEM
2. **Request**: Client encrypts HTTP request with AES-GCM using derived key  
3. **Proxy**: QuantShield server decrypts and forwards to target API
4. **Response**: Server encrypts API response and sends back to client
5. **Decryption**: Client automatically decrypts response

## 🎯 Browser Compatibility

- ✅ Chrome 57+ (WebAssembly support)
- ✅ Firefox 52+ (WebAssembly support) 
- ✅ Safari 11+ (WebAssembly support)
- ✅ Edge 16+ (WebAssembly support)

## 📁 Package Structure

```
qclair-quantshield/
├── src/
│   ├── index.js          # Main entry point
│   ├── QuantShield.js    # Core SDK implementation  
│   ├── wasm_exec.js      # Go WASM runtime bridge
│   └── index.d.ts        # TypeScript definitions
├── wasm/
│   └── crypto.wasm.gz    # Compressed WASM binary
├── package.json
└── README.md
```

## 🏗️ Production Build Support

### ✅ **WASM Files Are Handled Automatically**

Modern bundlers (Vite, Webpack 5, Rollup) automatically detect and include the WASM file in your production build:

```bash
# React/Vite build process:
npm run build

# ✅ WASM file is automatically:
# 1. Detected in node_modules/qclair-quantshield/wasm/
# 2. Copied to build/dist output
# 3. Loaded at runtime via import.meta.url
# 4. Cached by browser for performance
```

### 🎯 **Build Tool Compatibility**

| Build Tool | WASM Support | Configuration |
|------------|--------------|---------------|
| **Vite** | ✅ Automatic | None needed |
| **Webpack 5** | ✅ Automatic | None needed |
| **Create React App** | ✅ Automatic | None needed |
| **Next.js 13+** | ✅ Automatic | None needed (asyncWebAssembly enabled by default) |
| **Rollup** | ✅ Automatic | None needed |

###  **Deployment Platforms**

Works out-of-the-box on all major platforms:
- ✅ **Vercel** - Zero config
- ✅ **Netlify** - Zero config
- ✅ **Cloudflare Pages** - Zero config
- ✅ **AWS Amplify** - Zero config
- ✅ **GitHub Pages** - Zero config

### 🔍 **Verify WASM in Production**

```bash
# After building, check WASM is included:
find build -name "*.wasm*"   # Create React App
find dist -name "*.wasm*"    # Vite

# Test production build locally:
npx serve -s build           # CRA
npm run preview              # Vite
```

## ❓ Frequently Asked Questions

### Q: Do I need to modify my existing API calls?
**A: No!** QuantShield works transparently. After initialization, all your existing `fetch()` and `XMLHttpRequest` calls are automatically encrypted without any code changes.

### Q: Does it work with Axios, jQuery, and other HTTP libraries?
**A: Yes!** QuantShield patches the underlying `fetch` and `XMLHttpRequest` APIs, so any library that uses these (including Axios, jQuery, Superagent, etc.) is automatically protected.

### Q: Where should I initialize QuantShield in my app?
**A:** Initialize once in your main app file:
- **React**: `App.js` or `_app.js` (Next.js)
- **Vue**: `main.js`
- **Svelte**: `+layout.js` or `app.html`
- **Vanilla JS**: `index.html` or main entry file

### Q: Will it slow down my application?
**A: Minimal impact.** The WebAssembly crypto functions are highly optimized. The main overhead is the initial handshake (happens once) and AES-GCM encryption (very fast).

### Q: Does it work with SSR (Server-Side Rendering)?
**A: Yes for client-side requests.** QuantShield initializes on the client side and protects browser-initiated requests. Server-side requests during SSR are not affected.

### Q: Can I use it with React Native?
**A: Yes!** There's a separate package for React Native. Use `qclair-quantshield-react-native-android` for React Native apps.

### Q: Does it work with CommonJS projects?
**A: No.** This package is **ESM-only**. Modern projects (React, Vue, Next.js, Vite) all support ESM by default. If you're on an older setup, consider migrating to ESM or using the CDN version.

### Q: What Node.js version is required?
**A:** Node.js 16+ is required for WebAssembly and ES modules support. Most modern projects already use Node 16+.

### Q: Does it work with older bundlers like Webpack 4?
**A:** For older bundlers, use dynamic imports. Modern bundlers (Webpack 5, Vite, Rollup, esbuild) have full support.

### Q: What happens if QuantShield fails to initialize?
**A:** Your app continues to work normally with unencrypted HTTP requests. Always wrap initialization in try/catch blocks for production apps.

## � React Native Support

This package is for **web browsers only**. For React Native apps, use the dedicated package:

```bash
npm install qclair-quantshield-react-native-android
```

**Why separate packages?**
- React Native doesn't support WebAssembly like browsers do
- Different networking APIs (no `XMLHttpRequest` or `fetch` in the same way)
- Native bridge required for ML-KEM crypto operations

## ⚠️ Important Notes

- **Initialize Early**: Call `QuantShield.init()` before making any HTTP requests
- **Initialize Once**: Multiple initializations can cause conflicts
- **Global Effect**: Once initialized, ALL requests in your app are protected
- **Async Nature**: Always `await` the initialization functions
- **Error Handling**: Wrap initialization in try/catch for production apps
- **Domain Filtering**: Only requests to specified domains are encrypted (configurable)

## 🐛 Troubleshooting

### Error: "WebAssembly.instantiate(): expected magic word 00 61 73 6d, found 3c 21 64 6f"

**What it means**: The WASM file is returning HTML (a 404 error page) instead of the actual WebAssembly binary.

**Common causes**:
1. Bundler not configured to serve files from `node_modules`
2. WASM file not being copied to build output
3. Incorrect path resolution

**Quick fixes by bundler**:

#### Vite (Most Common)

Add to your `vite.config.ts` or `vite.config.js`:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  
  // Allow serving files from node_modules
  server: {
    fs: {
      allow: ['.', '../node_modules/qclair-quantshield/wasm']
    }
  },
  
  // Treat WASM files as assets
  assetsInclude: ['**/*.wasm', '**/*.wasm.gz'],
  
  // Don't pre-bundle QuantShield
  optimizeDeps: {
    exclude: ['qclair-quantshield']
  }
})
```

#### Webpack 5

Add to your `webpack.config.js`:

```javascript
module.exports = {
  experiments: {
    asyncWebAssembly: true,
    topLevelAwait: true
  },
  module: {
    rules: [
      {
        test: /\.wasm$/,
        type: 'asset/resource'
      }
    ]
  }
}
```

#### Create React App (CRA)

Install `react-app-rewired`:

```bash
npm install --save-dev react-app-rewired
```

Create `config-overrides.js`:

```javascript
module.exports = function override(config) {
  config.experiments = {
    asyncWebAssembly: true,
    topLevelAwait: true
  };
  return config;
};
```

Update `package.json`:

```json
{
  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build"
  }
}
```

#### Next.js

Add to `next.config.js`:

```javascript
module.exports = {
  webpack: (config) => {
    config.experiments = {
      asyncWebAssembly: true,
      layers: true
    };
    return config;
  }
}
```

### Error: "Failed to fetch" or Network Error

**Cause**: CORS issues or incorrect server URL

**Fix**:
1. Ensure your QuantShield proxy server is running
2. Check the server URL in `initialize()` is correct
3. For local development, use `http://localhost:7000` (not `127.0.0.1`)
4. Check browser console for detailed error messages

### WASM File Not Found in Production Build

**Symptoms**: Works in development but fails in production

**Fix**: Verify WASM file is in build output:

```bash
# For Vite
ls -la dist/assets/*.wasm*

# For CRA
ls -la build/static/**/*.wasm*
```

If missing, ensure `assetsInclude` is configured in your bundler.

### Initialization Takes Too Long

**Cause**: Large WASM file or slow network

**Fix**:
1. The WASM file is already gzipped (~800KB)
2. Enable HTTP/2 on your server for faster loading
3. Consider preloading the WASM file:

```javascript
// Preload WASM before user interaction
const preloadLink = document.createElement('link');
preloadLink.rel = 'preload';
preloadLink.href = '/path/to/crypto.wasm.gz';
preloadLink.as = 'fetch';
preloadLink.crossOrigin = 'anonymous';
document.head.appendChild(preloadLink);
```

### "Go is not defined" Error

**Cause**: `wasm_exec.js` not loaded

**Fix**: This should be automatic. If you see this error:
1. Check that `src/wasm_exec.js` exists in the package
2. Ensure you're importing from `qclair-quantshield` (not a custom path)
3. Clear your bundler cache: `rm -rf node_modules/.vite` or `rm -rf node_modules/.cache`

### Need More Help?

**Diagnostic Tool**: Use our diagnostic script to identify the issue:

```javascript
import QuantShield from 'qclair-quantshield';

// Add detailed logging
console.log('Starting QuantShield initialization...');

try {
  await QuantShield.initialize('https://your-server.com', {
    autoProtect: true,
    allowedDomains: ['api.example.com']
  });
  console.log('✅ QuantShield initialized successfully');
} catch (error) {
  console.error('❌ QuantShield initialization failed:', error);
  console.error('Error details:', {
    message: error.message,
    stack: error.stack
  });
}
```

**Get Support**:
1. Check the [WASM-FIX-GUIDE.md](https://github.com/qclairvoyance12/QuantShield-Client-SDK/blob/main/WASM-FIX-GUIDE.md) for detailed solutions
2. Open an issue on [GitHub](https://github.com/qclairvoyance12/QuantShield-Client-SDK/issues) with:
   - Your bundler name and version
   - Full error message
   - Your config file
   - Output of `npm list qclair-quantshield`

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- [GitHub Repository](https://github.com/qclairvoyance12/QuantShield-Client-SDK)
- [Documentation](https://github.com/qclairvoyance12/QuantShield-Client-SDK#readme)
- [Issues](https://github.com/qclairvoyance12/QuantShield-Client-SDK/issues)
- [NPM Package](https://www.npmjs.com/package/qclair-quantshield)

---

**Made with ❤️ by [Qclair](https://github.com/qclairvoyance12)**