threecommon 0.2.0__tar.gz → 0.4.0__tar.gz

threecommon-0.4.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+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
+
+- Invoices: auto_charge, refund_payment, delete_draft methods (sync + async).
+- Invoices: subscription_id filter on list().
+- Invoices: AutoChargeOutcome, AutoChargeResult, DeletedInvoice, RefundBody types.
+
+## 0.2.0
+
+### Added
+
+- Invoice write operations completing parity with the public REST surface, on
+  both the sync and async clients:
+  - `auto_charge` — off-session charge the customer's saved card
+    (`POST /v1/invoices/{id}/auto_charge`). A decline resolves with
+    `outcome="failed"` and a `failure_code` rather than raising; only network /
+    processor 5xx errors raise.
+  - `refund_payment` — refund all or part of a recorded payment
+    (`POST /v1/invoices/{id}/payments/{paymentId}/refunds`). Idempotent on
+    `body.idempotency_key`.
+  - `delete_draft` — permanently remove a draft invoice
+    (`DELETE /v1/invoices/{id}`).
+- New public types on `threecommon.invoices`: `AutoChargeResult`,
+  `AutoChargeOutcome`, `RefundBody`, and `DeletedInvoice`.
+
+### Fixed
+
+- `InvoiceStatus` now includes `payment_failed` (the state set after a failed
+  off-session auto-charge); it was previously missing.
+- Invoice `ListParams` now accepts the `subscription_id` filter the API
+  supports; it was previously missing.
+
+## 0.1.0
+
+### Added
+
+- Subscriptions resource. The new `client.subscriptions` surface covers the
+  full subscription lifecycle: `list`, `retrieve`, `create`, `update`
+  (mid-cycle change with proration), `activate`, `cancel`,
+  `cancel_immediately`, `mark_unpaid`, `bill`, `renew`,
+  `preview_upcoming_invoice`, and `list_auto_paginate`. Types and typed
+  errors match the events / invoices resources. Both sync and async surfaces.
+
+## 0.0.0
+
+### Added
+
+- Initial scaffolding.
+- `ThreeCommon` (sync) and `AsyncThreeCommon` (async) clients.
+- Events resource: `list`, `retrieve`, `update`, `list_auto_paginate`.
+- Invoices resource: `list`, `retrieve`, `create`, `update`, `finalize`, `void`,
+  `record_payment`, `list_auto_paginate`. Both sync and async surfaces.
+- Typed exception tree (`AuthError`, `NotFoundError`, `RateLimitError`, …).
+- Conformance harness running shared YAML scenarios against both clients.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threecommon
-Version: 0.2.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.2.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.2.0"
+version = "0.4.0"
 dependencies = [
     "httpx>=0.27,<1.0",
     "pydantic>=2.7,<3.0",

{threecommon-0.2.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]

{threecommon-0.2.0 → threecommon-0.4.0}/src/threecommon/invoices/__init__.py

@@ -8,7 +8,10 @@ service classes directly is supported for advanced wiring.
 
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
 from threecommon.invoices.types import (
+    AutoChargeOutcome,
+    AutoChargeResult,
     CreateBody,
+    DeletedInvoice,
     Invoice,
     InvoiceCurrency,
     InvoiceLineItem,
@@ -17,6 +20,7 @@ from threecommon.invoices.types import (
     ListInvoicesResponse,
     ListParams,
     PaymentBody,
+    RefundBody,
     RetrieveParams,
     UpdateBody,
     VoidBody,
@@ -24,7 +28,10 @@ from threecommon.invoices.types import (
 
 __all__ = (
     "AsyncInvoicesService",
+    "AutoChargeOutcome",
+    "AutoChargeResult",
     "CreateBody",
+    "DeletedInvoice",
     "Invoice",
     "InvoiceCurrency",
     "InvoiceLineItem",
@@ -34,6 +41,7 @@ __all__ = (
     "ListInvoicesResponse",
     "ListParams",
     "PaymentBody",
+    "RefundBody",
     "RetrieveParams",
     "UpdateBody",
     "VoidBody",

{threecommon-0.2.0 → threecommon-0.4.0}/src/threecommon/invoices/service.py

@@ -6,17 +6,20 @@ difference is which HTTP client they call.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from urllib.parse import quote
 
 from threecommon._core.http_client import Request
 from threecommon.errors.classes import ValidationError
 from threecommon.invoices.types import (
+    AutoChargeResult,
     CreateBody,
+    DeletedInvoice,
     Invoice,
     ListInvoicesResponse,
     ListParams,
     PaymentBody,
+    RefundBody,
     RetrieveParams,
     UpdateBody,
     VoidBody,
@@ -56,6 +59,23 @@ def _action_path(invoice_id: str, action: str) -> str:
     return f"{_path_for(invoice_id)}/{action}"
 
 
+def _refund_path(invoice_id: str, payment_id: str) -> str:
+    return f"{_path_for(invoice_id)}/payments/{quote(payment_id, safe='')}/refunds"
+
+
+def _build_auto_charge_result(response: dict[str, Any]) -> AutoChargeResult:
+    payload: dict[str, Any] = {"invoice": response["data"], "outcome": response["outcome"]}
+    if response.get("failureCode") is not None:
+        payload["failure_code"] = response["failureCode"]
+    return AutoChargeResult.model_validate(payload)
+
+
+def _require_payment_id(payment_id: str) -> None:
+    if not payment_id:
+        msg = "invoices.refund_payment: payment_id must be a non-empty string"
+        raise ValidationError(code="missing_payment_id", message=msg)
+
+
 # ────────────────────────────────────────────────────────────────────────────
 # Sync
 # ────────────────────────────────────────────────────────────────────────────
@@ -148,6 +168,48 @@ class InvoicesService:
         )
         return Invoice.model_validate(response["data"])
 
+    def auto_charge(self, invoice_id: str) -> AutoChargeResult:
+        """Off-session charge the customer's saved card for an open invoice.
+
+        A decline is not an error — it resolves with ``outcome="failed"`` and a
+        ``failure_code``, leaving the invoice in ``payment_failed``. Only
+        network / processor 5xx errors raise.
+        """
+        _require_id("auto_charge", invoice_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "auto_charge"), body={})
+        )
+        return _build_auto_charge_result(response)
+
+    def refund_payment(self, invoice_id: str, payment_id: str, body: RefundBody) -> Invoice:
+        """Refund all or part of a recorded payment on a paid invoice.
+
+        Idempotent on ``body.idempotency_key``: replays return the existing
+        refund without contacting the processor again.
+        """
+        _require_id("refund_payment", invoice_id)
+        _require_payment_id(payment_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body",
+                message="invoices.refund_payment: body must be non-None",
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="POST", path=_refund_path(invoice_id, payment_id), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    def delete_draft(self, invoice_id: str) -> DeletedInvoice:
+        """Permanently delete a draft invoice.
+
+        Only legal while in ``draft`` (no number issued); finalized invoices
+        must be voided instead so the audit trail stays intact.
+        """
+        _require_id("delete_draft", invoice_id)
+        response = self._http.request(Request(method="DELETE", path=_path_for(invoice_id)))
+        return DeletedInvoice.model_validate(response["data"])
+
     def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Invoice]:
         """Iterate every invoice matching ``params``, paging automatically."""
         start_page = params.page if params is not None and params.page is not None else 0
@@ -246,6 +308,32 @@ class AsyncInvoicesService:
         )
         return Invoice.model_validate(response["data"])
 
+    async def auto_charge(self, invoice_id: str) -> AutoChargeResult:
+        _require_id("auto_charge", invoice_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "auto_charge"), body={})
+        )
+        return _build_auto_charge_result(response)
+
+    async def refund_payment(self, invoice_id: str, payment_id: str, body: RefundBody) -> Invoice:
+        _require_id("refund_payment", invoice_id)
+        _require_payment_id(payment_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body",
+                message="invoices.refund_payment: body must be non-None",
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="POST", path=_refund_path(invoice_id, payment_id), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    async def delete_draft(self, invoice_id: str) -> DeletedInvoice:
+        _require_id("delete_draft", invoice_id)
+        response = await self._http.request(Request(method="DELETE", path=_path_for(invoice_id)))
+        return DeletedInvoice.model_validate(response["data"])
+
     def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Invoice]:
         """Async iterate every invoice matching ``params``."""
         start_page = params.page if params is not None and params.page is not None else 0

{threecommon-0.2.0 → threecommon-0.4.0}/src/threecommon/invoices/types.py

@@ -11,13 +11,17 @@ from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-#: Lifecycle status of an invoice. Future server-side values will arrive as
-#: raw strings until the SDK is updated.
-InvoiceStatus = Literal["draft", "open", "paid", "void"]
+#: Lifecycle status of an invoice. ``payment_failed`` is set when an off-session
+#: auto-charge attempt is rejected (decline / SCA / no card); the invoice is
+#: still owed and can be retried or paid manually.
+InvoiceStatus = Literal["draft", "open", "payment_failed", "paid", "void"]
 
 #: Invoice currency code; all line amounts must match.
 InvoiceCurrency = Literal["USD", "CAD"]
 
+#: Outcome of an auto-charge attempt.
+AutoChargeOutcome = Literal["paid", "failed"]
+
 
 class _BaseModel(BaseModel):
     """Shared config: accept snake_case or camelCase, ignore unknown fields."""
@@ -130,6 +134,9 @@ class ListParams(_BaseModel):
     customer_id: str | None = Field(
         default=None, serialization_alias="customerId", validation_alias="customerId"
     )
+    subscription_id: str | None = Field(
+        default=None, serialization_alias="subscriptionId", validation_alias="subscriptionId"
+    )
     issued_after: str | None = Field(
         default=None, serialization_alias="issuedAfter", validation_alias="issuedAfter"
     )
@@ -193,3 +200,35 @@ class PaymentBody(_BaseModel):
         default=None, serialization_alias="idempotencyKey", validation_alias="idempotencyKey"
     )
     note: str | None = None
