threecommon 0.3.0__tar.gz → 0.4.0__tar.gz

{threecommon-0.3.0 → threecommon-0.4.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## 0.4.0
+
+### Added
+
+- Contacts resource. The new `client.contacts` surface covers the full
+  contact lifecycle: `list`, `count`, `retrieve`, `create`, `update`
+  (with optional `merge_with` + `resolution` for absorbing a second
+  contact during an email change), `delete`, `bulk_upsert`,
+  `list_activity`, and both `list_auto_paginate` +
+  `list_activity_auto_paginate` iterators. Both sync and async surfaces.
+- New public types on `threecommon.contacts`: `Contact`,
+  `ContactWithOrderDetails`, `ContactActivity`, `ContactProperty`,
+  `ContactUpdate`, `CreateBody`, `UpdateBody`, `BulkUpsertBody`,
+  `BulkUpsertItem`, `ListParams`, `ActivityListParams`, plus result
+  envelopes `ListContactsResponse`, `ListActivityResponse`, `CountResult`,
+  `BulkUpsertResult`, `DeleteResult`, and the lifecycle / merge / activity
+  literal unions.
+
 ## 0.3.0
 
 ### Added

{threecommon-0.3.0 → threecommon-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threecommon
-Version: 0.3.0
+Version: 0.4.0
 Summary: Official Python client for the 3Common Public API.
 Project-URL: Homepage, https://github.com/3-Common/sdk/tree/main/sdk-python
 Project-URL: Issues, https://github.com/3-Common/sdk/issues

{threecommon-0.3.0 → threecommon-0.4.0}/pyproject.toml

@@ -10,7 +10,7 @@ license = { text = "MIT" }
 authors = [{ name = "3Common", email = "support@3common.com" }]
 keywords = ["3common", "sdk", "api-client", "events", "invoices"]
 requires-python = ">=3.10"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
     "httpx>=0.27,<1.0",
     "pydantic>=2.7,<3.0",

{threecommon-0.3.0 → threecommon-0.4.0}/src/threecommon/client.py

@@ -18,6 +18,7 @@ from threecommon._core.http_client import (
 from threecommon._core.retry import RetryPolicy
 from threecommon._core.telemetry import Telemetry
 from threecommon.config import RetryDelay, resolve_config
+from threecommon.contacts.service import AsyncContactsService, ContactsService
 from threecommon.events.service import AsyncEventsService, EventsService
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
 from threecommon.subscriptions.service import AsyncSubscriptionsService, SubscriptionsService
@@ -55,6 +56,11 @@ class ThreeCommon:
     subscriptions: SubscriptionsService
     """Subscriptions resource — list, retrieve, create, update, activate, cancel, bill, renew."""
 
+    contacts: ContactsService
+    """Contacts resource — ``list``, ``count``, ``retrieve``, ``create``,
+    ``update``, ``delete``, ``bulk_upsert``, ``list_activity``, plus
+    auto-paginators."""
+
     _http: HTTPClient
     _telemetry: Telemetry
 
@@ -98,6 +104,7 @@ class ThreeCommon:
         self.events = EventsService(self._http)
         self.invoices = InvoicesService(self._http)
         self.subscriptions = SubscriptionsService(self._http)
+        self.contacts = ContactsService(self._http)
 
     def close(self) -> None:
         """Close the underlying httpx client (no-op if you supplied your own)."""
@@ -126,6 +133,7 @@ class AsyncThreeCommon:
     events: AsyncEventsService
     invoices: AsyncInvoicesService
     subscriptions: AsyncSubscriptionsService
+    contacts: AsyncContactsService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -170,6 +178,7 @@ class AsyncThreeCommon:
         self.events = AsyncEventsService(self._http)
         self.invoices = AsyncInvoicesService(self._http)
         self.subscriptions = AsyncSubscriptionsService(self._http)
+        self.contacts = AsyncContactsService(self._http)
 
     async def aclose(self) -> None:
         """Close the underlying async httpx client."""

threecommon-0.4.0/src/threecommon/contacts/__init__.py

@@ -0,0 +1,58 @@
+"""Contacts resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.contacts][threecommon.ThreeCommon] /
+[AsyncThreeCommon.contacts][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.contacts.service import AsyncContactsService, ContactsService
+from threecommon.contacts.types import (
+    ActivityListParams,
+    BulkUpsertBody,
+    BulkUpsertItem,
+    BulkUpsertResult,
+    CompactContactStatus,
+    Contact,
+    ContactActivity,
+    ContactActivityType,
+    ContactMergeResolution,
+    ContactProperty,
+    ContactQuickFilter,
+    ContactStatus,
+    ContactUpdate,
+    ContactWithOrderDetails,
+    CountResult,
+    CreateBody,
+    DeleteResult,
+    ListActivityResponse,
+    ListContactsResponse,
+    ListParams,
+    UpdateBody,
+)
+
+__all__ = (
+    "ActivityListParams",
+    "AsyncContactsService",
+    "BulkUpsertBody",
+    "BulkUpsertItem",
+    "BulkUpsertResult",
+    "CompactContactStatus",
+    "Contact",
+    "ContactActivity",
+    "ContactActivityType",
+    "ContactMergeResolution",
+    "ContactProperty",
+    "ContactQuickFilter",
+    "ContactStatus",
+    "ContactUpdate",
+    "ContactWithOrderDetails",
+    "ContactsService",
+    "CountResult",
+    "CreateBody",
+    "DeleteResult",
+    "ListActivityResponse",
+    "ListContactsResponse",
+    "ListParams",
+    "UpdateBody",
+)

threecommon-0.4.0/src/threecommon/contacts/service.py

@@ -0,0 +1,331 @@
+"""Sync and async contacts services.
+
+Both services share the same wire shape and validation logic; the only
+difference is which HTTP client they call.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from threecommon._core.http_client import Request
+from threecommon.contacts.types import (
+    ActivityListParams,
+    BulkUpsertBody,
+    BulkUpsertResult,
+    Contact,
+    ContactActivity,
+    ContactWithOrderDetails,
+    CountResult,
+    CreateBody,
+    DeleteResult,
+    ListActivityResponse,
+    ListContactsResponse,
+    ListParams,
+    UpdateBody,
+)
+from threecommon.errors.classes import ValidationError
+from threecommon.pagination import AsyncIter, Iter
+
+if TYPE_CHECKING:
+    from threecommon._core.http_client import AsyncHTTPClient, HTTPClient
+
+
+def _encode_list_params(params: ListParams | None) -> dict[str, str] | None:
+    if params is None:
+        return None
+    raw = params.model_dump(by_alias=True, exclude_none=True)
+    if not raw:
+        return None
+    return {k: str(v) for k, v in raw.items()}
+
+
+def _encode_activity_params(params: ActivityListParams | None) -> dict[str, str] | None:
+    if params is None:
+        return None
+    raw = params.model_dump(by_alias=True, exclude_none=True)
+    if not raw:
+        return None
+    return {k: str(v) for k, v in raw.items()}
+
+
+def _require_id(method: str, contact_id: str) -> None:
+    if not contact_id:
+        msg = f"contacts.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(contact_id: str) -> str:
+    return f"/contacts/{quote(contact_id, safe='')}"
+
+
+def _activity_path(contact_id: str) -> str:
+    return f"{_path_for(contact_id)}/activity"
+
+
+# ---------------
+# Sync
+# ---------------
+
+
+class ContactsService:
+    """Sync contacts service — bound as ``client.contacts`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListContactsResponse:
+        """List the host's contacts (one page).
+
+        For full iteration use [list_auto_paginate][ContactsService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/contacts", query=_encode_list_params(params))
+        )
+        return ListContactsResponse.model_validate(body)
+
+    def count(self) -> CountResult:
+        """Return the total contact count for the host."""
+        body = self._http.request(Request(method="GET", path="/contacts/count"))
+        return CountResult.model_validate(body["data"])
+
+    def retrieve(self, contact_id: str) -> Contact:
+        """Retrieve a single contact by id."""
+        _require_id("retrieve", contact_id)
+        body = self._http.request(Request(method="GET", path=_path_for(contact_id)))
+        return Contact.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Contact:
+        """Create a new contact. Raises ``ConflictError`` on duplicate email."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(Request(method="POST", path="/contacts", body=payload))
+        return Contact.model_validate(response["data"])
+
+    def update(self, contact_id: str, body: UpdateBody) -> ContactWithOrderDetails:
+        """Update a contact. Returns the richer order-details projection."""
+        _require_id("update", contact_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="PATCH", path=_path_for(contact_id), body=payload)
+        )
+        return ContactWithOrderDetails.model_validate(response["data"])
+
+    def delete(self, contact_id: str) -> DeleteResult:
+        """Permanently remove a contact. Echoes the removed contact's id."""
+        _require_id("delete", contact_id)
+        response = self._http.request(Request(method="DELETE", path=_path_for(contact_id)))
+        return DeleteResult.model_validate(response["data"])
+
+    def bulk_upsert(self, body: BulkUpsertBody) -> BulkUpsertResult:
+        """Bulk-upsert up to 10,000 contacts in one round-trip.
+
+        Deduplicated server-side by email; existing rows are updated rather
+        than rejected.
+        """
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.bulk_upsert: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(Request(method="POST", path="/contacts/bulk", body=payload))
+        return BulkUpsertResult.model_validate(response["data"])
+
+    def list_activity(
+        self, contact_id: str, params: ActivityListParams | None = None
+    ) -> ListActivityResponse:
+        """Paginated activity log for a contact."""
+        _require_id("list_activity", contact_id)
+        body = self._http.request(
+            Request(
+                method="GET",
+                path=_activity_path(contact_id),
+                query=_encode_activity_params(params),
+            )
+        )
+        return ListActivityResponse.model_validate(body)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Contact]:
+        """Iterate every contact matching ``params``, paging automatically."""
+        start_page = (
+            params.page_number if params is not None and params.page_number is not None else 0
+        )
+
+        def fetch(page: int) -> tuple[list[Contact], bool]:
+            page_params = (
+                params.model_copy(update={"page_number": page})
+                if params is not None
+                else ListParams(page_number=page)
+            )
+            body = self._http.request(
+                Request(method="GET", path="/contacts", query=_encode_list_params(page_params))
+            )
+            response = ListContactsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+    def list_activity_auto_paginate(
+        self, contact_id: str, params: ActivityListParams | None = None
+    ) -> Iter[ContactActivity]:
+        """Iterate every activity record for a contact, paging automatically."""
+        _require_id("list_activity_auto_paginate", contact_id)
+        start_page = (
+            params.page_number if params is not None and params.page_number is not None else 0
+        )
+
+        def fetch(page: int) -> tuple[list[ContactActivity], bool]:
+            page_params = (
+                params.model_copy(update={"page_number": page})
+                if params is not None
+                else ActivityListParams(page_number=page)
+            )
+            body = self._http.request(
+                Request(
+                    method="GET",
+                    path=_activity_path(contact_id),
+                    query=_encode_activity_params(page_params),
+                )
+            )
+            response = ListActivityResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ---------------
+# Async
+# ---------------
+
+
+class AsyncContactsService:
+    """Async contacts service — bound as ``client.contacts`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListContactsResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/contacts", query=_encode_list_params(params))
+        )
+        return ListContactsResponse.model_validate(body)
+
+    async def count(self) -> CountResult:
+        body = await self._http.request(Request(method="GET", path="/contacts/count"))
+        return CountResult.model_validate(body["data"])
+
+    async def retrieve(self, contact_id: str) -> Contact:
+        _require_id("retrieve", contact_id)
+        body = await self._http.request(Request(method="GET", path=_path_for(contact_id)))
+        return Contact.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Contact:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(Request(method="POST", path="/contacts", body=payload))
+        return Contact.model_validate(response["data"])
+
+    async def update(self, contact_id: str, body: UpdateBody) -> ContactWithOrderDetails:
+        _require_id("update", contact_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="PATCH", path=_path_for(contact_id), body=payload)
+        )
+        return ContactWithOrderDetails.model_validate(response["data"])
+
+    async def delete(self, contact_id: str) -> DeleteResult:
+        _require_id("delete", contact_id)
+        response = await self._http.request(Request(method="DELETE", path=_path_for(contact_id)))
+        return DeleteResult.model_validate(response["data"])
+
+    async def bulk_upsert(self, body: BulkUpsertBody) -> BulkUpsertResult:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="contacts.bulk_upsert: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="POST", path="/contacts/bulk", body=payload)
+        )
+        return BulkUpsertResult.model_validate(response["data"])
+
+    async def list_activity(
+        self, contact_id: str, params: ActivityListParams | None = None
+    ) -> ListActivityResponse:
+        _require_id("list_activity", contact_id)
+        body = await self._http.request(
+            Request(
+                method="GET",
+                path=_activity_path(contact_id),
+                query=_encode_activity_params(params),
+            )
+        )
+        return ListActivityResponse.model_validate(body)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Contact]:
+        """Async iterate every contact matching ``params``."""
+        start_page = (
+            params.page_number if params is not None and params.page_number is not None else 0
+        )
+        http = self._http
+
+        async def fetch(page: int) -> tuple[list[Contact], bool]:
+            page_params = (
+                params.model_copy(update={"page_number": page})
+                if params is not None
+                else ListParams(page_number=page)
+            )
+            body = await http.request(
+                Request(method="GET", path="/contacts", query=_encode_list_params(page_params))
+            )
+            response = ListContactsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)
+
+    def list_activity_auto_paginate(
+        self, contact_id: str, params: ActivityListParams | None = None
+    ) -> AsyncIter[ContactActivity]:
+        """Async iterate every activity record for a contact."""
+        _require_id("list_activity_auto_paginate", contact_id)
+        start_page = (
+            params.page_number if params is not None and params.page_number is not None else 0
+        )
+        http = self._http
+
+        async def fetch(page: int) -> tuple[list[ContactActivity], bool]:
+            page_params = (
+                params.model_copy(update={"page_number": page})
+                if params is not None
+                else ActivityListParams(page_number=page)
+            )
+            body = await http.request(
+                Request(
+                    method="GET",
+                    path=_activity_path(contact_id),
+                    query=_encode_activity_params(page_params),
+                )
+            )
+            response = ListActivityResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.4.0/src/threecommon/contacts/types.py

@@ -0,0 +1,310 @@
+"""Public types for the contacts resource.
+
+Hand-curated Pydantic models that mirror the wire shape (camelCase aliases
+preserved). All response models use ``extra="ignore"`` so newer server-side
+fields don't break older SDK versions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Lifecycle status of a contact.
+#:
+#: * ``opted-in`` / ``unsubscribed``: explicit consent state
+#: * ``unknown``: never recorded a choice
+#: * ``imported``: created via CSV / bulk-upsert before consent was captured
+#: * ``deleted``: soft-deleted
+ContactStatus = Literal["deleted", "imported", "unsubscribed", "opted-in", "unknown"]
+
+#: Subset of statuses surfaced on the compact ``Contact`` projection
+#: returned by ``list``, ``retrieve``, and ``create``.
+CompactContactStatus = Literal["unsubscribed", "opted-in", "unknown"]
+
+#: How to resolve field-level conflicts when merging a second contact into
+#: the target during ``update``.
+ContactMergeResolution = Literal["safe-merge", "overwrite-merge"]
+
+#: The kind of event recorded against a contact in their activity feed.
+ContactActivityType = Literal[
+    "checkout_session_completed",
+    "product_set_checkout_session_completed",
+    "order_refunded",
+    "ticket_scanned",
+    "email_sent",
+    "invoice_paid",
+]
+
+#: Quick status filter accepted by ``ListParams.filter``. Case-insensitive
+#: on the wire; the SDK preserves casing.
+ContactQuickFilter = Literal["all", "opted-in", "unknown", "unsubscribed", "imported"]
+
+
+class _BaseModel(BaseModel):
+    """Shared config: accept snake_case or camelCase, ignore unknown fields."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+        str_strip_whitespace=False,
+    )
+
+
+class Contact(_BaseModel):
+    """A contact in the compact projection returned by ``list``, ``retrieve``,
+    and ``create``.
+
+    Custom-property keys (24-char hex ids) may appear as additional top-level
+    fields beyond those declared here — ``extra="ignore"`` on the base config
+    means we silently drop them; access via ``model_extra`` if needed.
+    """
+
+    id: str
+    first_name: str = Field(serialization_alias="firstName", validation_alias="firstName")
+    last_name: str = Field(serialization_alias="lastName", validation_alias="lastName")
+    full_name: str = Field(serialization_alias="fullName", validation_alias="fullName")
+    email: str
+    phone: str | None = None
+    vendor_id: str = Field(serialization_alias="vendorId", validation_alias="vendorId")
+    order_sum: int = Field(serialization_alias="orderSum", validation_alias="orderSum")
+    gross_sum: int = Field(serialization_alias="grossSum", validation_alias="grossSum")
+    first_order: int | None = Field(
+        default=None, serialization_alias="firstOrder", validation_alias="firstOrder"
+    )
+    last_order: int | None = Field(
+        default=None, serialization_alias="lastOrder", validation_alias="lastOrder"
+    )
+    created_at: str | None = Field(
+        default=None, serialization_alias="createdAt", validation_alias="createdAt"
+    )
+    status: CompactContactStatus
+    events_attended_ids: list[str] = Field(
+        default_factory=list,
+        serialization_alias="eventsAttended_IDS",
+        validation_alias="eventsAttended_IDS",
+    )
+    items_purchased_ids: list[str] = Field(
+        default_factory=list,
+        serialization_alias="itemsPurchased_IDS",
+        validation_alias="itemsPurchased_IDS",
+    )
+    products_purchased_ids: list[str] = Field(
+        default_factory=list,
+        serialization_alias="productsPurchased_IDS",
+        validation_alias="productsPurchased_IDS",
+    )
+
+
+class ContactProperty(_BaseModel):
+    """One custom-property entry on the richer order-details projection."""
+
+    property_id: str = Field(serialization_alias="property_id", validation_alias="property_id")
+    value: str | list[str] | bool
+
+
+class ContactWithOrderDetails(_BaseModel):
+    """The richer "order-details" projection returned by ``update``.
+
+    Includes raw ``events_attended`` / ``items_purchased`` / ``products_purchased``
+    arrays and the ``properties`` array, on top of everything in :class:`Contact`.
+    The id field on this projection is ``_id`` (Mongo-style), not ``id``.
+    """
+
+    id_: str = Field(serialization_alias="_id", validation_alias="_id")
+    email: str
+    vendor_id: str = Field(serialization_alias="vendorId", validation_alias="vendorId")
+    first_name: str = Field(serialization_alias="firstName", validation_alias="firstName")
+    last_name: str = Field(serialization_alias="lastName", validation_alias="lastName")
+    full_name: str = Field(serialization_alias="fullName", validation_alias="fullName")
+    phone: str | None = None
+    status: ContactStatus
+    gross_sum: int = Field(serialization_alias="grossSum", validation_alias="grossSum")
+    order_sum: int = Field(serialization_alias="orderSum", validation_alias="orderSum")
+    least_recent_order: str | None = Field(
+        default=None,
+        serialization_alias="leastRecentOrder",
+        validation_alias="leastRecentOrder",
+    )
+    most_recent_order: str | None = Field(
+        default=None, serialization_alias="mostRecentOrder", validation_alias="mostRecentOrder"
+    )
+    events_attended: list[str] = Field(default_factory=list)
+    items_purchased: list[str] = Field(default_factory=list)
+    products_purchased: list[str] = Field(default_factory=list)
+    properties: list[ContactProperty] | None = None
+    created_at: str | None = Field(
+        default=None, serialization_alias="createdAt", validation_alias="createdAt"
+    )
+    updated_at: str | None = Field(
+        default=None, serialization_alias="updatedAt", validation_alias="updatedAt"
+    )
+
+
+class ContactActivity(_BaseModel):
+    """A single activity record in a contact's activity feed."""
+
+    id_: str = Field(serialization_alias="_id", validation_alias="_id")
+    vendor_id: str = Field(serialization_alias="vendor_id", validation_alias="vendor_id")
+    email: str
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contact_id", validation_alias="contact_id"
+    )
+    type: ContactActivityType
+    data: dict[str, Any]
+    created_at: str = Field(serialization_alias="createdAt", validation_alias="createdAt")
+    updated_at: str = Field(serialization_alias="updatedAt", validation_alias="updatedAt")
+
+
+class ListContactsResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/contacts``."""
+
+    data: list[Contact]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+    page_number: int = Field(serialization_alias="pageNumber", validation_alias="pageNumber")
+    page_size: int = Field(serialization_alias="pageSize", validation_alias="pageSize")
+
+
+class ListActivityResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/contacts/{id}/activity``."""
+
+    data: list[ContactActivity]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+    page_number: int = Field(serialization_alias="pageNumber", validation_alias="pageNumber")
+    page_size: int = Field(serialization_alias="pageSize", validation_alias="pageSize")
+
+
+class CountResult(_BaseModel):
+    """Result shape returned by ``count``."""
+
+    count: int
+
+
+class BulkUpsertResult(_BaseModel):
+    """Result shape returned by ``bulk_upsert``."""
+
+    affected: int
+
+
+class DeleteResult(_BaseModel):
+    """Result shape returned by ``delete``. Echoes the removed contact id."""
+
+    id: str
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/contacts``."""
+
+    page_number: int | None = Field(
+        default=None, serialization_alias="pageNumber", validation_alias="pageNumber"
+    )
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    sort_field: str | None = Field(
+        default=None, serialization_alias="sortField", validation_alias="sortField"
+    )
+    sort_direction: Literal["asc", "desc"] | None = Field(
+        default=None, serialization_alias="sortDirection", validation_alias="sortDirection"
+    )
+    filter: ContactQuickFilter | None = None
+    filters: str | None = None
+    search: str | None = None
+
+
+class ActivityListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/contacts/{id}/activity``."""
+
+    page_number: int | None = Field(
+        default=None, serialization_alias="pageNumber", validation_alias="pageNumber"
+    )
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    filter: ContactActivityType | None = None
+    sort: Literal["oldest"] | None = None
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/contacts``."""
+
+    email: str
+    first_name: str | None = Field(
+        default=None, serialization_alias="firstName", validation_alias="firstName"
+    )
+    last_name: str | None = Field(
+        default=None, serialization_alias="lastName", validation_alias="lastName"
+    )
+    phone: str | None = None
+
+
+class ContactUpdate(_BaseModel):
+    """The nested ``contact`` object inside :class:`UpdateBody`."""
+
+    first_name: str = Field(serialization_alias="firstName", validation_alias="firstName")
+    last_name: str = Field(serialization_alias="lastName", validation_alias="lastName")
+    email: str
+    phone: str | None = None
+    status: ContactStatus
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/contacts/{id}``.
+
+    The nested ``contact`` object carries the new field values; ``merge_with``
+    and ``resolution`` are set together when an email change collides with
+    another contact.
+    """
+
+    contact: ContactUpdate
+    merge_with: str | None = Field(
+        default=None, serialization_alias="mergeWith", validation_alias="mergeWith"
+    )
+    resolution: ContactMergeResolution | None = None
+
+
+class BulkUpsertItem(_BaseModel):
+    """One row in :class:`BulkUpsertBody.contacts`. Wider than :class:`CreateBody`
+    to support CSV-import flows that carry status + properties + association
+    arrays."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        # Unlike other request bodies, the bulk endpoint accepts a `catchall`
+        # of 24-char hex custom-property keys at the top level. Keep them.
+        extra="allow",
+        str_strip_whitespace=False,
+    )
+
+    email: str
+    first_name: str | None = Field(
+        default=None, serialization_alias="firstName", validation_alias="firstName"
+    )
+    last_name: str | None = Field(
+        default=None, serialization_alias="lastName", validation_alias="lastName"
+    )
+    phone: str | None = None
+    status: ContactStatus | None = None
+    properties: list[ContactProperty] | None = None
+    events_attended_ids: list[str] | None = Field(
+        default=None,
+        serialization_alias="eventsAttended_IDS",
+        validation_alias="eventsAttended_IDS",
+    )
+    items_purchased_ids: list[str] | None = Field(
+        default=None,
+        serialization_alias="itemsPurchased_IDS",
+        validation_alias="itemsPurchased_IDS",
+    )
+    products_purchased_ids: list[str] | None = Field(
+        default=None,
+        serialization_alias="productsPurchased_IDS",
+        validation_alias="productsPurchased_IDS",
+    )
+
+
+class BulkUpsertBody(_BaseModel):
+    """Body accepted by ``POST /v1/contacts/bulk``."""
+
+    contacts: list[BulkUpsertItem]