contackd-sync 0.2.0__tar.gz → 0.3.0__tar.gz

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contackd-sync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Contackd Sync
 Project-URL: Homepage, https://example.com/contackd-sync
 Requires-Python: >=3.10
@@ -10,7 +10,7 @@ Requires-Dist: urllib3>=2.0.0
 
 # contackd-sync (Python)
 
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`).
+Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
 
 ## Install
 
@@ -80,6 +80,52 @@ print(len(result.created), len(result.updated), result.errors)
 page = client.contacts.list(page=1, per_page=50, email="jane@acme.com")
 ```
 
+## Sync Businesses Before Their Contacts
+
+Create or update businesses first so contacts can reference the returned CRM
+business IDs. Business synchronization uses `external_business_id` as its
+primary natural key and falls back to the normalized business name.
+
+```python
+from contackd_sync import Business, Contact, ContackdClient
+
+client = ContackdClient(
+    api_key="sk_live_...",
+    base_url="https://api.yourapp.com/api/v1",
+)
+
+business_result = client.businesses.bulk_upsert(
+    [
+        Business(
+            name="Default Facility",
+            external_business_id="bb7d2b66-034a-4333-8573-dce07b9684ed",
+            stage="customer",
+            status="active",
+            tags=["FACILITY"],
+            custom={"org_code": "FACILITYBILLS"},
+        )
+    ]
+)
+business = [*business_result.created, *business_result.updated][0]
+
+contact_result = client.contacts.bulk_upsert(
+    [
+        Contact(
+            email="resident@example.com",
+            first_name="Resident",
+            external_contact_id="resident-1",
+            business_id=business.id,
+            tags=["RESIDENT"],
+            custom={"role": "resident"},
+        )
+    ]
+)
+```
+
+Callers should merge duplicate source rows before sending them. For a person
+belonging to multiple estates, keep the complete estate list in `custom` and
+use `business_id` for the single primary CRM relationship.
+
 ## API Key Setup
 
 Contact support@dalmlabs.com for the API key and base domain.
@@ -94,12 +140,12 @@ Given `base_url = https://api.yourapp.com/api/v1`:
 - `GET /tags/{id}`
 - `PUT /tags/{id}`
 - `DELETE /tags/{id}`
-- `POST /contacts|leads|prospects`
-- `GET /contacts|leads|prospects/{id}`
-- `PUT /contacts|leads|prospects/{id}`
-- `DELETE /contacts|leads|prospects/{id}`
-- `GET /contacts|leads|prospects`
-- `POST /contacts|leads|prospects/upsert`
-- `POST /contacts|leads|prospects/bulk`
-- `POST /contacts|leads|prospects/bulk/upsert`
-- `POST /contacts|leads|prospects/bulk/delete`
+- `POST /contacts|leads|prospects|businesses`
+- `GET /contacts|leads|prospects|businesses/{id}`
+- `PUT /contacts|leads|prospects|businesses/{id}`
+- `DELETE /contacts|leads|prospects|businesses/{id}`
+- `GET /contacts|leads|prospects|businesses`
+- `POST /contacts|leads|prospects|businesses/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk`
+- `POST /contacts|leads|prospects|businesses/bulk/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk/delete`

contackd_sync-0.3.0/README.md

