threecommon 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -5,6 +5,37 @@ versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## 0.5.0
+
+### Added
+
+- Entitlements resource. The new `client.entitlements` surface covers balance
+  lookups and grant management: `list`, `retrieve`, `lookup` (by contact +
+  feature), `grant` (manual top-up, idempotent on `grant_id`), `consume`
+  (debit balance), and `list_auto_paginate`. Both sync and async surfaces.
+- New public types on `threecommon.entitlements`: `Entitlement`,
+  `EntitlementGrant`, `EntitlementGrantSource`, `GrantBody`, `ConsumeBody`,
+  `ListParams`, `RetrieveParams`, `LookupParams`, and the
+  `ListEntitlementsResponse` envelope.
+
+## 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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threecommon
-Version: 0.3.0
+Version: 0.5.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.5.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.5.0"
 dependencies = [
     "httpx>=0.27,<1.0",
     "pydantic>=2.7,<3.0",

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

@@ -18,6 +18,8 @@ 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.entitlements.service import AsyncEntitlementsService, EntitlementsService
 from threecommon.events.service import AsyncEventsService, EventsService
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
 from threecommon.subscriptions.service import AsyncSubscriptionsService, SubscriptionsService
@@ -55,6 +57,15 @@ 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."""
+
+    entitlements: EntitlementsService
+    """Entitlements resource — ``list``, ``retrieve``, ``lookup``, ``grant``,
+    ``consume``, plus ``list_auto_paginate``."""
+
     _http: HTTPClient
     _telemetry: Telemetry
 
@@ -98,6 +109,8 @@ class ThreeCommon:
         self.events = EventsService(self._http)
         self.invoices = InvoicesService(self._http)
         self.subscriptions = SubscriptionsService(self._http)
+        self.contacts = ContactsService(self._http)
+        self.entitlements = EntitlementsService(self._http)
 
     def close(self) -> None:
         """Close the underlying httpx client (no-op if you supplied your own)."""
@@ -126,6 +139,8 @@ class AsyncThreeCommon:
     events: AsyncEventsService
     invoices: AsyncInvoicesService
     subscriptions: AsyncSubscriptionsService
+    contacts: AsyncContactsService
+    entitlements: AsyncEntitlementsService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -170,6 +185,8 @@ class AsyncThreeCommon:
         self.events = AsyncEventsService(self._http)
         self.invoices = AsyncInvoicesService(self._http)
         self.subscriptions = AsyncSubscriptionsService(self._http)
+        self.contacts = AsyncContactsService(self._http)
+        self.entitlements = AsyncEntitlementsService(self._http)
 
     async def aclose(self) -> None:
         """Close the underlying async httpx client."""

threecommon-0.5.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.5.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)