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

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

@@ -1,16 +1,25 @@
 Metadata-Version: 2.4
 Name: contackd-sync
-Version: 0.3.0
-Summary: Python SDK for Contackd Sync
+Version: 0.4.0
+Summary: Sync CRM records and capture immutable person and business events with the Contackd API
 Project-URL: Homepage, https://example.com/contackd-sync
-Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.31.0
 Requires-Dist: urllib3>=2.0.0
 
 # contackd-sync (Python)
 
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
+Python SDK for syncing CRM records (`contacts`, `leads`, `prospects`, and `businesses`), managing deals, and capturing immutable person and business events.
+
+Requires Python 3.9 or later.
 
 ## Install
 
@@ -47,6 +56,53 @@ customer = client.contacts.upsert(
 print(customer)
 ```
 
+## Capture Custom Events
+
+```python
+from contackd_sync import PersonEvent
+
+event = client.person_events.track(
+    PersonEvent(
+        unified_id=customer.id,
+        event_name="financing",
+        status="applied",
+        correlation_id="application-10042",
+        amount="10000.00",
+        currency="NGN",
+    )
+)
+
+current_states = client.person_events.latest(customer.id)
+```
+
+Use `BusinessEvent` with `client.business_events` for B2B actions. Both event resources expose `track`, `track_batch`, `list`, and `latest`; a retry-safe `event_id` is generated when omitted.
+
+## Manage Deals
+
+```python
+from contackd_sync import Deal, DealStage, DealTransaction
+
+deal = client.deals.create(
+    Deal(
+        contact_id=customer.id,
+        title="Annual facility management plan",
+        amount="150000.00",
+        currency="NGN",
+    )
+)
+
+client.deals.update(deal.id, assigned_to_user_id="sales-agent-id")
+won = client.deals.update_stage(
+    deal.id,
+    DealStage.WON,
+    transaction=DealTransaction(external_transaction_id="payment-10042"),
+)
+```
+
+`client.deals` also provides `get` and `list`. List filters include
+`contact_id`, `lead_id`, `conversation_id`, `stage`, `q`, and
+`assigned_to_user_id`.
+
 ## Common Customer Push Patterns
 
 ### 1) Push one new customer
@@ -149,3 +205,12 @@ Given `base_url = https://api.yourapp.com/api/v1`:
 - `POST /contacts|leads|prospects|businesses/bulk`
 - `POST /contacts|leads|prospects|businesses/bulk/upsert`
 - `POST /contacts|leads|prospects|businesses/bulk/delete`
+- `POST /events/person|business`
+- `POST /events/person|business/batch`
+- `GET /events/person|business/{id}`
+- `GET /events/person|business/{id}/latest`
+- `POST /deals`
+- `GET /deals`
+- `GET /deals/{id}`
+- `PATCH /deals/{id}`
+- `PATCH /deals/{id}/stage`

contackd_sync-0.3.0/PKG-INFO → contackd_sync-0.4.0/README.md

@@ -1,16 +1,8 @@
-Metadata-Version: 2.4
-Name: contackd-sync
-Version: 0.3.0
-Summary: Python SDK for Contackd Sync
-Project-URL: Homepage, https://example.com/contackd-sync
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31.0
-Requires-Dist: urllib3>=2.0.0
-
 # contackd-sync (Python)
 
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
+Python SDK for syncing CRM records (`contacts`, `leads`, `prospects`, and `businesses`), managing deals, and capturing immutable person and business events.
+
+Requires Python 3.9 or later.
 
 ## Install
 
@@ -47,6 +39,53 @@ customer = client.contacts.upsert(
 print(customer)
 ```
 
+## Capture Custom Events
+
+```python
+from contackd_sync import PersonEvent
+
+event = client.person_events.track(
+    PersonEvent(
+        unified_id=customer.id,
+        event_name="financing",
+        status="applied",
+        correlation_id="application-10042",
+        amount="10000.00",
+        currency="NGN",
+    )
+)
+
+current_states = client.person_events.latest(customer.id)
+```
+
+Use `BusinessEvent` with `client.business_events` for B2B actions. Both event resources expose `track`, `track_batch`, `list`, and `latest`; a retry-safe `event_id` is generated when omitted.
+
+## Manage Deals
+
+```python
+from contackd_sync import Deal, DealStage, DealTransaction
+
+deal = client.deals.create(
+    Deal(
+        contact_id=customer.id,
+        title="Annual facility management plan",
+        amount="150000.00",
+        currency="NGN",
+    )
+)
+
+client.deals.update(deal.id, assigned_to_user_id="sales-agent-id")
+won = client.deals.update_stage(
+    deal.id,
+    DealStage.WON,
+    transaction=DealTransaction(external_transaction_id="payment-10042"),
+)
+```
+
+`client.deals` also provides `get` and `list`. List filters include
+`contact_id`, `lead_id`, `conversation_id`, `stage`, `q`, and
+`assigned_to_user_id`.
+
 ## Common Customer Push Patterns
 
 ### 1) Push one new customer
@@ -149,3 +188,12 @@ Given `base_url = https://api.yourapp.com/api/v1`:
 - `POST /contacts|leads|prospects|businesses/bulk`
 - `POST /contacts|leads|prospects|businesses/bulk/upsert`
 - `POST /contacts|leads|prospects|businesses/bulk/delete`
+- `POST /events/person|business`
+- `POST /events/person|business/batch`
+- `GET /events/person|business/{id}`
+- `GET /events/person|business/{id}/latest`
+- `POST /deals`
+- `GET /deals`
+- `GET /deals/{id}`
+- `PATCH /deals/{id}`
+- `PATCH /deals/{id}/stage`

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

@@ -6,16 +6,24 @@ from .client import (
     Business,
     BusinessesResource,
     BulkResult,
+    BusinessEvent,
+    BusinessEventsResource,
     ConflictStrategy,
     Contact,
     ContactsResource,
     ContackdClient,
     ContackdError,
+    Deal,
+    DealsResource,
+    DealStage,
+    DealTransaction,
     Lead,
     LeadStatus,
     LeadsResource,
     NotFoundError,
     PipelineStage,
+    PersonEvent,
+    PersonEventsResource,
     Prospect,
     ProspectsResource,
     RateLimitError,
@@ -23,6 +31,9 @@ from .client import (
     SyncConflictError,
     SyncEngine,
     SyncResult,
+    EventBatchError,
+    EventBatchResult,
+    EventList,
 )
 
 __all__ = [
@@ -31,16 +42,24 @@ __all__ = [
     "Business",
     "BusinessesResource",
     "BulkResult",
+    "BusinessEvent",
+    "BusinessEventsResource",
     "ConflictStrategy",
     "Contact",
     "ContactsResource",
     "ContackdClient",
     "ContackdError",
+    "Deal",
+    "DealsResource",
+    "DealStage",
+    "DealTransaction",
     "Lead",
     "LeadStatus",
     "LeadsResource",
     "NotFoundError",
     "PipelineStage",
+    "PersonEvent",
+    "PersonEventsResource",
     "Prospect",
     "ProspectsResource",
     "RateLimitError",
@@ -48,4 +67,7 @@ __all__ = [
     "SyncConflictError",
     "SyncEngine",
     "SyncResult",
+    "EventBatchError",
+    "EventBatchResult",
+    "EventList",
 ]

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

@@ -4,8 +4,9 @@ import hashlib
 import json
 from dataclasses import asdict, dataclass, field
 from enum import Enum
-from typing import Any, Callable, Dict, Generic, List, Optional, Protocol, TypeVar, Literal
-from urllib.parse import urljoin
+from typing import Any, Callable, Dict, Generic, List, Literal, Optional, Protocol, TypeVar, Union
+from urllib.parse import quote, urljoin
+from uuid import uuid4
 
 import requests
 from requests.adapters import HTTPAdapter
@@ -66,6 +67,18 @@ class PipelineStage(str, Enum):
     PURCHASE = "purchase"
 
 
+class DealStage(str, Enum):
+    """Supported first-class deal stages."""
+
+    NEW = "new"
+    QUALIFIED = "qualified"
+    PROPOSAL = "proposal"
+    NEGOTIATION = "negotiation"
+    FOLLOW_UP = "follow_up"
+    WON = "won"
+    LOST = "lost"
+
+
 @dataclass
 class Contact:
     """Contact record model used by the Contacts API."""
@@ -222,7 +235,170 @@ class Business:
         return hashlib.sha256(payload.encode()).hexdigest()
 
 
-RecordType = Contact | Lead | Prospect | Business
+@dataclass
+class DealTransaction:
+    """Purchase transaction attached to a won deal."""
+
+    external_transaction_id: Optional[str] = None
+    order_id: Optional[str] = None
+    status: str = "completed"
+    amount: Optional[str] = None
+    currency: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    deal_id: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Serialize fields accepted by a deal stage update."""
+        data = {
+            "external_transaction_id": self.external_transaction_id,
+            "order_id": self.order_id,
+            "status": self.status,
+            "amount": self.amount,
+            "currency": self.currency,
+            "metadata": self.metadata or None,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DealTransaction":
+        """Build a transaction from API response data."""
+        return cls(**{key: value for key, value in data.items() if key in cls.__dataclass_fields__})
+
+
+@dataclass
+class Deal:
+    """First-class sales opportunity linked to one contact or lead."""
+
+    title: str
+    contact_id: Optional[str] = None
+    lead_id: Optional[str] = None
+    conversation_id: Optional[str] = None
+    assigned_to_user_id: Optional[str] = None
+    description: Optional[str] = None
+    product_or_service: Optional[str] = None
+    amount: Optional[str] = None
+    currency: Optional[str] = None
+    expected_close_at: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    stage: DealStage = DealStage.NEW
+    won_at: Optional[str] = None
+    lost_at: Optional[str] = None
+    loss_reason: Optional[str] = None
+    transaction: Optional[DealTransaction] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Serialize fields accepted when creating a deal."""
+        data = {
+            "contact_id": self.contact_id,
+            "lead_id": self.lead_id,
+            "conversation_id": self.conversation_id,
+            "assigned_to_user_id": self.assigned_to_user_id,
+            "title": self.title,
+            "description": self.description,
+            "product_or_service": self.product_or_service,
+            "amount": self.amount,
+            "currency": self.currency,
+            "expected_close_at": self.expected_close_at,
+            "metadata": self.metadata or None,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Deal":
+        """Build a deal from API response data."""
+        payload = dict(data)
+        if "stage" in payload:
+            payload["stage"] = DealStage(payload["stage"])
+        if isinstance(payload.get("transaction"), dict):
+            payload["transaction"] = DealTransaction.from_dict(payload["transaction"])
+        return cls(**{key: value for key, value in payload.items() if key in cls.__dataclass_fields__})
+
+
+@dataclass
+class PersonEvent:
+    """Immutable custom event attributed to a person CRM ID."""
+
+    unified_id: str
+    event_name: str
+    status: str
+    event_id: Optional[str] = None
+    correlation_id: Optional[str] = None
+    amount: Optional[str] = None
+    currency: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+    occurred_at: Optional[str] = None
+    id: Optional[str] = None
+    actor: Dict[str, Any] = field(default_factory=dict)
+    source: Optional[str] = None
+    sdk_version: Optional[str] = None
+    received_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "event_id": self.event_id,
+            "unified_id": self.unified_id,
+            "event_name": self.event_name,
+            "status": self.status,
+            "correlation_id": self.correlation_id,
+            "amount": self.amount,
+            "currency": self.currency,
+            "properties": self.properties,
+            "occurred_at": self.occurred_at,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PersonEvent":
+        return cls(**{key: value for key, value in data.items() if key in cls.__dataclass_fields__})
+
+
+@dataclass
+class BusinessEvent:
+    """Immutable custom event attributed to a business CRM ID."""
+
+    business_id: str
+    event_name: str
+    status: str
+    event_id: Optional[str] = None
+    correlation_id: Optional[str] = None
+    amount: Optional[str] = None
+    currency: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+    occurred_at: Optional[str] = None
+    id: Optional[str] = None
+    actor: Dict[str, Any] = field(default_factory=dict)
+    source: Optional[str] = None
+    sdk_version: Optional[str] = None
+    received_at: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "event_id": self.event_id,
+            "business_id": self.business_id,
+            "event_name": self.event_name,
+            "status": self.status,
+            "correlation_id": self.correlation_id,
+            "amount": self.amount,
+            "currency": self.currency,
+            "properties": self.properties,
+            "occurred_at": self.occurred_at,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BusinessEvent":
+        return cls(**{key: value for key, value in data.items() if key in cls.__dataclass_fields__})
+
+
+RecordType = Union[Contact, Lead, Prospect, Business]
 ConflictStrategy = Literal["local", "remote", "raise"]
 RecordT = TypeVar("RecordT", Contact, Lead, Prospect, Business)
 
@@ -321,11 +497,120 @@ class _HttpClient:
         self._raise(response)
         return response.json()
 
+    def patch(self, path: str, body: dict) -> dict:
+        response = self.session.patch(self._url(path), json=body, timeout=self.timeout)
+        self._raise(response)
+        return response.json()
+
     def delete(self, path: str) -> None:
         response = self.session.delete(self._url(path), timeout=self.timeout)
         self._raise(response)
 
 
+EventT = TypeVar("EventT", PersonEvent, BusinessEvent)
+
+
+@dataclass
+class EventBatchError:
+    index: int
+    status_code: int
+    detail: Any
+    event_id: Optional[str] = None
+
+
+@dataclass
+class EventBatchResult(Generic[EventT]):
+    created: List[EventT] = field(default_factory=list)
+    duplicates: List[EventT] = field(default_factory=list)
+    errors: List[EventBatchError] = field(default_factory=list)
+    total: int = 0
+
+
+@dataclass
+class EventList(Generic[EventT]):
+    results: List[EventT] = field(default_factory=list)
+    page: int = 1
+    per_page: int = 50
+    total: int = 0
+
+
+class _EventsResource(Generic[EventT]):
+    def __init__(self, http: _HttpClient, kind: str, model: type[EventT]):
+        self._http = http
+        self._kind = kind
+        self._model = model
+
+    @staticmethod
+    def _event_body(event: EventT) -> dict:
+        body = event.to_dict()
+        if not body.get("event_id"):
+            body["event_id"] = f"evt_{uuid4()}"
+        return body
+
+    def track(self, event: EventT) -> EventT:
+        data = self._http.post(f"events/{self._kind}", self._event_body(event))
+        return self._model.from_dict(data)
+
+    def track_batch(self, events: List[EventT]) -> EventBatchResult[EventT]:
+        data = self._http.post(
+            f"events/{self._kind}/batch",
+            {"events": [self._event_body(event) for event in events]},
+        )
+        return EventBatchResult(
+            created=[self._model.from_dict(item) for item in data.get("created", [])],
+            duplicates=[self._model.from_dict(item) for item in data.get("duplicates", [])],
+            errors=[
+                EventBatchError(
+                    index=item["index"],
+                    event_id=item.get("event_id"),
+                    status_code=item["status_code"],
+                    detail=item.get("detail"),
+                )
+                for item in data.get("errors", [])
+            ],
+            total=data.get("total", 0),
+        )
+
+    def list(self, subject_id: str, page: int = 1, per_page: int = 50, **filters: Any) -> EventList[EventT]:
+        return self._read(subject_id, page=page, per_page=per_page, latest=False, filters=filters)
+
+    def latest(self, subject_id: str, page: int = 1, per_page: int = 50, **filters: Any) -> EventList[EventT]:
+        return self._read(subject_id, page=page, per_page=per_page, latest=True, filters=filters)
+
+    def _read(
+        self,
+        subject_id: str,
+        *,
+        page: int,
+        per_page: int,
+        latest: bool,
+        filters: Dict[str, Any],
+    ) -> EventList[EventT]:
+        suffix = "/latest" if latest else ""
+        data = self._http.get(
+            f"events/{self._kind}/{quote(subject_id, safe='')}{suffix}",
+            page=page,
+            per_page=per_page,
+            **filters,
+        )
+        return EventList(
+            results=[self._model.from_dict(item) for item in data.get("results", [])],
+            page=data.get("page", page),
+            per_page=data.get("per_page", per_page),
+            total=data.get("total", 0),
+        )
+
+
+class PersonEventsResource(_EventsResource[PersonEvent]):
+    def __init__(self, http: _HttpClient):
+        super().__init__(http, "person", PersonEvent)
+
+
+class BusinessEventsResource(_EventsResource[BusinessEvent]):
+    def __init__(self, http: _HttpClient):
+        super().__init__(http, "business", BusinessEvent)
+
+
 class _Resource(Generic[RecordT]):
     """Base CRUD and bulk helpers for a typed API resource."""
 
@@ -437,6 +722,55 @@ class BusinessesResource(_Resource[Business]):
     _model = Business
 
 
+class DealsResource:
+    """Typed resource wrapper for first-class deals."""
+
+    def __init__(self, http: _HttpClient):
+        self._http = http
+
+    def create(self, deal: Deal) -> Deal:
+        """Create a deal linked to one contact or lead."""
+        return Deal.from_dict(self._http.post("deals", deal.to_dict()))
+
+    def get(self, deal_id: str) -> Deal:
+        """Fetch a deal by ID."""
+        data = self._http.get(f"deals/{quote(deal_id, safe='')}")
+        return Deal.from_dict(data)
+
+    def list(self, limit: int = 50, offset: int = 0, **filters: Any) -> List[Deal]:
+        """List deals using the API's filters and offset pagination."""
+        data = self._http.get("deals", limit=limit, offset=offset, **filters)
+        items = data.get("results", data) if isinstance(data, dict) else data
+        return [Deal.from_dict(item) for item in items]
+
+    def update(self, deal_id: str, **changes: Any) -> Deal:
+        """Patch assignment or editable deal details."""
+        data = self._http.patch(f"deals/{quote(deal_id, safe='')}", changes)
+        return Deal.from_dict(data)
+
+    def update_stage(
+        self,
+        deal_id: str,
+        stage: Union[DealStage, str],
+        *,
+        loss_reason: Optional[str] = None,
+        transaction: Optional[DealTransaction] = None,
+    ) -> Deal:
+        """Move a deal to another stage and optionally attach a transaction."""
+        body: Dict[str, Any] = {
+            "stage": stage.value if isinstance(stage, DealStage) else stage,
+        }
+        if loss_reason is not None:
+            body["loss_reason"] = loss_reason
+        if transaction is not None:
+            body["transaction"] = transaction.to_dict()
+        data = self._http.patch(
+            f"deals/{quote(deal_id, safe='')}/stage",
+            body,
+        )
+        return Deal.from_dict(data)
+
+
 @dataclass
 class SyncResult:
     """Outcome summary for a bidirectional sync operation."""
@@ -566,6 +900,9 @@ class ContackdClient:
         self.leads = LeadsResource(self._http)
         self.prospects = ProspectsResource(self._http)
         self.businesses = BusinessesResource(self._http)
+        self.deals = DealsResource(self._http)
+        self.person_events = PersonEventsResource(self._http)
+        self.business_events = BusinessEventsResource(self._http)
 
     def sync_contacts(
         self,
@@ -641,16 +978,24 @@ __all__ = [
     "Business",
     "BusinessesResource",
     "BulkResult",
+    "BusinessEvent",
+    "BusinessEventsResource",
     "ConflictStrategy",
     "Contact",
     "ContactsResource",
     "ContackdClient",
     "ContackdError",
+    "Deal",
+    "DealsResource",
+    "DealStage",
+    "DealTransaction",
     "Lead",
     "LeadStatus",
     "LeadsResource",
     "NotFoundError",
     "PipelineStage",
+    "PersonEvent",
+    "PersonEventsResource",
     "Prospect",
     "ProspectsResource",
     "RateLimitError",
@@ -658,4 +1003,7 @@ __all__ = [
     "SyncConflictError",
     "SyncEngine",
     "SyncResult",
+    "EventBatchError",
+    "EventBatchResult",
+    "EventList",
 ]

contackd_sync-0.3.0/README.md → contackd_sync-0.4.0/contackd_sync.egg-info/PKG-INFO

@@ -1,6 +1,25 @@
+Metadata-Version: 2.4
+Name: contackd-sync
+Version: 0.4.0
+Summary: Sync CRM records and capture immutable person and business events with the Contackd API
+Project-URL: Homepage, https://example.com/contackd-sync
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: urllib3>=2.0.0
+
 # contackd-sync (Python)
 
-Python SDK for pushing and syncing customer data (`contacts`, `leads`, `prospects`, `businesses`).
+Python SDK for syncing CRM records (`contacts`, `leads`, `prospects`, and `businesses`), managing deals, and capturing immutable person and business events.
+
+Requires Python 3.9 or later.
 
 ## Install
 
@@ -37,6 +56,53 @@ customer = client.contacts.upsert(
 print(customer)
 ```
 
+## Capture Custom Events
+
+```python
+from contackd_sync import PersonEvent
+
+event = client.person_events.track(
+    PersonEvent(
+        unified_id=customer.id,
+        event_name="financing",
+        status="applied",
+        correlation_id="application-10042",
+        amount="10000.00",
+        currency="NGN",
+    )
+)
+
+current_states = client.person_events.latest(customer.id)
+```
+
+Use `BusinessEvent` with `client.business_events` for B2B actions. Both event resources expose `track`, `track_batch`, `list`, and `latest`; a retry-safe `event_id` is generated when omitted.
+
+## Manage Deals
+
+```python
+from contackd_sync import Deal, DealStage, DealTransaction
+
+deal = client.deals.create(
+    Deal(
+        contact_id=customer.id,
+        title="Annual facility management plan",
+        amount="150000.00",
+        currency="NGN",
+    )
+)
+
+client.deals.update(deal.id, assigned_to_user_id="sales-agent-id")
+won = client.deals.update_stage(
+    deal.id,
+    DealStage.WON,
+    transaction=DealTransaction(external_transaction_id="payment-10042"),
+)
+```
+
+`client.deals` also provides `get` and `list`. List filters include
+`contact_id`, `lead_id`, `conversation_id`, `stage`, `q`, and
+`assigned_to_user_id`.
+
 ## Common Customer Push Patterns
 
 ### 1) Push one new customer
@@ -139,3 +205,12 @@ Given `base_url = https://api.yourapp.com/api/v1`:
 - `POST /contacts|leads|prospects|businesses/bulk`
 - `POST /contacts|leads|prospects|businesses/bulk/upsert`
 - `POST /contacts|leads|prospects|businesses/bulk/delete`
+- `POST /events/person|business`
+- `POST /events/person|business/batch`
+- `GET /events/person|business/{id}`
+- `GET /events/person|business/{id}/latest`
+- `POST /deals`
+- `GET /deals`
+- `GET /deals/{id}`
+- `PATCH /deals/{id}`
+- `PATCH /deals/{id}/stage`

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

@@ -9,4 +9,6 @@ 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
+tests/test_client.py
+tests/test_deals.py
+tests/test_python39_compatibility.py

contackd_sync-0.4.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contackd-sync"
+version = "0.4.0"
+description = "Sync CRM records and capture immutable person and business events with the Contackd API"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "requests>=2.31.0",
+  "urllib3>=2.0.0",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://example.com/contackd-sync"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["contackd_sync*"]

contackd_sync-0.4.0/tests/test_client.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+import json
+from contextlib import contextmanager
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from threading import Thread
+from urllib.parse import parse_qs, urlparse
+
+import contackd_sync
+from contackd_sync import ContackdClient, Lead, LeadStatus, SyncEngine
+
+
+def test_cold_lead_without_email_parses_conversation_fields() -> None:
+    lead = Lead.from_dict(
+        {
+            "id": "lead-1",
+            "status": "cold",
+            "title": "WhatsApp inquiry",
+            "display_name": "Ada",
+            "conversation_id": "conversation-1",
+            "external_thread_id": "+2348012345678",
+            "phone": "+2348012345678",
+        }
+    )
+
+    assert lead.email is None
+    assert lead.status is LeadStatus.COLD
+    assert lead.title == "WhatsApp inquiry"
+    assert lead.display_name == "Ada"
+    assert lead.conversation_id == "conversation-1"
+    assert lead.external_thread_id == "+2348012345678"
+    assert lead.phone == "+2348012345678"
+
+
+def test_sdk_version_header_matches_installed_package_version() -> None:
+    client = ContackdClient(api_key="test-key", base_url="https://api.example.com")
+
+    assert client._http.session.headers["X-SDK-Version"] == version("contackd-sync")
+
+
+class _InMemoryLeadResource:
+    def __init__(self, records: list[Lead]):
+        self.records = records
+
+    def list(self, page: int = 1, per_page: int = 100, **filters: object) -> list[Lead]:
+        del per_page, filters
+        return self.records if page == 1 else []
+
+    def bulk_upsert(self, records: list[Lead], chunk_size: int = 100) -> None:
+        raise AssertionError(f"unexpected push of {len(records)} records in chunks of {chunk_size}")
+
+
+def test_sync_matches_email_less_leads_by_external_thread_id() -> None:
+    remote_a = Lead(
+        status=LeadStatus.COLD,
+        display_name="Remote Ada",
+        external_thread_id="thread-a",
+    )
+    remote_b = Lead(
+        status=LeadStatus.COLD,
+        display_name="Remote Grace",
+        external_thread_id="thread-b",
+    )
+    local_a = Lead(
+        status=LeadStatus.COLD,
+        display_name="Local Ada",
+        external_thread_id="thread-a",
+    )
+    engine = SyncEngine(_InMemoryLeadResource([remote_a, remote_b]), conflict_strategy="remote")
+
+    result = engine.sync([local_a])
+
+    assert result.pushed == []
+    assert result.remote_only == [remote_b]
+
+
+@contextmanager
+def _event_api_server():
+    requests: list[dict] = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, format: str, *args: object) -> None:
+            del format, args
+
+        def do_POST(self) -> None:
+            length = int(self.headers.get("Content-Length", "0"))
+            body = json.loads(self.rfile.read(length) or b"{}")
+            requests.append({"method": "POST", "path": self.path, "body": body})
+            if self.path.endswith("/batch"):
+                response = {"created": [], "duplicates": [], "errors": [], "total": len(body["events"])}
+            else:
+                response = {
+                    "id": "internal-1",
+                    **body,
+                    "actor": {"type": "api_key", "id": "user-1", "email": "apikey:mobile"},
+                    "source": "sdk",
+                    "sdk_version": "0.3.0",
+                    "received_at": "2026-08-28T10:31:00Z",
+                }
+            encoded = json.dumps(response).encode()
+            self.send_response(201)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+
+        def do_GET(self) -> None:
+            parsed = urlparse(self.path)
+            requests.append({"method": "GET", "path": parsed.path, "query": parse_qs(parsed.query)})
+            encoded = json.dumps({"results": [], "page": 2, "per_page": 25, "total": 0}).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}", requests
+    finally:
+        server.shutdown()
+        thread.join()
+        server.server_close()
+
+
+def test_python_person_events_generate_ids_and_serialize_exact_contract() -> None:
+    assert hasattr(contackd_sync, "PersonEvent")
+    with _event_api_server() as (base_url, requests):
+        client = ContackdClient(api_key="test-key", base_url=base_url)
+        event = client.person_events.track(
+            contackd_sync.PersonEvent(
+                unified_id="contact-1",
+                event_name="financing",
+                status="applied",
+                correlation_id="application-1",
+                amount="10000.00",
+                currency="NGN",
+                properties={"product": "vehicle"},
+                occurred_at="2026-08-28T10:30:00Z",
+            )
+        )
+
+    assert requests[0]["body"]["event_id"].startswith("evt_")
+    assert requests[0]["body"]["unified_id"] == "contact-1"
+    assert event.event_id == requests[0]["body"]["event_id"]
+    assert event.received_at == "2026-08-28T10:31:00Z"
+
+
+def test_python_business_events_batch_and_latest_filters() -> None:
+    assert hasattr(contackd_sync, "BusinessEvent")
+    with _event_api_server() as (base_url, requests):
+        client = ContackdClient(api_key="test-key", base_url=base_url)
+        batch = client.business_events.track_batch(
+            [
+                contackd_sync.BusinessEvent(
+                    event_id="evt-order-1",
+                    business_id="business-1",
+                    event_name="purchase",
+                    status="completed",
+                )
+            ]
+        )
+        latest = client.business_events.latest(
+            "business-1",
+            page=2,
+            per_page=25,
+            event_name="purchase",
+            correlation_id="order-1",
+        )
+
+    assert batch.total == 1
+    assert latest.page == 2
+    assert requests[0]["body"]["events"][0]["event_id"] == "evt-order-1"
+    assert requests[1]["path"] == "/events/business/business-1/latest"
+    assert requests[1]["query"]["event_name"] == ["purchase"]
+    assert requests[1]["query"]["correlation_id"] == ["order-1"]

contackd_sync-0.4.0/tests/test_deals.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import contackd_sync
+
+
+class RecordingHttpClient:
+    def __init__(self, responses: list[object]) -> None:
+        self.responses = list(responses)
+        self.requests: list[tuple[str, str, object]] = []
+
+    def get(self, path: str, **params: object) -> object:
+        self.requests.append(("GET", path, params))
+        return self.responses.pop(0)
+
+    def post(self, path: str, body: dict[str, object]) -> object:
+        self.requests.append(("POST", path, body))
+        return self.responses.pop(0)
+
+    def patch(self, path: str, body: dict[str, object]) -> object:
+        self.requests.append(("PATCH", path, body))
+        return self.responses.pop(0)
+
+
+def test_deal_models_serialize_requests_and_parse_responses() -> None:
+    assert hasattr(contackd_sync, "Deal")
+    assert hasattr(contackd_sync, "DealStage")
+    assert hasattr(contackd_sync, "DealTransaction")
+
+    deal = contackd_sync.Deal(
+        contact_id="contact-1",
+        title="Annual plan",
+        amount="150000.00",
+        currency="NGN",
+        metadata={"source": "website"},
+    )
+
+    assert deal.to_dict() == {
+        "contact_id": "contact-1",
+        "title": "Annual plan",
+        "amount": "150000.00",
+        "currency": "NGN",
+        "metadata": {"source": "website"},
+    }
+
+    parsed = contackd_sync.Deal.from_dict(
+        {
+            **deal.to_dict(),
+            "id": "deal-1",
+            "tenant_id": "tenant-1",
+            "stage": "won",
+            "transaction": {
+                "id": "transaction-1",
+                "deal_id": "deal-1",
+                "tenant_id": "tenant-1",
+                "status": "completed",
+                "amount": "150000.00",
+                "currency": "NGN",
+                "metadata": {},
+            },
+        }
+    )
+
+    assert parsed.stage is contackd_sync.DealStage.WON
+    assert isinstance(parsed.transaction, contackd_sync.DealTransaction)
+    assert parsed.transaction.id == "transaction-1"
+
+
+def test_deals_resource_creates_gets_and_lists_typed_deals() -> None:
+    assert hasattr(contackd_sync, "DealsResource")
+    response = {
+        "id": "deal-1",
+        "tenant_id": "tenant-1",
+        "contact_id": "contact-1",
+        "title": "Annual plan",
+        "stage": "new",
+        "metadata": {},
+    }
+    http = RecordingHttpClient([response, response, [response]])
+    resource = contackd_sync.DealsResource(http)
+
+    created = resource.create(
+        contackd_sync.Deal(contact_id="contact-1", title="Annual plan")
+    )
+    fetched = resource.get("deal-1")
+    listed = resource.list(limit=25, offset=10, stage="new")
+
+    assert created.id == "deal-1"
+    assert fetched.id == "deal-1"
+    assert [deal.id for deal in listed] == ["deal-1"]
+    assert http.requests == [
+        (
+            "POST",
+            "deals",
+            {"contact_id": "contact-1", "title": "Annual plan"},
+        ),
+        ("GET", "deals/deal-1", {}),
+        ("GET", "deals", {"limit": 25, "offset": 10, "stage": "new"}),
+    ]
+
+
+def test_deals_resource_updates_details_and_stage_with_patch() -> None:
+    response = {
+        "id": "deal-1",
+        "tenant_id": "tenant-1",
+        "contact_id": "contact-1",
+        "title": "Renewed plan",
+        "stage": "won",
+        "metadata": {},
+    }
+    http = RecordingHttpClient([response, response])
+    resource = contackd_sync.DealsResource(http)
+
+    updated = resource.update(
+        "deal-1",
+        title="Renewed plan",
+        assigned_to_user_id=None,
+    )
+    won = resource.update_stage(
+        "deal-1",
+        contackd_sync.DealStage.WON,
+        transaction=contackd_sync.DealTransaction(
+            external_transaction_id="payment-1",
+            amount="150000.00",
+            currency="NGN",
+        ),
+    )
+
+    assert updated.title == "Renewed plan"
+    assert won.stage is contackd_sync.DealStage.WON
+    assert http.requests == [
+        (
+            "PATCH",
+            "deals/deal-1",
+            {"title": "Renewed plan", "assigned_to_user_id": None},
+        ),
+        (
+            "PATCH",
+            "deals/deal-1/stage",
+            {
+                "stage": "won",
+                "transaction": {
+                    "external_transaction_id": "payment-1",
+                    "status": "completed",
+                    "amount": "150000.00",
+                    "currency": "NGN",
+                },
+            },
+        ),
+    ]
+
+
+def test_client_exposes_deals_resource() -> None:
+    client = contackd_sync.ContackdClient(
+        api_key="test-key",
+        base_url="https://api.example.com/api/v1",
+    )
+
+    assert isinstance(client.deals, contackd_sync.DealsResource)

contackd_sync-0.4.0/tests/test_python39_compatibility.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+import contackd_sync
+
+
+def test_public_record_type_imports_on_python39() -> None:
+    assert contackd_sync.RecordType is not None

contackd_sync-0.3.0/pyproject.toml

@@ -1,21 +0,0 @@
-[build-system]
-requires = ["setuptools>=68", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "contackd-sync"
-version = "0.3.0"
-description = "Python SDK for Contackd Sync"
-readme = "README.md"
-requires-python = ">=3.10"
-dependencies = [
-  "requests>=2.31.0",
-  "urllib3>=2.0.0",
-]
-
-[project.urls]
-Homepage = "https://example.com/contackd-sync"
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["contackd_sync*"]

contackd_sync-0.3.0/tests/test_client.py

@@ -1,67 +0,0 @@
-from importlib.metadata import version
-
-from contackd_sync import ContackdClient, Lead, LeadStatus, SyncEngine
-
-
-def test_cold_lead_without_email_parses_conversation_fields() -> None:
-    lead = Lead.from_dict(
-        {
-            "id": "lead-1",
-            "status": "cold",
-            "title": "WhatsApp inquiry",
-            "display_name": "Ada",
-            "conversation_id": "conversation-1",
-            "external_thread_id": "+2348012345678",
-            "phone": "+2348012345678",
-        }
-    )
-
-    assert lead.email is None
-    assert lead.status is LeadStatus.COLD
-    assert lead.title == "WhatsApp inquiry"
-    assert lead.display_name == "Ada"
-    assert lead.conversation_id == "conversation-1"
-    assert lead.external_thread_id == "+2348012345678"
-    assert lead.phone == "+2348012345678"
-
-
-def test_sdk_version_header_matches_installed_package_version() -> None:
-    client = ContackdClient(api_key="test-key", base_url="https://api.example.com")
-
-    assert client._http.session.headers["X-SDK-Version"] == version("contackd-sync")
-
-
-class _InMemoryLeadResource:
-    def __init__(self, records: list[Lead]):
-        self.records = records
-
-    def list(self, page: int = 1, per_page: int = 100, **filters: object) -> list[Lead]:
-        del per_page, filters
-        return self.records if page == 1 else []
-
-    def bulk_upsert(self, records: list[Lead], chunk_size: int = 100) -> None:
-        raise AssertionError(f"unexpected push of {len(records)} records in chunks of {chunk_size}")
-
-
-def test_sync_matches_email_less_leads_by_external_thread_id() -> None:
-    remote_a = Lead(
-        status=LeadStatus.COLD,
-        display_name="Remote Ada",
-        external_thread_id="thread-a",
-    )
-    remote_b = Lead(
-        status=LeadStatus.COLD,
-        display_name="Remote Grace",
-        external_thread_id="thread-b",
-    )
-    local_a = Lead(
-        status=LeadStatus.COLD,
-        display_name="Local Ada",
-        external_thread_id="thread-a",
-    )
-    engine = SyncEngine(_InMemoryLeadResource([remote_a, remote_b]), conflict_strategy="remote")
-
-    result = engine.sync([local_a])
-
-    assert result.pushed == []
-    assert result.remote_only == [remote_b]