AI Integration Generator

Generate a complete ByeBot CAPTCHA integration for {PLATFORM}.

ByeBot is a GDPR-compliant, proof-of-work CAPTCHA service. It protects forms from bots using browser fingerprinting and computational challenges — no tracking, no cookies, no user data collection.

## How It Works

1. A JavaScript widget runs inside an iframe on the user's page
2. The widget solves a proof-of-work challenge and collects a browser fingerprint
3. On success, a single-use token is injected into the form as a hidden input
4. The server validates this token via a REST API before processing the form

## Frontend Integration

### Script Tag

Include the widget script on any page that needs CAPTCHA protection:

```html
<script src="https://challenge.byebot.de/ray/widget.js"></script>
```

### Widget Container

Add a div with the `captcha-widget` class inside your form:

```html
<form action="/submit" method="POST">
  <!-- your form fields -->

  <div class="captcha-widget" data-sitekey="YOUR_SITE_KEY"></div>

  <button type="submit">Submit</button>
</form>
```

### HTML Attributes

| Attribute             | Required | Description                                                                 |
|-----------------------|----------|-----------------------------------------------------------------------------|
| `class="captcha-widget"` | Yes  | Identifies the container for widget initialization                          |
| `data-sitekey`         | Yes      | Your site's public key (from the ByeBot dashboard)                         |
| `data-token-callback`  | No       | Name of a JS function called with the token on success (supports nested names like `myApp.handleToken`) |

### What Happens Automatically

- The widget renders a CAPTCHA UI inside the div
- On successful verification, a hidden input `<input type="hidden" name="byebot-token" value="...">` is appended to the parent form
- The token is also passed to the callback function if `data-token-callback` is set

### Widget Modes (configured in dashboard, not in code)

- **Auto Solve** — challenge runs automatically in the background (default)
- **Click to Solve** — user clicks a checkbox to start verification
- **Invisible** — no visible UI, runs entirely in the background

### Programmatic Rendering (for SPAs)

For dynamically added forms or single-page applications:

```javascript
// Render widget into a specific container element
window.Byebot.render(document.getElementById('captcha-container'));

// Re-render all captcha-widget divs on the page
window.Byebot.renderAll();
```

### Token Callback Example

```html
<div class="captcha-widget"
     data-sitekey="YOUR_SITE_KEY"
     data-token-callback="onCaptchaVerified">
</div>

<script>
function onCaptchaVerified(token) {
  console.log('CAPTCHA solved, token:', token);
  // Enable submit button, send via AJAX, etc.
}
</script>
```

### Retrieving the Token in JavaScript

```javascript
// After the widget injects the hidden input:
const token = document.querySelector('input[name="byebot-token"]').value;
```

## Server-Side Validation

After receiving the form submission, validate the token on your server before processing anything.

### Endpoint

```
POST https://challenge.byebot.de/validate_token
Content-Type: application/json
```

### Request Body

```json
{
  "api_key": "YOUR_SECRET_API_KEY",
  "token": "TOKEN_FROM_FORM"
}
```

### Response

| Status | Meaning                                    |
|--------|--------------------------------------------|
| 200 OK | Token is valid — returns JSON with challenge metadata |
| 400 Bad Request | Token is invalid, expired, or already used — no body |

On success, the response body contains:

```json
{
  "success": true,
  "sitekey": "abc123def456ghij7890",
  "challenged_at": 1742140800,
  "solve_time_ms": 2340,
  "interactive_solved": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always true on 200 |
| `sitekey` | string | Site key the challenge was solved for |
| `challenged_at` | integer | Unix timestamp (seconds) of challenge creation |
| `solve_time_ms` | integer | Milliseconds from challenge creation to solution |
| `interactive_solved` | boolean | Whether an interactive challenge was completed |

The status code alone is sufficient for basic validation — the body provides optional metadata.

### Example (Node.js fetch)

```javascript
const response = await fetch('https://challenge.byebot.de/validate_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.BYEBOT_API_KEY,
    token: tokenFromForm
  })
});

if (response.ok) {
  // Valid — process the form
  // Optionally parse challenge metadata:
  // const { sitekey, challenged_at, solve_time_ms, interactive_solved } = await response.json();
} else {
  // Invalid — reject the submission
}
```

## Token Properties

- **Single-use**: each token can only be validated once
- **Short-lived**: tokens expire after a few minutes
- **Site-bound**: each token is tied to the site key that generated it

## Security Best Practices

- **Never expose your API key in client-side code** — use environment variables on the server
- **Always validate server-side** — never trust client-side verification alone
- **Validate before expensive operations** — check the token before writing to the database, sending emails, etc.
- **Handle failures gracefully** — show a user-friendly error and allow retry
- **Log validation failures** — monitor for abuse patterns

## Your Task

Generate a complete, production-ready {PLATFORM} integration that includes:

1. **Frontend**: the widget HTML/component with the script tag and `captcha-widget` div, adapted to {PLATFORM}'s conventions and templating system
2. **Backend**: a form handler that extracts the `byebot-token` field and validates it via the REST API before processing the form
3. **Configuration**: use environment variables for the API key (`BYEBOT_API_KEY`) and site key (`BYEBOT_SITE_KEY`)
4. **Error handling**: proper error responses when the token is missing or invalid

Follow {PLATFORM}'s idiomatic patterns, project structure conventions, and best practices. Use the framework's native HTTP client for the validation request. Include brief code comments explaining each step.

## Reference Documentation

For more details, refer to the official ByeBot documentation:

- Full documentation: https://docs.byebot.de
- Getting started: https://docs.byebot.de/docs/getting-started
- Widget configuration: https://docs.byebot.de/docs/widget-configuration
- Server-side validation: https://docs.byebot.de/docs/server-side-validation
- Existing integration guides: https://docs.byebot.de/docs/integrations