npm package: @one-payments/adapters-crypto-js
Description: CryptoJS-based crypto adapter for One Payments SDK (WebView compatible)
Author: One Payments
Latest version: 1.0.1

# @one-payments/adapters-crypto-js

CryptoJS-based crypto adapter for One Payments SDK. This adapter provides cryptographic operations using the `crypto-js` library instead of the native Web Crypto API (`crypto.subtle`).

## When to Use This Package

Use this adapter in environments where the Web Crypto API (`crypto.subtle`) is **not available**:

- ✅ **React Native WebView** - The primary use case
- ✅ **Legacy browsers** - Browsers that don't support Web Crypto API
- ✅ **Server-side rendering** - Node.js environments without crypto.subtle
- ✅ **Testing environments** - When you need consistent crypto behavior

## Installation

```bash
npm install @one-payments/adapters-crypto-js
# or
yarn add @one-payments/adapters-crypto-js
# or
pnpm add @one-payments/adapters-crypto-js
```

## Usage

### Basic Usage (Browser/WebView)

```javascript
import { CryptoJSAdapter } from '@one-payments/adapters-crypto-js';
import { WebStorageAdapter, WebHttpAdapter, WebTimerAdapter } from '@one-payments/adapters-web';

// Create hybrid adapters: crypto-js for crypto, web adapters for everything else
const adapters = {
  crypto: new CryptoJSAdapter(),
  storage: new WebStorageAdapter(),
  http: new WebHttpAdapter(),
  timer: new WebTimerAdapter()
};

// Use with One Payments SDK
const paymentElement = document.getElementById('payment');
paymentElement.adapters = adapters;
```

### React Native WebView (Recommended)

This adapter is automatically used in `@one-payments/react-native` package. The HTML template loads it from unpkg:

```html
<script type="module">
  import { CryptoJSAdapter } from 'https://unpkg.com/@one-payments/adapters-crypto-js@latest/dist/index.js';
  import { WebStorageAdapter, WebHttpAdapter, WebTimerAdapter } from 'https://unpkg.com/@one-payments/adapters-web@latest/dist/index.js';

  const adapters = {
    crypto: new CryptoJSAdapter(),
    storage: new WebStorageAdapter(),
    http: new WebHttpAdapter(),
    timer: new WebTimerAdapter()
  };
</script>
```

### Direct Usage (Testing/Development)

```typescript
import { CryptoJSAdapter } from '@one-payments/adapters-crypto-js';

const crypto = new CryptoJSAdapter();

// SHA-256 hashing
const hash = await crypto.sha256('Hello World');
console.log(hash); // "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e"

// HMAC-SHA256
const hmac = await crypto.hmacSHA256('secret-key', 'message');
console.log(hmac);

// UUID v4 generation
const id = crypto.uuid();
console.log(id); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Random bytes
const bytes = crypto.randomBytes(16);
console.log(bytes); // Uint8Array(16) [...]
```

## API Reference

### `CryptoJSAdapter`

Implements the `CryptoAdapter` interface from `@one-payments/core`.

#### Methods

##### `sha256(input: string | Uint8Array): Promise<string>`

Computes SHA-256 hash of the input.

**Parameters:**
- `input` - String or Uint8Array to hash

**Returns:**
- Promise resolving to hex-encoded hash string

##### `hmacSHA256(secret: string, message: string): Promise<string>`

Computes HMAC-SHA256 signature.

**Parameters:**
- `secret` - Secret key for HMAC
- `message` - Message to sign

**Returns:**
- Promise resolving to hex-encoded HMAC string

##### `uuid(): string`

Generates a UUID v4 identifier.

**Returns:**
- UUID v4 string (e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479")

##### `randomBytes(length: number): Uint8Array`

Generates cryptographically random bytes.

**Parameters:**
- `length` - Number of bytes to generate

**Returns:**
- Uint8Array of random bytes

## Architecture

This package is part of the One Payments adapter ecosystem:

```
@one-payments/core (interfaces)
    ↓
@one-payments/adapters-crypto-js (crypto-js implementation)
@one-payments/adapters-web (browser APIs)
@one-payments/adapters-native (React Native APIs)
    ↓
@one-payments/react-native (WebView wrapper)
@one-payments/react (React wrapper)
@one-payments/vue (Vue wrapper)
```

## Why This Package Exists

### The Problem

React Native WebView environments don't support the Web Crypto API (`crypto.subtle`), which causes errors like:

```
undefined is not an object (evaluating 'crypto.subtle.importKey')
```

### The Solution

This package provides a drop-in replacement using `crypto-js`, a pure JavaScript implementation that works in any environment. The crypto-js library is **bundled** into this package, so it can be loaded via unpkg CDN without external dependencies.

### Comparison with Web Crypto API

| Feature | Web Crypto API | crypto-js (this package) |
|---------|----------------|-------------------------|
| Browser Support | Modern browsers only | All browsers |
| WebView Support | ❌ No | ✅ Yes |
| Performance | Faster (native) | Slower (JavaScript) |
| Bundle Size | 0 KB (native) | ~100 KB (bundled) |
| Node.js Support | Limited | ✅ Yes |

## Package Structure

```
adapters-crypto-js/
├── src/
│   ├── crypto.ts       # CryptoJSAdapter implementation
│   └── index.ts        # Public exports
├── dist/               # Built files (published)
│   ├── index.js        # ES module
│   ├── index.cjs       # CommonJS module
│   └── index.d.ts      # TypeScript definitions
├── package.json
├── tsconfig.json
├── tsup.config.ts      # Build configuration
└── README.md
```

## Dependencies

- **@one-payments/core** - Core types and interfaces
- **crypto-js** - JavaScript cryptography library (bundled)

## Development

```bash
# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch mode (auto-rebuild on changes)
pnpm dev

# Type checking
pnpm typecheck

# Linting
pnpm lint
```

## Publishing

```bash
# Build and publish to npm
pnpm build
pnpm publish --access public
```

## Related Packages

- [@one-payments/core](../core) - Core SDK and types
- [@one-payments/adapters-web](../adapters-web) - Web platform adapters
- [@one-payments/adapters-native](../adapters-native) - React Native platform adapters
- [@one-payments/react-native](../react-native) - React Native wrapper

## License

MIT