npm package: @sbwcws/musa
Description: MUSA - Privacy-first invisible captcha widget
Author: SBWCWS
Latest version: 1.0.1

# @sbwcws/musa

Privacy-first, invisible captcha widget for bot protection. MUSA protects your websites from bots using browser fingerprinting and behavioral analysis, showing challenges only when necessary.

## Installation

```bash
npm install @sbwcws/musa
```

Or include via CDN:

```html
<script src="https://unpkg.com/@wcws/musa/dist/musa.min.js"></script>
```

## Quick Start

### JavaScript/TypeScript

```typescript
import { Musa } from '@sbwcws/musa';

// Initialize the widget
const musa = new Musa({
  siteKey: 'your-site-key',
  onSuccess: (token) => {
    console.log('Verification successful:', token);
    // Send token to your server for validation
  },
  onError: (error) => {
    console.error('Verification failed:', error);
  },
});

// Render the widget in a container
musa.render('#captcha-container');
```

### Script Tag

```html
<div id="captcha-container"></div>

<script src="https://unpkg.com/@wcws/musa/dist/musa.min.js"></script>
<script>
  const musa = new window.musa.Musa({
    siteKey: 'your-site-key',
    onSuccess: function(token) {
      document.getElementById('musa-token').value = token;
    }
  });
  musa.render('#captcha-container');
</script>
```

## Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `siteKey` | `string` | Yes | Your MUSA site key from the dashboard |
| `onSuccess` | `(token: string) => void` | Yes | Callback when verification succeeds |
| `onError` | `(error: Error) => void` | No | Callback when verification fails |
| `onExpire` | `() => void` | No | Callback when token expires |
| `theme` | `'light' \| 'dark' \| 'auto'` | No | Widget theme (default: 'auto') |
| `size` | `'normal' \| 'compact'` | No | Widget size (default: 'normal') |
| `language` | `string` | No | Language code (default: browser language) |

## Methods

### `render(container: string | HTMLElement)`

Renders the widget in the specified container.

```typescript
musa.render('#my-container');
// or
musa.render(document.getElementById('my-container'));
```

### `reset()`

Resets the widget to its initial state.

```typescript
musa.reset();
```

### `remove()`

Removes the widget from the DOM.

```typescript
musa.remove();
```

### `getResponse()`

Returns the current verification token, or `null` if not verified.

```typescript
const token = musa.getResponse();
```

## Server-Side Verification

After receiving the token on your server, verify it using the `@wcws/musa-server` package:

```typescript
import { verifyToken } from '@wcws/musa-server';

const result = await verifyToken({
  secretKey: 'your-secret-key',
  token: tokenFromClient,
  remoteip: clientIpAddress, // optional
});

if (result.success) {
  // Token is valid
} else {
  // Token is invalid
}
```

## React Integration

For React applications, use the `@wcws/musa-react` package:

```bash
npm install @wcws/musa-react
```

```tsx
import { MusaWidget } from '@wcws/musa-react';

function MyForm() {
  return (
    <form>
      <MusaWidget
        siteKey="your-site-key"
        onSuccess={(token) => console.log(token)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}
```

## How It Works

MUSA uses a multi-layered approach to bot detection:

1. **Invisible Mode (85% of traffic)** - Pure fingerprint + behavioral analysis. Legitimate users pass automatically.
2. **Checkbox Mode (10% of traffic)** - Simple click verification for medium-risk requests.
3. **Interactive Challenge (5% of traffic)** - Slide puzzle for high-risk requests.

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT

## Links

- [Dashboard](https://musa.wcws.net)
- [Documentation](https://musa.wcws.net/docs)