unitpulse-channels 0.1.0

Canonical communication-channel enum and lead-source registry

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

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.