@@ -0,0 +1,141 @@
+# contackd-sync (Python)
+
+Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
+
+## Install
+
+```bash
+pip install contackd-sync
+```
+
+## 2-Minute Start (Push Customer Details)
+
+```python
+from contackd_sync import ContackdClient, Contact
+
+client = ContackdClient(
+    api_key="sk_live_...",
+    base_url="https://api.yourapp.com/api/v1",  # no trailing slash required
+)
+
+# Create/update a customer contact by email
+customer = client.contacts.upsert(
+    Contact(
+        email="jane@acme.com",
+        first_name="Jane",
+        last_name="Doe",
+        phone="+14155550199",
+        tags=["customer", "vip"],
+        custom={
+            "customer_id": "CUST-1001",
+            "plan": "pro",
+            "country": "US",
+        },
+    )
+)
+
+print(customer)
+```
+
+## Common Customer Push Patterns
+
+### 1) Push one new customer
+
+```python
+from contackd_sync import Contact
+
+created = client.contacts.create(
+    Contact(email="new@acme.com", first_name="New", last_name="Customer")
+)
+```
+
+### 2) Push many customers (bulk upsert)
+
+```python
+from contackd_sync import Contact
+
+result = client.contacts.bulk_upsert(
+    [
+        Contact(email="a@acme.com", first_name="A"),
+        Contact(email="b@acme.com", first_name="B", tags=["trial"]),
+    ]
+)
+
+print(len(result.created), len(result.updated), result.errors)
+```
+
+### 3) Read/filter customers
+
+```python
+page = client.contacts.list(page=1, per_page=50, email="jane@acme.com")
+```
+
+## Sync Businesses Before Their Contacts
+
+Create or update businesses first so contacts can reference the returned CRM
+business IDs. Business synchronization uses `external_business_id` as its
+primary natural key and falls back to the normalized business name.
+
+```python
+from contackd_sync import Business, Contact, ContackdClient
+
+client = ContackdClient(
+    api_key="sk_live_...",
+    base_url="https://api.yourapp.com/api/v1",
+)
+
+business_result = client.businesses.bulk_upsert(
+    [
+        Business(
+            name="Default Facility",
+            external_business_id="bb7d2b66-034a-4333-8573-dce07b9684ed",
+            stage="customer",
+            status="active",
+            tags=["FACILITY"],
+            custom={"org_code": "FACILITYBILLS"},
+        )
+    ]
+)
+business = [*business_result.created, *business_result.updated][0]
+
+contact_result = client.contacts.bulk_upsert(
+    [
+        Contact(
+            email="resident@example.com",
+            first_name="Resident",
+            external_contact_id="resident-1",
+            business_id=business.id,
+            tags=["RESIDENT"],
+            custom={"role": "resident"},
+        )
+    ]
+)
+```
+
+Callers should merge duplicate source rows before sending them. For a person
+belonging to multiple estates, keep the complete estate list in `custom` and
+use `business_id` for the single primary CRM relationship.
+
+## API Key Setup
+
+Contact support@dalmlabs.com for the API key and base domain.
+
+## Backend Routes Expected by SDK
+
+Given `base_url = https://api.yourapp.com/api/v1`:
+
+- `GET /health`
+- `POST /tags`
+- `GET /tags`
+- `GET /tags/{id}`
+- `PUT /tags/{id}`
+- `DELETE /tags/{id}`
+- `POST /contacts|leads|prospects|businesses`
+- `GET /contacts|leads|prospects|businesses/{id}`
+- `PUT /contacts|leads|prospects|businesses/{id}`
+- `DELETE /contacts|leads|prospects|businesses/{id}`
+- `GET /contacts|leads|prospects|businesses`
+- `POST /contacts|leads|prospects|businesses/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk`
+- `POST /contacts|leads|prospects|businesses/bulk/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk/delete`

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/contackd_sync/__init__.py