+
+
+class RefundBody(_BaseModel):
+    """Body accepted by ``POST /v1/invoices/{id}/payments/{paymentId}/refunds``."""
+
+    amount: int
+    reason: Literal["duplicate", "fraudulent", "requested_by_customer"] | None = None
+    note: str | None = None
+    idempotency_key: str | None = Field(
+        default=None, serialization_alias="idempotencyKey", validation_alias="idempotencyKey"
+    )
+
+
+class AutoChargeResult(_BaseModel):
+    """Successful response shape from ``POST /v1/invoices/{id}/auto_charge``.
+
+    A card decline is an expected business outcome, not an error: ``outcome`` is
+    ``"failed"`` with the invoice left in ``payment_failed`` and a
+    ``failure_code`` set. Only network / processor 5xx errors raise.
+    """
+
+    invoice: Invoice
+    outcome: AutoChargeOutcome
+    failure_code: str | None = Field(
+        default=None, serialization_alias="failureCode", validation_alias="failureCode"
+    )
+
+
+class DeletedInvoice(_BaseModel):
+    """Result of ``DELETE /v1/invoices/{id}`` — the id of the removed draft."""
+
+    id: str

threecommon-0.2.0/CHANGELOG.md

@@ -1,29 +0,0 @@
-# Changelog
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## 0.1.0
-
-### Added
-
-- Subscriptions resource. The new `client.subscriptions` surface covers the
-  full subscription lifecycle: `list`, `retrieve`, `create`, `update`
-  (mid-cycle change with proration), `activate`, `cancel`,
-  `cancel_immediately`, `mark_unpaid`, `bill`, `renew`,
-  `preview_upcoming_invoice`, and `list_auto_paginate`. Types and typed
-  errors match the events / invoices resources. Both sync and async surfaces.
-
-## 0.0.0
-
-### Added
-
-- Initial scaffolding.
-- `ThreeCommon` (sync) and `AsyncThreeCommon` (async) clients.
-- Events resource: `list`, `retrieve`, `update`, `list_auto_paginate`.
-- Invoices resource: `list`, `retrieve`, `create`, `update`, `finalize`, `void`,
-  `record_payment`, `list_auto_paginate`. Both sync and async surfaces.
-- Typed exception tree (`AuthError`, `NotFoundError`, `RateLimitError`, …).
-- Conformance harness running shared YAML scenarios against both clients.