Metadata-Version: 2.4
Name: unitpulse-channels
Version: 0.2.0
Summary: Canonical communication-channel enum and lead-source registry
Author: UnitPulse
Author-email: honglu.he@unitpulse.ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# unitpulse-channels

Single source of truth for UnitPulse's communication-channel and lead-source
vocabulary. Import it everywhere a `channel` or `lead_source` value is produced
so services stop re-declaring (and drifting) their own lists.

## Concepts

Three distinct things that were historically conflated into one free-form field:

| concept | field | governance |
|---|---|---|
| **channel** | per-message medium | CLOSED enum (`Channel`) |
| **first_touch_channel** | mode of first contact (prospect) | same `Channel` enum |
| **lead_source** | acquisition / attribution | OPEN curated registry (`LEAD_SOURCES`) |

`channel` is closed: unknown input → `other` (+ WARN log). `lead_source` is an
open curated registry: unknown input → `other` but the original raw string is
preserved so new sources can be promoted by review.

## Usage

```python
from unitpulse_channels import (
    normalize_channel, normalize_lead_source, classify_prospect_source,
)

normalize_channel("FB Messenger")        # -> "fb messenger"
normalize_channel("call in")             # -> "phone"
normalize_channel("walk in")             # -> "in_person"

normalize_lead_source("ZILLOW").value    # -> "zillow"
normalize_lead_source("1133 Hope")       # -> LeadSource(value="other", raw="1133 Hope")

# Split a raw prospect "source" into both dimensions:
classify_prospect_source("Walk in")            # -> ("direct", "in_person")
classify_prospect_source("Zillow")             # -> ("zillow", None)  # derive channel from 1st activity
classify_prospect_source("Facebook Messenger") # -> ("facebook", "fb messenger")
```

Design + backfill: `design-docs` → `unitpulse/specs/2026-06-18-channel-enum-cleanup.md`.