@@ -3,6 +3,8 @@
 from ._version import __version__
 from .client import (
     AuthError,
+    Business,
+    BusinessesResource,
     BulkResult,
     ConflictStrategy,
     Contact,
@@ -26,6 +28,8 @@ from .client import (
 __all__ = [
     "__version__",
     "AuthError",
+    "Business",
+    "BusinessesResource",
     "BulkResult",
     "ConflictStrategy",
     "Contact",

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/contackd_sync/client.py

@@ -74,6 +74,8 @@ class Contact:
     first_name: str = ""
     last_name: str = ""
     phone: Optional[str] = None
+    external_contact_id: Optional[str] = None
+    business_id: Optional[str] = None
     tags: List[str] = field(default_factory=list)
     custom: Dict[str, Any] = field(default_factory=dict)
     id: Optional[str] = None
@@ -180,9 +182,49 @@ class Prospect:
         return hashlib.sha256(payload.encode()).hexdigest()
 
 
-RecordType = Contact | Lead | Prospect
+@dataclass
+class Business:
+    """Business record model used by the Businesses API."""
+
+    name: str
+    external_business_id: Optional[str] = None
+    email: Optional[str] = None
+    phone: Optional[str] = None
+    website: Optional[str] = None
+    industry: Optional[str] = None
+    address: Optional[str] = None
+    notes: Optional[str] = None
+    primary_contact_id: Optional[str] = None
+    stage: str = "lead"
+    status: str = "active"
+    estimated_value: Optional[int] = None
+    tags: List[str] = field(default_factory=list)
+    custom: Dict[str, Any] = field(default_factory=dict)
+    id: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Serialize the record to a JSON-friendly dictionary."""
+        data = asdict(self)
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Business":
+        """Build a business from API response data."""
+        return cls(**{key: value for key, value in data.items() if key in cls.__dataclass_fields__})
+
+    def fingerprint(self) -> str:
+        """Return a stable SHA-256 digest for change detection."""
+        payload = json.dumps(
+            {key: value for key, value in self.to_dict().items() if key not in ("id", "updated_at")},
+            sort_keys=True,
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+
+RecordType = Contact | Lead | Prospect | Business
 ConflictStrategy = Literal["local", "remote", "raise"]
-RecordT = TypeVar("RecordT", Contact, Lead, Prospect)
+RecordT = TypeVar("RecordT", Contact, Lead, Prospect, Business)
 
 
 class _RecordModel(Protocol):
@@ -199,8 +241,31 @@ class _RecordFactory(Protocol[RecordT]):
     def from_dict(cls, data: dict) -> RecordT: ...
 
 
+def _record_keys(record: _RecordModel) -> List[str]:
+    keys: List[str] = []
+    if hasattr(record, "external_business_id"):
+        external_business_id = getattr(record, "external_business_id", None)
+        if external_business_id:
+            keys.append(
+                f"external_business_id:{str(external_business_id).strip().casefold()}"
+            )
+        name = getattr(record, "name", None)
+        if name:
+            keys.append(f"name:{str(name).strip().casefold()}")
+    else:
+        if record.email:
+            keys.append(f"email:{record.email.strip().casefold()}")
+        external_thread_id = getattr(record, "external_thread_id", None)
+        if external_thread_id:
+            keys.append(f"external_thread_id:{str(external_thread_id).strip()}")
+        if record.id:
+            keys.append(f"id:{record.id}")
+    return keys
+
+
 def _record_key(record: _RecordModel) -> Optional[str]:
-    return record.email or getattr(record, "external_thread_id", None) or record.id
+    keys = _record_keys(record)
+    return keys[0] if keys else None
 
 
 class _HttpClient:
@@ -365,6 +430,13 @@ class ProspectsResource(_Resource[Prospect]):
     _model = Prospect
 
 
+class BusinessesResource(_Resource[Business]):
+    """Typed resource wrapper for businesses."""
+
+    _path = "businesses"
+    _model = Business
+
+
 @dataclass
 class SyncResult:
     """Outcome summary for a bidirectional sync operation."""
@@ -419,19 +491,23 @@ class SyncEngine(Generic[RecordT]):
         """Run a full bidirectional sync against the remote API."""
         result = SyncResult()
         remote_records = self.pull(**filters)
-        remote_by_key: Dict[str, RecordT] = {
-            key: record
-            for record in remote_records
-            if (key := _record_key(record)) is not None
-        }
+        remote_by_key: Dict[str, RecordT] = {}
+        for record in remote_records:
+            for key in _record_keys(record):
+                remote_by_key.setdefault(key, record)
         local_keys = {
-            key for record in local_records if (key := _record_key(record)) is not None
+            key
+            for record in local_records
+            for key in _record_keys(record)
         }
 
         to_push: List[RecordT] = []
 
         for local in local_records:
-            remote = remote_by_key.get(_record_key(local))
+            remote = next(
+                (remote_by_key[key] for key in _record_keys(local) if key in remote_by_key),
+                None,
+            )
 
             if remote is None:
                 to_push.append(local)
@@ -453,7 +529,9 @@ class SyncEngine(Generic[RecordT]):
             result.errors.extend(bulk.errors)
 
         result.remote_only = [
-            record for record in remote_records if _record_key(record) not in local_keys
+            record
+            for record in remote_records
+            if not local_keys.intersection(_record_keys(record))
         ]
         return result
 
@@ -487,6 +565,7 @@ class ContackdClient:
         self.contacts = ContactsResource(self._http)
         self.leads = LeadsResource(self._http)
         self.prospects = ProspectsResource(self._http)
+        self.businesses = BusinessesResource(self._http)
 
     def sync_contacts(
         self,
@@ -533,6 +612,21 @@ class ContackdClient:
         )
         return engine.sync(local_records, **filters)
 
+    def sync_businesses(
+        self,
+        local_records: List[Business],
+        conflict_strategy: Optional[ConflictStrategy] = None,
+        on_conflict: Optional[Callable[[SyncConflictError], Business]] = None,
+        **filters: Any,
+    ) -> SyncResult:
+        """Synchronize businesses between local state and the remote API."""
+        engine = SyncEngine(
+            self.businesses,
+            conflict_strategy=conflict_strategy or self.conflict_strategy,
+            on_conflict=on_conflict,
+        )
+        return engine.sync(local_records, **filters)
+
     def ping(self) -> bool:
         """Return ``True`` when the health endpoint responds successfully."""
         try:
@@ -544,6 +638,8 @@ class ContackdClient:
 
 __all__ = [
     "AuthError",
+    "Business",
+    "BusinessesResource",
     "BulkResult",
     "ConflictStrategy",
     "Contact",

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/contackd_sync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contackd-sync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Contackd Sync
 Project-URL: Homepage, https://example.com/contackd-sync
 Requires-Python: >=3.10
@@ -10,7 +10,7 @@ Requires-Dist: urllib3>=2.0.0
 
 # contackd-sync (Python)
 
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`).
+Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
 
 ## Install
 
@@ -80,6 +80,52 @@ print(len(result.created), len(result.updated), result.errors)
 page = client.contacts.list(page=1, per_page=50, email="jane@acme.com")
 ```
 
+## Sync Businesses Before Their Contacts
+
+Create or update businesses first so contacts can reference the returned CRM
+business IDs. Business synchronization uses `external_business_id` as its
+primary natural key and falls back to the normalized business name.
+
+```python
+from contackd_sync import Business, Contact, ContackdClient
+
+client = ContackdClient(
+    api_key="sk_live_...",
+    base_url="https://api.yourapp.com/api/v1",
+)
+
+business_result = client.businesses.bulk_upsert(
+    [
+        Business(
+            name="Default Facility",
+            external_business_id="bb7d2b66-034a-4333-8573-dce07b9684ed",
+            stage="customer",
+            status="active",
+            tags=["FACILITY"],
+            custom={"org_code": "FACILITYBILLS"},
+        )
+    ]
+)
+business = [*business_result.created, *business_result.updated][0]
+
+contact_result = client.contacts.bulk_upsert(
+    [
+        Contact(
+            email="resident@example.com",
+            first_name="Resident",
+            external_contact_id="resident-1",
+            business_id=business.id,
+            tags=["RESIDENT"],
+            custom={"role": "resident"},
+        )
+    ]
+)
+```
+
+Callers should merge duplicate source rows before sending them. For a person
+belonging to multiple estates, keep the complete estate list in `custom` and
+use `business_id` for the single primary CRM relationship.
+
 ## API Key Setup
 
 Contact support@dalmlabs.com for the API key and base domain.
@@ -94,12 +140,12 @@ Given `base_url = https://api.yourapp.com/api/v1`:
 - `GET /tags/{id}`
 - `PUT /tags/{id}`
 - `DELETE /tags/{id}`
-- `POST /contacts|leads|prospects`
-- `GET /contacts|leads|prospects/{id}`
-- `PUT /contacts|leads|prospects/{id}`
-- `DELETE /contacts|leads|prospects/{id}`
-- `GET /contacts|leads|prospects`
-- `POST /contacts|leads|prospects/upsert`
-- `POST /contacts|leads|prospects/bulk`
-- `POST /contacts|leads|prospects/bulk/upsert`
-- `POST /contacts|leads|prospects/bulk/delete`
+- `POST /contacts|leads|prospects|businesses`
+- `GET /contacts|leads|prospects|businesses/{id}`
+- `PUT /contacts|leads|prospects|businesses/{id}`
+- `DELETE /contacts|leads|prospects|businesses/{id}`
+- `GET /contacts|leads|prospects|businesses`
+- `POST /contacts|leads|prospects|businesses/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk`
+- `POST /contacts|leads|prospects|businesses/bulk/upsert`
+- `POST /contacts|leads|prospects|businesses/bulk/delete`

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/contackd_sync.egg-info/SOURCES.txt

@@ -8,4 +8,5 @@ contackd_sync.egg-info/SOURCES.txt
 contackd_sync.egg-info/dependency_links.txt
 contackd_sync.egg-info/requires.txt
 contackd_sync.egg-info/top_level.txt
+tests/test_business_sync.py
 tests/test_client.py

{contackd_sync-0.2.0 → contackd_sync-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "contackd-sync"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Contackd Sync"
 readme = "README.md"
 requires-python = ">=3.10"

contackd_sync-0.3.0/tests/test_business_sync.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from typing import Any
+
+import contackd_sync
+from contackd_sync import Business, Contact, ContackdClient, SyncEngine
+
+
+class RecordingHttpClient:
+    def __init__(self, responses: list[dict[str, Any]] | None = None) -> None:
+        self.responses = list(responses or [])
+        self.posts: list[tuple[str, dict[str, Any]]] = []
+
+    def post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        self.posts.append((path, body))
+        return self.responses.pop(0) if self.responses else {}
+
+
+class InMemoryBusinessResource:
+    def __init__(self, records: list[Business]) -> None:
+        self.records = records
+        self.pushed: list[Business] = []
+
+    def list(self, page: int = 1, per_page: int = 100, **filters: Any) -> list[Business]:
+        del per_page, filters
+        return self.records if page == 1 else []
+
+    def bulk_upsert(self, records: list[Business], chunk_size: int = 100) -> contackd_sync.BulkResult:
+        del chunk_size
+        self.pushed.extend(records)
+        return contackd_sync.BulkResult(updated=list(records))
+
+
+def test_contact_serializes_source_and_business_ids() -> None:
+    contact = Contact(
+        email="resident@example.com",
+        external_contact_id="resident-1",
+        business_id="business-1",
+    )
+
+    assert contact.to_dict()["external_contact_id"] == "resident-1"
+    assert contact.to_dict()["business_id"] == "business-1"
+
+
+def test_business_serializes_facility_fields() -> None:
+    business = contackd_sync.Business(
+        name="Default Facility",
+        external_business_id="estate-1",
+        stage="customer",
+        status="active",
+        tags=["FACILITY"],
+        custom={"org_code": "FACILITYBILLS"},
+    )
+
+    assert business.to_dict() == {
+        "name": "Default Facility",
+        "external_business_id": "estate-1",
+        "stage": "customer",
+        "status": "active",
+        "tags": ["FACILITY"],
+        "custom": {"org_code": "FACILITYBILLS"},
+    }
+
+
+def test_business_resource_bulk_upserts_in_chunks() -> None:
+    http = RecordingHttpClient(
+        [
+            {"created": [{"id": "business-1", "name": "Estate 1", "external_business_id": "estate-1"}]},
+            {"updated": [{"id": "business-2", "name": "Estate 2", "external_business_id": "estate-2"}]},
+        ]
+    )
+    resource_type = getattr(contackd_sync, "BusinessesResource")
+    resource = resource_type(http)
+    records = [
+        Business(name="Estate 1", external_business_id="estate-1"),
+        Business(name="Estate 2", external_business_id="estate-2"),
+    ]
+
+    result = resource.bulk_upsert(records, chunk_size=1)
+
+    assert [path for path, _ in http.posts] == ["businesses/bulk/upsert", "businesses/bulk/upsert"]
+    assert result.total == 2
+    assert [record.id for record in result.created] == ["business-1"]
+    assert [record.id for record in result.updated] == ["business-2"]
+
+
+def test_business_sync_matches_by_external_business_id() -> None:
+    remote = Business(
+        id="business-1",
+        name="Old Facility Name",
+        external_business_id="estate-1",
+    )
+    other_remote = Business(
+        id="business-2",
+        name="Other Facility",
+        external_business_id="estate-2",
+    )
+    local = Business(
+        name="Renamed Facility",
+        external_business_id="estate-1",
+    )
+    resource = InMemoryBusinessResource([remote, other_remote])
+    engine = SyncEngine(resource, conflict_strategy="local")  # type: ignore[arg-type]
+
+    result = engine.sync([local])
+
+    assert result.pushed == []
+    assert len(result.resolved) == 1
+    assert result.resolved[0][1] is remote
+    assert resource.pushed == [local]
+    assert result.remote_only == [other_remote]
+
+
+def test_business_sync_falls_back_to_name_when_remote_has_no_external_id() -> None:
+    remote = Business(id="business-1", name="Default Facility")
+    local = Business(name=" default facility ", external_business_id="estate-1")
+    resource = InMemoryBusinessResource([remote])
+    engine = SyncEngine(resource, conflict_strategy="local")  # type: ignore[arg-type]
+
+    result = engine.sync([local])
+
+    assert result.pushed == []
+    assert len(result.resolved) == 1
+    assert result.resolved[0][1] is remote
+    assert result.remote_only == []
+
+
+def test_client_exposes_business_resource() -> None:
+    client = ContackdClient(api_key="test-key", base_url="https://api.example.com/api/v1")
+
+    resource_type = getattr(contackd_sync, "BusinessesResource")
+    assert isinstance(client.businesses, resource_type)
+
+
+def test_client_syncs_businesses_with_requested_conflict_strategy() -> None:
+    remote = Business(id="business-1", name="Old Name", external_business_id="estate-1")
+    local = Business(name="New Name", external_business_id="estate-1")
+    resource = InMemoryBusinessResource([remote])
+    client = ContackdClient(api_key="test-key", base_url="https://api.example.com/api/v1")
+    client.businesses = resource  # type: ignore[assignment]
+
+    result = client.sync_businesses([local], conflict_strategy="local")
+
+    assert resource.pushed == [local]
+    assert len(result.resolved) == 1
+
+
+def test_client_reports_the_installed_sdk_version() -> None:
+    client = ContackdClient(api_key="test-key", base_url="https://api.example.com/api/v1")
+
+    assert client._http.session.headers["X-SDK-Version"] == contackd_sync.__version__

contackd_sync-0.2.0/README.md

@@ -1,95 +0,0 @@
-# contackd-sync (Python)
-
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`).
-
-## Install
-
-```bash
-pip install contackd-sync
-```
-
-## 2-Minute Start (Push Customer Details)
-
-```python
-from contackd_sync import ContackdClient, Contact
-
-client = ContackdClient(
-    api_key="sk_live_...",
-    base_url="https://api.yourapp.com/api/v1",  # no trailing slash required
-)
-
-# Create/update a customer contact by email
-customer = client.contacts.upsert(
-    Contact(
-        email="jane@acme.com",
-        first_name="Jane",
-        last_name="Doe",
-        phone="+14155550199",
-        tags=["customer", "vip"],
-        custom={
-            "customer_id": "CUST-1001",
-            "plan": "pro",
-            "country": "US",
-        },
-    )
-)
-
-print(customer)
-```
-
-## Common Customer Push Patterns
-
-### 1) Push one new customer
-
-```python
-from contackd_sync import Contact
-
-created = client.contacts.create(
-    Contact(email="new@acme.com", first_name="New", last_name="Customer")
-)
-```
-
-### 2) Push many customers (bulk upsert)
-
-```python
-from contackd_sync import Contact
-
-result = client.contacts.bulk_upsert(
-    [
-        Contact(email="a@acme.com", first_name="A"),
-        Contact(email="b@acme.com", first_name="B", tags=["trial"]),
-    ]
-)
-
-print(len(result.created), len(result.updated), result.errors)
-```
-
-### 3) Read/filter customers
-
-```python
-page = client.contacts.list(page=1, per_page=50, email="jane@acme.com")
-```
-
-## API Key Setup
-
-Contact support@dalmlabs.com for the API key and base domain.
-
-## Backend Routes Expected by SDK
-
-Given `base_url = https://api.yourapp.com/api/v1`:
-
-- `GET /health`
-- `POST /tags`
-- `GET /tags`
-- `GET /tags/{id}`
-- `PUT /tags/{id}`
-- `DELETE /tags/{id}`
-- `POST /contacts|leads|prospects`
-- `GET /contacts|leads|prospects/{id}`
-- `PUT /contacts|leads|prospects/{id}`
-- `DELETE /contacts|leads|prospects/{id}`
-- `GET /contacts|leads|prospects`
-- `POST /contacts|leads|prospects/upsert`
-- `POST /contacts|leads|prospects/bulk`
-- `POST /contacts|leads|prospects/bulk/upsert`
-- `POST /contacts|leads|prospects/bulk/delete`