Metadata-Version: 2.4
Name: pycrmkit
Version: 1.2.0
Summary: Headless CRM building blocks for Python applications.
Author: Thomas Awounfouet
License-Expression: MIT
Project-URL: Homepage, https://github.com/tawounfouet/pycrmkit
Project-URL: Repository, https://github.com/tawounfouet/pycrmkit
Project-URL: Issues, https://github.com/tawounfouet/pycrmkit/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: sqlalchemy
Requires-Dist: SQLAlchemy<2.2,>=2.0; extra == "sqlalchemy"
Provides-Extra: postgresql
Requires-Dist: SQLAlchemy<2.2,>=2.0; extra == "postgresql"
Requires-Dist: psycopg[binary]<3.4,>=3.2; extra == "postgresql"
Provides-Extra: migrations
Requires-Dist: SQLAlchemy<2.2,>=2.0; extra == "migrations"
Requires-Dist: alembic<2,>=1.16; extra == "migrations"
Requires-Dist: psycopg[binary]<3.4,>=3.2; extra == "migrations"
Provides-Extra: fastapi
Requires-Dist: fastapi<0.142,>=0.141; extra == "fastapi"
Requires-Dist: pydantic<2.14,>=2.13; extra == "fastapi"
Provides-Extra: django
Requires-Dist: Django<5.3,>=5.2; extra == "django"
Provides-Extra: drf
Requires-Dist: Django<5.3,>=5.2; extra == "drf"
Requires-Dist: djangorestframework<3.19,>=3.18; extra == "drf"
Provides-Extra: email
Requires-Dist: Jinja2<3.2,>=3.1; extra == "email"
Provides-Extra: resend
Requires-Dist: resend<3,>=2.47; extra == "resend"
Provides-Extra: dev
Requires-Dist: SQLAlchemy<2.2,>=2.0; extra == "dev"
Requires-Dist: alembic<2,>=1.16; extra == "dev"
Requires-Dist: psycopg[binary]<3.4,>=3.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=6; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pre-commit>=4; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: mkdocs<2,>=1.6; extra == "dev"
Requires-Dist: Jinja2<3.2,>=3.1; extra == "dev"
Requires-Dist: resend<3,>=2.47; extra == "dev"
Requires-Dist: fastapi<0.142,>=0.141; extra == "dev"
Requires-Dist: pydantic<2.14,>=2.13; extra == "dev"
Requires-Dist: httpx<1,>=0.28; extra == "dev"
Requires-Dist: Django<5.3,>=5.2; extra == "dev"
Requires-Dist: djangorestframework<3.19,>=3.18; extra == "dev"
Requires-Dist: django-stubs<7,>=6.0; extra == "dev"
Requires-Dist: djangorestframework-stubs<4,>=3.18; extra == "dev"
Dynamic: license-file

# PyCRMKit

**Headless, framework-agnostic CRM building blocks for Python applications.**

Build customer relationship workflows without running a full CRM server. PyCRMKit provides a typed domain model, a Python facade, events and pluggable persistence; your application controls its API, identity and deployment.

## Features

- **CRM:** contacts, organizations, relationships, tags and custom fields.
- **Sales & activities:** leads, opportunities, pipelines, tasks and customer timelines.
- **Segmentation & campaigns:** saved queries, segment membership, Campaign metadata, audiences and attribution references.
- **Automation:** domain events, audit history, webhooks and provider-neutral email workflows.
- **Data operations:** CSV/JSON/JSONL import and export, external identities, duplicate review and contact merge.
- **Integrations:** in-memory storage, SQLAlchemy/PostgreSQL, FastAPI, Django and Django REST Framework.

## Installation

Requires **Python 3.11–3.13**. For a version available on [PyPI](https://pypi.org/project/pycrmkit/):

```bash
python -m pip install pycrmkit
```

For the latest source checkout (including versions not yet published):

```bash
git clone https://github.com/tawounfouet/pycrmkit.git
cd pycrmkit
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

## Quickstart

```python
from pycrmkit import CRM
from pycrmkit.core.references import EntityReference

crm = CRM.memory()
contact = crm.contacts.create(first_name="Ada", last_name="Lovelace")
contact_ref = EntityReference("contact", contact.id)

task = crm.tasks.create(title="Prepare follow-up", references=(contact_ref,))
crm.tasks.complete(task.id)

for entry in crm.timeline.for_contact(contact.id).items:
    print(entry.title)
```

`CRM.memory()` requires no database or web framework. Add an adapter for durable storage or HTTP endpoints.

## Architecture

```text
Application → CRM facade → Domain services & events → Repository contracts → Adapters
```

The core has **no mandatory third-party runtime dependencies**. SQLAlchemy, PostgreSQL, FastAPI, Django/DRF and email integrations are opt-in.

**Scope:** Campaigns manage metadata, audiences and references; they do not send marketing messages. Host applications must enforce authentication, tenant authorization and database migration ownership.

## Documentation

- [Quickstart](https://github.com/tawounfouet/pycrmkit/blob/main/docs/getting-started/quickstart.md) · [Guides](https://github.com/tawounfouet/pycrmkit/blob/main/docs/guides/index.md)
- [Campaigns](https://github.com/tawounfouet/pycrmkit/blob/main/docs/campaigns/index.md) · [Compatibility](https://github.com/tawounfouet/pycrmkit/blob/main/docs/reference/1.2.0-support-and-compatibility.md)
- [Releases](https://github.com/tawounfouet/pycrmkit/releases) · [Changelog](https://github.com/tawounfouet/pycrmkit/blob/main/CHANGELOG.md) · [Contributing](https://github.com/tawounfouet/pycrmkit/blob/main/CONTRIBUTING.md)

**Release availability:** Check the GitHub Releases page and PyPI independently. A version present in source control is not necessarily published on either platform.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
```

## License

[MIT](https://github.com/tawounfouet/pycrmkit/blob/main/LICENSE) © 2026 Thomas Awounfouet.
