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`).

## 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`
