# Hoptcha Client for Django

Hoptcha is a modern CAPTCHA provider designed for seamless integration into web applications.
This package, `django-hoptcha`, allows Django developers to quickly integrate Hoptcha CAPTCHA validation into their views with minimal effort.

---

## 📚 Table of Contents

* [Features](#features)
* [Installation](#installation)
* [Quick Start](#quick-start)

  * [1. Configure settings](#1-configure-settings)
  * [2. Protect a view with CAPTCHA](#2-protect-a-view-with-captcha)
  * [3. Use JavaScript integration](#3-use-javascript-integration)
* [Advanced Usage](#advanced-usage)

  * [Custom Rate-Limiting Logic](#custom-rate-limiting-logic)
  * [Combining with Django-Ratelimit](#combining-with-django-ratelimit)
  * [Custom CAPTCHA UI Rendering](#custom-captcha-ui-rendering)
* [Customization](#customization)
* [License](#license)

---

## ✅ Features

* 🔒 Server-side CAPTCHA verification with client and secret keys
* 🧠 Rate-limiting and conditional CAPTCHA fallback
* 🤩 Easy integration via decorators
* ⚙️ Customizable request identification (e.g., IP + user ID)
* 🧰 Built-in support for Django views and REST APIs
* 🛆 Lightweight and production-ready
* 🎨 Custom iframe rendering with `{% captcha_iframe %}`

---

## 🛠️ Installation

```bash
pip install django-hoptcha
```

Add to `INSTALLED_APPS` in `settings.py`:

```python
INSTALLED_APPS = [
    ...,
    'django_hoptcha',
]
```

Collect static files:

```bash
python manage.py collectstatic
```

---

## 🚀 Quick Start

### 1. Configure settings

Add the following to your `settings.py`:

```python
CAPTCHA_VERIFY_URL = 'https://your-hoptcha-domain.com/captcha/validate/'
CAPTCHA_GENERATE_URL = 'https://your-hoptcha-domain.com/captcha/'
CAPTCHA_PUBLIC_KEY = 'your-client-key'
CAPTCHA_PRIVATE_KEY = 'your-secret-key'
```

> These credentials are provided by the Hoptcha service when you register your application.

---

### 2. Protect a view with CAPTCHA

Import the decorator and apply it to any Django view:

```python
from django_hoptcha.decorators import hoptcha_protected

@hoptcha_protected()
def my_view(request):
    return JsonResponse({'success': True})
```

This will:

* Track repeated requests using the IP address.
* Require CAPTCHA after 5 attempts (default).
* Verify the token via the configured Hoptcha endpoint.

---

### 3. Use JavaScript integration

In your template:

```html
{% load static hoptcha_tags %}
{% captcha_placeholder %}
<script src="{% static 'django_hoptcha/hoptcha.js' %}"></script>
```

Or if you want to place captcha placeholder dynamically use `<div id="hoptcha-container"></div>`.
Alternatively you can use `{% captcha_iframe %}` if your captcha is static.


In your frontend JS:

```javascript
function startPasswordReset() {
    const payload = {
        studentId: String(studentId),
        captcha_token: 'initial'
    };

    hoptchaPost('/users/send-reset/', payload, function() {
        renderResetOTPEntry();
    }, function(error) {
        showError(error);
    });
}
```

You may optionally pass a custom onCaptcha renderer if you want to override the default iframe design:

```javascript
hoptchaPost('/users/send-reset/', payload, onSuccess, onError, function customCaptchaRenderer(url) {
    // Your custom UI logic here
    showCustomModal();
    renderMyCustomCaptchaIframe(url);
});
```

---

## ⚙️ Advanced Usage

### Custom Rate-Limiting Logic

You can customize how repeated attempts are tracked using a key function:

```python
def ip_and_student_id(request):
    ip = request.META.get("REMOTE_ADDR", "unknown")
    student_id = request.POST.get("studentId", "")
    return f"{ip}:{student_id}"
```

Apply it like this:

```python
@hoptcha_protected(threshold=5, timeout=300, key=ip_and_student_id)
def send_reset_code(request):
    ...
```

---

### Combining with Django-Ratelimit

This package works seamlessly with [`django-ratelimit`](https://pypi.org/project/django-ratelimit/):

```python
from ratelimit.decorators import ratelimit
from django_hoptcha.decorators import hoptcha_protected

@ratelimit(key='ip', rate='15/m', method='POST', block=True)
@hoptcha_protected(threshold=5, timeout=300)
def secure_view(request):
    ...
```

The `@ratelimit` decorator enforces strict rate limits while `@hoptcha_protected` provides a soft CAPTCHA fallback.

### Custom CAPTCHA UI Rendering

You can override the default iframe and style using the optional onCaptcha parameter in the hoptchaPost() JavaScript function. This is useful if you want to match your app’s branding or use modals.

```javascript
hoptchaPost('/endpoint', payload, onSuccess, onError, function renderCustom(url) {
    // Replace container with your custom implementation
    $('#myCustomCaptchaArea').html(`<iframe src="${url}"></iframe>`);
});
```

---

## 🔧 Customization

| Parameter   | Description                                                  | Default       |
|-------------|--------------------------------------------------------------|---------------|
| `key`       | Function or string to identify requestor (IP, user ID, etc.) | `ip`          |
| `threshold` | Number of allowed attempts before CAPTCHA is required        | `5`           |
| `timeout`   | Time in seconds to reset attempt count                       | `300` (5 min) |
| `backoff`   | Exponentially increase timeout if repeatedly exceeded        | `False`       |
| `response`  | Optional custom response function on CAPTCHA failure         | `None`        |
| `exempt_if` | Skip protection for trusted users                            | For staff     |
| `methods`   | HTTP methods to track (POST, GET, etc.)                      | POST          |
| `shared`    | Share same attempts counter among all endpoints              | `False`       |
| `type`      | Type of CAPTCHA do display (sliding, pointing, random)       | `random`      |

---

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

Contributions are welcome! Open issues or pull requests on [GitHub](https://github.com/yourusername/django-hoptcha).