Metadata-Version: 2.5
Name: entirius-django-contact-forms
Version: 4.0.0
Summary: Contact forms module for Entirius: channel-scoped submissions, bookings, leads and Google Ads conversion uploads
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-contact-forms/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-contact-forms
Project-URL: Changelog, https://github.com/entirius/entirius-django-contact-forms/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-contact-forms/issues
Author: Entirius
Maintainer-email: Piotr Brzozowski <piotrb@entirius.com>, Paweł Kiełt <cptshooter12@gmail.com>, Mateusz Baran <mateuszbaranpv@gmail.com>, Michał Kloczkowski <michal@kloczkowski.pl>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: bookings,contact-forms,django,ecommerce,entirius,google-ads,leads
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.11
Requires-Dist: amqp>=5.0
Requires-Dist: celery>=5.0
Requires-Dist: cryptography>=44.0
Requires-Dist: django>=4.0.0
Requires-Dist: djangorestframework-simplejwt>=5.3
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Requires-Dist: entirius-django-regional>=2.0.1
Requires-Dist: entirius-django-utils>=2.0.0
Requires-Dist: entirius-py-idx-normalizator>=2.0.0
Requires-Dist: entirius-py-process-logger>=2.0.0
Requires-Dist: marshmallow-dataclass>=8.5.3
Requires-Dist: marshmallow<4,>=3.15
Requires-Dist: pydantic[email]>=2.0
Provides-Extra: bookings
Requires-Dist: entirius-py-google-calendar-sdk>=2.0.0; extra == 'bookings'
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: email
Requires-Dist: entirius-django-email>=4.0.1; extra == 'email'
Provides-Extra: google-ads
Requires-Dist: entirius-py-google-ads-sdk>=2.0.0; extra == 'google-ads'
Provides-Extra: test
Requires-Dist: dj-database-url; extra == 'test'
Requires-Dist: factory-boy; extra == 'test'
Requires-Dist: psycopg[binary]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Description-Content-Type: text/markdown

# entirius-django-contact-forms

A Django module for contact forms in Entirius, the open-source modular ecommerce platform. It accepts form
submissions with attachments per sales channel, sends notification emails, takes calendar bookings, and turns
submissions into leads that can be reported to Google Ads as offline conversions.

[![PyPI](https://img.shields.io/pypi/v/entirius-django-contact-forms.svg)](https://pypi.org/project/entirius-django-contact-forms/)
[![Python](https://img.shields.io/pypi/pyversions/entirius-django-contact-forms.svg)](https://pypi.org/project/entirius-django-contact-forms/)
[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/entirius/entirius-django-contact-forms/blob/develop/LICENSE)

## What it does

- Accepts form submissions with file attachments, scoped per sales channel and typed from a per-channel catalog.
- Sends a notification to the shop and an optional copy to the submitter, configured per form type.
- Offers a booking calendar with free slots, backed by Google Calendar or a local-only backend.
- Creates leads from submissions and bookings and tracks them through a status pipeline.
- Uploads lead conversions to Google Ads.
- Exposes an admin API for the CMS and a key-protected, throttled public API for the storefront.

## Installation

```shell
uv add entirius-django-contact-forms
pip install entirius-django-contact-forms
```

```python
INSTALLED_APPS = [
    ...
    "django_regional",
    "django_utils",
    "django_contact_forms",
]

PRIVATE_DIR = "/private"  # required: root of the private file storage (attachments)

# urls.py
urlpatterns = [
    path("", include("django_contact_forms.urls")),
]
```

`PRIVATE_DIR` is the only required setting. Reference with defaults:
https://github.com/entirius/entirius-django-contact-forms/blob/develop/docs/configuration.md

Extras: `bookings` (Google Calendar backend for bookings), `google-ads` (conversion uploads), `email` (branded
notification emails through `entirius-django-email`).

```shell
uv add "entirius-django-contact-forms[bookings,google-ads,email]"
```

The public API takes a key in the `X-API-KEY` header. Where `django_access` is installed the key is an access token
with the scope `contact_forms.submit` (bookings: `contact_forms.booking`):

```shell
python manage.py access_token create --application storefront --create-application --scope contact_forms.submit --channel default
```

Without `django_access`, `python manage.py forms-generate-api-key` creates the key.

## Quick start

```python
from django_contact_forms.services.contact_form_service import create_submission, get_channel

channel = get_channel(idx="default")
form = create_submission(email="customer@example.com", channel=channel, body={"message": "Hello"})
```

## Requirements

- Python 3.11 or newer, Django 4.0 or newer.
- PostgreSQL, and Celery for email dispatch and conversion uploads.
- Entirius packages pulled in: `entirius-django-regional`, `entirius-django-utils`, `entirius-py-idx-normalizator`,
  `entirius-py-process-logger`.
- Optional, through the extras: `entirius-py-google-calendar-sdk`, `entirius-py-google-ads-sdk`,
  `entirius-django-email`.

## Documentation

- Module docs: https://github.com/entirius/entirius-django-contact-forms/tree/develop/docs
- Entirius documentation: https://docs.entirius.com/
- Changelog: https://github.com/entirius/entirius-django-contact-forms/blob/develop/CHANGELOG.md

## Part of Entirius

This module runs inside the Entirius backend service (Volkanos) and serves the forms of the storefront.

- Backend service: https://github.com/entirius/entirius-service-volkanos
- Docker harness: https://github.com/entirius/entirius-zeno
- Sibling modules: https://github.com/entirius/entirius-django-email, https://github.com/entirius/entirius-django-regional,
  https://github.com/entirius/entirius-django-access

## Development

```shell
make install     # sync dependencies (uv)
make check       # lint + format check (ruff)
make test        # test suite (pytest, needs PostgreSQL via DATABASE_URL)
```

Development and agent instructions: https://github.com/entirius/entirius-django-contact-forms/blob/develop/AGENTS.md

## License

Mozilla Public License 2.0 (MPL-2.0) — see https://github.com/entirius/entirius-django-contact-forms/blob/develop/LICENSE.
