django-clickify 0.1.0__tar.gz

django_clickify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Romjan Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_clickify-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.3
+Name: django-clickify
+Version: 0.1.0
+Summary: A Django app to track file downloads with rate limiting, IP filtering, and geolocation.
+License: MIT
+Keywords: django,click,tracker,ratelimit,ipfilter,geolocation
+Author: Romjan Ali
+Author-email: romjanvr5@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: drf
+Requires-Dist: django (>=4.2)
+Requires-Dist: django-ipware (>=4.0)
+Requires-Dist: django-ratelimit (>=4.1)
+Requires-Dist: requests (>=2.20)
+Project-URL: Homepage, https://github.com/romjanxr/django-clickify
+Project-URL: Repository, https://github.com/romjanxr/django-clickify
+Description-Content-Type: text/markdown
+
+# Django Clickify
+
+[![PyPI version](https://badge.fury.io/py/django-clickify.svg)](https://badge.fury.io/py/django-clickify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A simple Django app to track clicks on any link (e.g., affiliate links, outbound links, file downloads) with rate limiting, IP filtering, and geolocation.
+
+## Features
+
+*   **Click Tracking**: Logs every click on a tracked link, including IP address, user agent, and timestamp.
+*   **Geolocation**: Automatically enriches click logs with the country and city of the request's IP address via a web API.
+*   **Rate Limiting**: Prevents abuse by limiting the number of clicks per IP address in a given timeframe.
+*   **IP Filtering**: Easily configure allowlists and blocklists for IP addresses.
+*   **Secure**: Protects against path traversal attacks.
+*   **Django Admin Integration**: Create and manage your tracked links directly in the Django admin.
+*   **Template Tag & DRF View**: Provides both a simple template tag for traditional Django templates and a DRF API view for headless/JavaScript applications.
+
+## Installation
+
+1.  Install the package from PyPI:
+
+    ```bash
+    pip install django-clickify
+    ```
+
+2.  Add `'clickify'` to your `INSTALLED_APPS` in `settings.py`:
+
+    ```python
+    INSTALLED_APPS = [
+        # ...
+        'clickify',
+    ]
+    ```
+
+3.  Run migrations to create the necessary database models:
+
+    ```bash
+    python manage.py migrate
+    ```
+
+4.  **For API support (Optional)**: If you plan to use the DRF view, you must also install `djangorestframework` and add it to your `INSTALLED_APPS`.
+
+    ```bash
+    pip install django-clickify[drf]
+    ```
+    ```python
+    INSTALLED_APPS = [
+        # ...
+        'rest_framework',
+        'clickify',
+    ]
+    ```
+
+## Configuration
+
+### 1. Middleware (for IP Filtering)
+
+To enable the IP allowlist and blocklist feature, add the `IPFilterMiddleware` to your `settings.py`.
+
+```python
+MIDDLEWARE = [
+    # ...
+    'clickify.middleware.IPFilterMiddleware',
+    # ...
+]
+```
+
+### 2. Settings (Optional)
+
+You can customize the behavior of `django-clickify` by adding the following settings to your `settings.py`:
+
+*   `CLICKIFY_GEOLOCATION`: A boolean to enable or disable geolocation. Defaults to `True`.
+*   `CLICKIFY_RATE_LIMIT`: The rate limit for clicks. Defaults to `'5/m'`.
+*   `CLICKIFY_IP_ALLOWLIST`: A list of IP addresses that are always allowed. Defaults to `[]`.
+*   `CLICKIFY_IP_BLOCKLIST`: A list of IP addresses that are always blocked. Defaults to `[]`.
+
+## Testing
+
+To run the tests for this project, you'll need to have `pytest` and `pytest-django` installed. You can install them with:
+
+```bash
+pip install pytest pytest-django
+```
+
+Then, you can run the tests from the root of the project with:
+
+```bash
+poetry run pytest
+```
+
+This will run all the tests in the `tests/` directory.
+
+## Usage
+
+### Option 1: Template-Based Usage
+
+This is the standard way to use the app in traditional Django projects.
+
+#### Step 1: Create a Tracked Link
+
+In your Django Admin, go to the "Clickify" section and create a new "Tracked Link". This target can be any URL you want to track clicks on.
+
+The `Target Url` can point to any type of file (e.g., PDF, ZIP, MP3, MP4, TXT) or any webpage. The link can be hosted anywhere, such as Amazon S3, a personal blog, or an affiliate partner's site.
+
+*   **Name:** `Monthly Report PDF`
+*   **Slug:** `monthly-report-pdf` (this will be auto-populated from the name)
+*   **Target Url:** `https://your-s3-bucket.s3.amazonaws.com/reports/monthly-summary.pdf`
+
+#### Step 2: Include Clickify URLs
+
+In your project's `urls.py`, include the `clickify` URL patterns.
+
+```python
+# your_project/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... your other urls
+    path('track/', include('clickify.urls', namespace='clickify')),
+]
+```
+
+#### Step 3: Create the Tracked Link
+
+In your Django template, use the `track_url` template tag to generate the tracking link. Use the slug of the `TrackedLink` you created in Step 1.
+
+```html
+<!-- your_app/templates/my_template.html -->
+{% load clickify_tags %}
+
+<a href="{% track_url 'monthly-report-pdf' %}">
+  Download Monthly Summary
+</a>
+```
+
+### Option 2: API Usage (for Headless/JS Frameworks)
+
+If you are using a JavaScript frontend (like React, Vue, etc.) or need a programmatic way to get a tracked URL, you can use the DRF API endpoint.
+
+#### Step 1: Create a Tracked Link
+
+Follow Step 1 from the template-based usage above.
+
+#### Step 2: Include Clickify DRF URLs
+
+In your project's `urls.py`, include the `clickify.drf_urls` patterns.
+
+```python
+# your_project/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... your other urls
+    path('api/track/', include('clickify.drf_urls', namespace='clickify-api')),
+]
+```
+
+#### Step 3: Make the API Request
+
+From your frontend, make a `POST` request to the API endpoint using the slug of your `TrackedLink`.
+
+**Endpoint**: `POST /api/track/<slug>/`
+
+A successful request will track the click and return the actual file URL, which you can then use to trigger the click or redirection on the client-side.
+
+**Example using JavaScript `fetch`:**
+
+```javascript
+fetch('/api/track/monthly-report-pdf/', {
+    method: 'POST',
+    headers: {
+        // Include CSRF token if necessary for your setup
+        'X-CSRFToken': 'YourCsrfTokenHere' 
+    }
+})
+.then(response => response.json())
+.then(data => {
+    if (data.target_url) {
+        console.log("Click tracked. Redirecting to:", data.target_url);
+        // Redirect the user to the URL
+        window.location.href = data.target_url;
+    } else {
+        console.error("Failed to track click:", data);
+    }
+})
+.catch(error => {
+    console.error('Error:', error);
+});
+```
+
+**Successful Response (`200 OK`):**
+```json
+{
+    "message": "Click tracked successfully",
+    "target_url": "https://your-s3-bucket.s3.amazonaws.com/reports/monthly-summary.pdf"
+}
+```
+
+**Failure Responses**
+
+If the request fails, you might receive one of the following error responses:
+
+*   **404 Not Found:**
+
+    ```json
+    {
+        "detail": "Not found."
+    }
+    ```
+
+*   **429 Too Many Requests:**
+
+    ```json
+    {
+        "error": "Rate limit exceeded. Please try again later"
+    }
+    ```
+
+*   **403 Forbidden:** (If IP filtering is enabled and the IP is blocked)
+
+    This will typically return a plain text response like:
+    ```
+    IP address blocked.
+    ```
+
+### How It Works
+
+1.  A user clicks a tracked link (`/track/monthly-report-pdf/`) or a `POST` request is sent to the API.
+2.  The view or API view records the click event in the database, associating it with the correct `TrackedLink`.
+3.  The standard view issues a `302 Redirect` to the `target_url`. The API view returns a JSON response containing the `target_url`.
+4.  The user's browser is redirected to the final destination.
+
+This approach is powerful because if you ever need to change the link's destination, you only need to update the `Target Url` in the Django Admin. All your tracked links and API calls will continue to work correctly.
+
+## Contributing
+
+Contributions are welcome! If you'd like to contribute to this project, please follow these steps:
+
+1.  Fork the repository.
+2.  Create a new branch for your feature or bug fix.
+3.  Make your changes and add tests for them.
+4.  Ensure the tests pass by running `poetry run pytest`.
+5.  Create a pull request with a clear description of your changes.

django_clickify-0.1.0/README.md

@@ -0,0 +1,243 @@
+# Django Clickify
+
+[![PyPI version](https://badge.fury.io/py/django-clickify.svg)](https://badge.fury.io/py/django-clickify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A simple Django app to track clicks on any link (e.g., affiliate links, outbound links, file downloads) with rate limiting, IP filtering, and geolocation.
+
+## Features
+
+*   **Click Tracking**: Logs every click on a tracked link, including IP address, user agent, and timestamp.
+*   **Geolocation**: Automatically enriches click logs with the country and city of the request's IP address via a web API.
+*   **Rate Limiting**: Prevents abuse by limiting the number of clicks per IP address in a given timeframe.
+*   **IP Filtering**: Easily configure allowlists and blocklists for IP addresses.
+*   **Secure**: Protects against path traversal attacks.
+*   **Django Admin Integration**: Create and manage your tracked links directly in the Django admin.
+*   **Template Tag & DRF View**: Provides both a simple template tag for traditional Django templates and a DRF API view for headless/JavaScript applications.
+
+## Installation
+
+1.  Install the package from PyPI:
+
+    ```bash
+    pip install django-clickify
+    ```
+
+2.  Add `'clickify'` to your `INSTALLED_APPS` in `settings.py`:
+
+    ```python
+    INSTALLED_APPS = [
+        # ...
+        'clickify',
+    ]
+    ```
+
+3.  Run migrations to create the necessary database models:
+
+    ```bash
+    python manage.py migrate
+    ```
+
+4.  **For API support (Optional)**: If you plan to use the DRF view, you must also install `djangorestframework` and add it to your `INSTALLED_APPS`.
+
+    ```bash
+    pip install django-clickify[drf]
+    ```
+    ```python
+    INSTALLED_APPS = [
+        # ...
+        'rest_framework',
+        'clickify',
+    ]
+    ```
+
+## Configuration
+
+### 1. Middleware (for IP Filtering)
+
+To enable the IP allowlist and blocklist feature, add the `IPFilterMiddleware` to your `settings.py`.
+
+```python
+MIDDLEWARE = [
+    # ...
+    'clickify.middleware.IPFilterMiddleware',
+    # ...
+]
+```
+
+### 2. Settings (Optional)
+
+You can customize the behavior of `django-clickify` by adding the following settings to your `settings.py`:
+
+*   `CLICKIFY_GEOLOCATION`: A boolean to enable or disable geolocation. Defaults to `True`.
+*   `CLICKIFY_RATE_LIMIT`: The rate limit for clicks. Defaults to `'5/m'`.
+*   `CLICKIFY_IP_ALLOWLIST`: A list of IP addresses that are always allowed. Defaults to `[]`.
+*   `CLICKIFY_IP_BLOCKLIST`: A list of IP addresses that are always blocked. Defaults to `[]`.
+
+## Testing
+
+To run the tests for this project, you'll need to have `pytest` and `pytest-django` installed. You can install them with:
+
+```bash
+pip install pytest pytest-django
+```
+
+Then, you can run the tests from the root of the project with:
+
+```bash
+poetry run pytest
+```
+
+This will run all the tests in the `tests/` directory.
+
+## Usage
+
+### Option 1: Template-Based Usage
+
+This is the standard way to use the app in traditional Django projects.
+
+#### Step 1: Create a Tracked Link
+
+In your Django Admin, go to the "Clickify" section and create a new "Tracked Link". This target can be any URL you want to track clicks on.
+
+The `Target Url` can point to any type of file (e.g., PDF, ZIP, MP3, MP4, TXT) or any webpage. The link can be hosted anywhere, such as Amazon S3, a personal blog, or an affiliate partner's site.
+
+*   **Name:** `Monthly Report PDF`
+*   **Slug:** `monthly-report-pdf` (this will be auto-populated from the name)
+*   **Target Url:** `https://your-s3-bucket.s3.amazonaws.com/reports/monthly-summary.pdf`
+
+#### Step 2: Include Clickify URLs
+
+In your project's `urls.py`, include the `clickify` URL patterns.
+
+```python
+# your_project/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... your other urls
+    path('track/', include('clickify.urls', namespace='clickify')),
+]
+```
+
+#### Step 3: Create the Tracked Link
+
+In your Django template, use the `track_url` template tag to generate the tracking link. Use the slug of the `TrackedLink` you created in Step 1.
+
+```html
+<!-- your_app/templates/my_template.html -->
+{% load clickify_tags %}
+
+<a href="{% track_url 'monthly-report-pdf' %}">
+  Download Monthly Summary
+</a>
+```
+
+### Option 2: API Usage (for Headless/JS Frameworks)
+
+If you are using a JavaScript frontend (like React, Vue, etc.) or need a programmatic way to get a tracked URL, you can use the DRF API endpoint.
+
+#### Step 1: Create a Tracked Link
+
+Follow Step 1 from the template-based usage above.
+
+#### Step 2: Include Clickify DRF URLs
+
+In your project's `urls.py`, include the `clickify.drf_urls` patterns.
+
+```python
+# your_project/urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ... your other urls
+    path('api/track/', include('clickify.drf_urls', namespace='clickify-api')),
+]
+```
+
+#### Step 3: Make the API Request
+
+From your frontend, make a `POST` request to the API endpoint using the slug of your `TrackedLink`.
+
+**Endpoint**: `POST /api/track/<slug>/`
+
+A successful request will track the click and return the actual file URL, which you can then use to trigger the click or redirection on the client-side.
+
+**Example using JavaScript `fetch`:**
+
+```javascript
+fetch('/api/track/monthly-report-pdf/', {
+    method: 'POST',
+    headers: {
+        // Include CSRF token if necessary for your setup
+        'X-CSRFToken': 'YourCsrfTokenHere' 
+    }
+})
+.then(response => response.json())
+.then(data => {
+    if (data.target_url) {
+        console.log("Click tracked. Redirecting to:", data.target_url);
+        // Redirect the user to the URL
+        window.location.href = data.target_url;
+    } else {
+        console.error("Failed to track click:", data);
+    }
+})
+.catch(error => {
+    console.error('Error:', error);
+});
+```
+
+**Successful Response (`200 OK`):**
+```json
+{
+    "message": "Click tracked successfully",
+    "target_url": "https://your-s3-bucket.s3.amazonaws.com/reports/monthly-summary.pdf"
+}
+```
+
+**Failure Responses**
+
+If the request fails, you might receive one of the following error responses:
+
+*   **404 Not Found:**
+
+    ```json
+    {
+        "detail": "Not found."
+    }
+    ```
+
+*   **429 Too Many Requests:**
+
+    ```json
+    {
+        "error": "Rate limit exceeded. Please try again later"
+    }
+    ```
+
+*   **403 Forbidden:** (If IP filtering is enabled and the IP is blocked)
+
+    This will typically return a plain text response like:
+    ```
+    IP address blocked.
+    ```
+
+### How It Works
+
+1.  A user clicks a tracked link (`/track/monthly-report-pdf/`) or a `POST` request is sent to the API.
+2.  The view or API view records the click event in the database, associating it with the correct `TrackedLink`.
+3.  The standard view issues a `302 Redirect` to the `target_url`. The API view returns a JSON response containing the `target_url`.
+4.  The user's browser is redirected to the final destination.
+
+This approach is powerful because if you ever need to change the link's destination, you only need to update the `Target Url` in the Django Admin. All your tracked links and API calls will continue to work correctly.
+
+## Contributing
+
+Contributions are welcome! If you'd like to contribute to this project, please follow these steps:
+
+1.  Fork the repository.
+2.  Create a new branch for your feature or bug fix.
+3.  Make your changes and add tests for them.
+4.  Ensure the tests pass by running `poetry run pytest`.
+5.  Create a pull request with a clear description of your changes.

django_clickify-0.1.0/clickify/admin.py

@@ -0,0 +1,24 @@
+from django.contrib import admin
+from .models import TrackedLink, ClickLog
+
+
+@admin.register(TrackedLink)
+class TrackedLinkAdmin(admin.ModelAdmin):
+    list_display = ('name', 'slug', 'target_url', 'created_at')
+    search_fields = ('name', 'slug', 'target_url')
+    prepopulated_fields = {'slug': ('name')}
+    list_filter = ('created_at')
+
+
+@admin.register(ClickLog)
+class ClickLogAdmin(admin.ModelAdmin):
+    list_display = ('target', 'ip_address', 'country', 'city', 'timestamp')
+    search_fields = ('target__name', 'ip_address', 'country', 'city')
+    list_filter = ('target', 'country', 'timestamp')
+    readonly_fields = [field.name for field in ClickLog._meta.fields]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_delete_permission(self, request, obj=...):
+        return False

django_clickify-0.1.0/clickify/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class ClickifyConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'clickify'

django_clickify-0.1.0/clickify/drf_urls.py

@@ -0,0 +1,8 @@
+from django.urls import path
+from .drf_views import TrackClickAPIView
+
+app_name = "clickify-drf"
+
+urlpatterns = [
+    path('<slug:slug>/', TrackClickAPIView.as_view(), name='track_click_api'),
+]

django_clickify-0.1.0/clickify/drf_views.py

@@ -0,0 +1,46 @@
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from rest_framework import status
+from django.shortcuts import get_object_or_404
+from django_ratelimit.decorators import ratelimit
+from django.utils.decorators import method_decorator
+from django.conf import settings
+from .models import TrackedLink
+from .views import track_click
+from .utils import create_click_log
+
+
+@method_decorator(
+    ratelimit(
+        key='ip',
+        rate=lambda r, g: getattr(settings, 'CLICKIFY_RATE_LIMIT', '5/m'),
+        block=True
+    ),
+    name='post'
+)
+class TrackClickAPIView(APIView):
+    """ An API View to track a click for a TrackedLink. """
+
+    def post(self, request, slug, format=None):
+        """ Tracks a click for the given slug. """
+        target = get_object_or_404(TrackedLink, slug=slug)
+
+        # Use the helper function with the underlying Django request
+        create_click_log(target=target, request=request._request)
+
+        return Response(
+            {"message": "Click tracked successfully",
+                "target_url": target.target_url},
+            status=status.HTTP_200_OK
+        )
+
+    def throttled(self, request, wait):
+        """ 
+        Custom handler for when a request is rate-limited 
+        Note: This is for DRF's own throttling, not django-ratelimit.
+        """
+
+        return Response(
+            {"error": "Rate limit exceeded. Please try again later"},
+            status=status.HTTP_429_TOO_MANY_REQUESTS
+        )

django_clickify-0.1.0/clickify/middleware.py

@@ -0,0 +1,22 @@
+from django.conf import settings
+from django.core.exceptions import PermissionDenied
+from ipware import get_client_ip
+
+
+class IPFilterMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        ip_allowlist = getattr(settings, 'CLICKIFY_IP_ALLOWLIST', [])
+        ip_blocklist = getattr(settings, 'CLICKIFY_IP_BLOCKLIST', [])
+        client_ip, _ = get_client_ip(request)
+
+        if ip_allowlist and client_ip not in ip_allowlist:
+            raise PermissionDenied("IP address not allowed.")
+
+        if client_ip in ip_blocklist:
+            raise PermissionDenied("IP address blocked.")
+
+        response = self.get_response(request)
+        return response

django_clickify-0.1.0/clickify/migrations/0001_initial.py

@@ -0,0 +1,80 @@
+# Generated by Django 4.2.23 on 2025-08-28 09:03
+
+from django.db import migrations, models
+import django.db.models.deletion
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="TrackedLink",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                (
+                    "name",
+                    models.CharField(
+                        help_text="A user-friendly name for tracked link, e.g., Monthly Report PDF",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "slug",
+                    models.SlugField(
+                        help_text="A unique slug for the URL. E.g., 'monthly-report-pdf' ",
+                        max_length=255,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "target_url",
+                    models.URLField(
+                        help_text="The actual URL to the destination (e.g., on S3, a blog post, an affiliate link, etc.)",
+                        max_length=2048,
+                    ),
+                ),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+        ),
+        migrations.CreateModel(
+            name="ClickLog",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("ip_address", models.GenericIPAddressField()),
+                ("user_agent", models.TextField()),
+                ("timestamp", models.DateTimeField(auto_now_add=True)),
+                ("country", models.CharField(blank=True, max_length=100, null=True)),
+                ("city", models.CharField(blank=True, max_length=100, null=True)),
+                (
+                    "target",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="clicks",
+                        to="clickify.trackedlink",
+                    ),
+                ),
+            ],
+        ),
+    ]

django_clickify-0.1.0/clickify/models.py

@@ -0,0 +1,46 @@
+from django.db import models
+import uuid
+
+
+class TrackedLink(models.Model):
+    """
+    Represents a link that can be tracked.
+    This model decouples the link from its actual URL,
+      allowing the URL to change without losing the click history.
+    """
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=255,
+                            help_text="A user-friendly name for tracked link, e.g., Monthly Report PDF"
+                            )
+    slug = models.SlugField(
+        max_length=255,
+        unique=True,
+        help_text="A unique slug for the URL. E.g., 'monthly-report-pdf' "
+    )
+    target_url = models.URLField(
+        max_length=2048,
+        help_text="The actual URL to the destination (e.g., on S3, a blog post, an affiliate link, etc.)")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        return self.name
+
+
+class ClickLog(models.Model):
+    """
+    Logs a single click event for a TrackedLink.
+    """
+    target = models.ForeignKey(
+        TrackedLink,
+        on_delete=models.CASCADE,
+        related_name='clicks'
+    )
+    ip_address = models.GenericIPAddressField()
+    user_agent = models.TextField()
+    timestamp = models.DateTimeField(auto_now_add=True)
+    country = models.CharField(max_length=100, blank=True, null=True)
+    city = models.CharField(max_length=100, blank=True, null=True)
+
+    def __str__(self):
+        return f"Click on {self.target.name} at {self.timestamp}"

django_clickify-0.1.0/clickify/templatetags/clickify_tags.py

@@ -0,0 +1,14 @@
+from django import template
+from django.urls import reverse
+
+register = template.Library()
+
+
+@register.simple_tag
+def track_url(slug):
+    """
+    A template tag that returns the tracked URL for a TrackedLink slug.
+    Usage: {% track_url 'my-link-slug' %}
+    """
+
+    return reverse('clickify:track_click', kwargs={'slug': slug})

django_clickify-0.1.0/clickify/urls.py

@@ -0,0 +1,8 @@
+from django.urls import path
+from .views import track_click
+
+app_name = 'clickify'
+
+urlpatterns = [
+    path('<slug:slug>', track_click, name='track_click'),
+]

django_clickify-0.1.0/clickify/utils.py

@@ -0,0 +1,55 @@
+import requests
+from django.conf import settings
+from .models import ClickLog
+from ipware import get_client_ip
+
+
+def get_geolocation(ip_address):
+    """
+    Get the geolocation for a given IP address using the ip-api.com service.
+    This function should only be called for public, routable IP addresses.
+    """
+
+    # Geolocation can be disabled globally in settings
+    if not getattr(settings, 'CLICKIFY_GEOLOCATION', True):
+        return None, None
+
+    if not ip_address:
+        return None, None
+
+    try:
+        # The API endpoint. We request only the fields we need
+        url = f"http://ip-api.com/json/{ip_address}?fields=status,country,city"
+        response = requests.get(url, timeout=2)
+        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
+        data = response.json()
+
+        if data.get('status') == 'success':
+            return data.get('country'), data.get('city')
+        else:
+            return None, None
+    except (requests.RequestException, ValueError):
+        # Catch network errors, timeouts, or JSON decoding errors
+        return None, None
+
+
+def create_click_log(target, request):
+    """
+    Helper function to create a ClickLog object.
+   This contains the core tracking logic that can be reused by both the standard view and the DRF API view.
+    """
+
+    ip, is_routable = get_client_ip(request)
+    user_agent = request.META.get("HTTP_USER_AGENT", "")
+
+    country, city = (None, None)
+    if is_routable:
+        country, city = get_geolocation(ip)
+
+    ClickLog.objects.create(
+        target=target,
+        ip_address=ip,
+        user_agent=user_agent,
+        country=country,
+        city=city
+    )

django_clickify-0.1.0/clickify/views.py

@@ -0,0 +1,22 @@
+from django.http import HttpResponseRedirect, HttpResponseForbidden
+from django.shortcuts import get_object_or_404
+from django.conf import settings
+from django_ratelimit.exceptions import Ratelimited
+from django_ratelimit.decorators import ratelimit
+from .models import TrackedLink
+from .utils import create_click_log
+
+
+@ratelimit(key='ip', rate=lambda r, g: getattr(settings, 'CLICKIFY_RATE_LIMIT', '5/m'), block=True)
+def track_click(request, slug):
+    """
+    Tracks a click for a TrackedLink and then redirects to its actual URL.
+    """
+
+    try:
+        target = get_object_or_404(TrackedLink, slug=slug)
+        # Call the helper function to do the actual tracking
+        create_click_log(target=target, request=request)
+        return HttpResponseRedirect(target.target_url)
+    except Ratelimited:
+        return HttpResponseForbidden("Rate limit exceeded. Please try again later.")

django_clickify-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[tool.poetry]
+name = "django-clickify"
+version = "0.1.0"
+description = "A Django app to track file downloads with rate limiting, IP filtering, and geolocation."
+authors = ["Romjan Ali <romjanvr5@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/romjanxr/django-clickify"
+repository = "https://github.com/romjanxr/django-clickify"
+keywords = ["django", "click", "tracker", "ratelimit", "ipfilter", "geolocation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 4.2",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+packages = [
+  { include = "clickify" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+django = ">=4.2"
+django-ipware = ">=4.0" # Using a more flexible specifier
+django-ratelimit = ">=4.1" # Using a more flexible specifier
+requests = ">=2.20" # Added for the new geolocation API
+
+[tool.poetry.extras]
+drf = ["djangorestframework"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+pytest-django = ">=4.5"
+black = {version = "^24.0", extras = ["d"]}
+isort = ">=5.10"
+djangorestframework = "^3.16.1"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = "tests.py test_*.py *_tests.py"
+filterwarnings = [
+  "ignore::DeprecationWarning:django.core.cache.backends.filebased",
+]