threecommon 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -5,6 +5,19 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threecommon
-Version: 0.4.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.4.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.4.0"
+version = "0.5.0"
 dependencies = [
     "httpx>=0.27,<1.0",
     "pydantic>=2.7,<3.0",

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

@@ -19,6 +19,7 @@ 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
@@ -61,6 +62,10 @@ class ThreeCommon:
     ``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
 
@@ -105,6 +110,7 @@ class ThreeCommon:
         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)."""
@@ -134,6 +140,7 @@ class AsyncThreeCommon:
     invoices: AsyncInvoicesService
     subscriptions: AsyncSubscriptionsService
     contacts: AsyncContactsService
+    entitlements: AsyncEntitlementsService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -179,6 +186,7 @@ class AsyncThreeCommon:
         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/entitlements/__init__.py

@@ -0,0 +1,37 @@
+"""Entitlements resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.entitlements][threecommon.ThreeCommon] /
+[AsyncThreeCommon.entitlements][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.entitlements.service import (
+    AsyncEntitlementsService,
+    EntitlementsService,
+)
+from threecommon.entitlements.types import (
+    ConsumeBody,
+    Entitlement,
+    EntitlementGrant,
+    EntitlementGrantSource,
+    GrantBody,
+    ListEntitlementsResponse,
+    ListParams,
+    LookupParams,
+    RetrieveParams,
+)
+
+__all__ = (
+    "AsyncEntitlementsService",
+    "ConsumeBody",
+    "Entitlement",
+    "EntitlementGrant",
+    "EntitlementGrantSource",
+    "EntitlementsService",
+    "GrantBody",
+    "ListEntitlementsResponse",
+    "ListParams",
+    "LookupParams",
+    "RetrieveParams",
+)

threecommon-0.5.0/src/threecommon/entitlements/service.py

@@ -0,0 +1,243 @@
+"""Sync and async entitlements 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.entitlements.types import (
+    ConsumeBody,
+    Entitlement,
+    GrantBody,
+    ListEntitlementsResponse,
+    ListParams,
+    LookupParams,
+    RetrieveParams,
+)
+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_retrieve_params(params: RetrieveParams | None) -> dict[str, str] | None:
+    if params is None or params.fields is None:
+        return None
+    return {"fields": params.fields}
+
+
+def _encode_lookup_params(params: LookupParams) -> dict[str, str]:
+    raw = params.model_dump(by_alias=True, exclude_none=True)
+    return {k: str(v) for k, v in raw.items()}
+
+
+def _require_id(method: str, entitlement_id: str) -> None:
+    if not entitlement_id:
+        msg = f"entitlements.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _require_lookup_params(params: LookupParams) -> None:
+    if not params.contact_id:
+        raise ValidationError(
+            code="missing_contact_id",
+            message="entitlements.lookup: contact_id must be a non-empty string",
+        )
+    if not params.feature_key:
+        raise ValidationError(
+            code="missing_feature_key",
+            message="entitlements.lookup: feature_key must be a non-empty string",
+        )
+
+
+def _path_for(entitlement_id: str) -> str:
+    return f"/entitlements/{quote(entitlement_id, safe='')}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class EntitlementsService:
+    """Sync entitlements service — bound as ``client.entitlements`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListEntitlementsResponse:
+        """List the host's entitlement balance records (one page).
+
+        For full iteration use
+        [list_auto_paginate][EntitlementsService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/entitlements", query=_encode_list_params(params))
+        )
+        return ListEntitlementsResponse.model_validate(body)
+
+    def retrieve(self, entitlement_id: str, params: RetrieveParams | None = None) -> Entitlement:
+        """Retrieve a single entitlement record by id, including grant history."""
+        _require_id("retrieve", entitlement_id)
+        body = self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(entitlement_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Entitlement.model_validate(body["data"])
+
+    def lookup(self, params: LookupParams) -> Entitlement:
+        """Look up the unique entitlement for a ``(contact_id, feature_key)`` pair.
+
+        Raises [NotFoundError][threecommon.NotFoundError] if no record exists yet.
+        """
+        _require_lookup_params(params)
+        body = self._http.request(
+            Request(method="GET", path="/entitlements/lookup", query=_encode_lookup_params(params))
+        )
+        return Entitlement.model_validate(body["data"])
+
+    def grant(self, body: GrantBody) -> Entitlement:
+        """Add a manual entitlement grant. Idempotent on ``grant_id``."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="entitlements.grant: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="POST", path="/entitlements/grants", body=payload)
+        )
+        return Entitlement.model_validate(response["data"])
+
+    def consume(self, body: ConsumeBody) -> Entitlement:
+        """Debit units from a customer's entitlement balance.
+
+        Raises [ConflictError][threecommon.ConflictError] on insufficient balance.
+        """
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="entitlements.consume: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="POST", path="/entitlements/consume", body=payload)
+        )
+        return Entitlement.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Entitlement]:
+        """Iterate every entitlement matching ``params``, paging automatically."""
+        start_page = params.page if params is not None and params.page is not None else 0
+
+        def fetch(page: int) -> tuple[list[Entitlement], bool]:
+            page_params = (
+                params.model_copy(update={"page": page})
+                if params is not None
+                else ListParams(page=page)
+            )
+            body = self._http.request(
+                Request(method="GET", path="/entitlements", query=_encode_list_params(page_params))
+            )
+            response = ListEntitlementsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncEntitlementsService:
+    """Async entitlements service — bound as ``client.entitlements`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListEntitlementsResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/entitlements", query=_encode_list_params(params))
+        )
+        return ListEntitlementsResponse.model_validate(body)
+
+    async def retrieve(
+        self, entitlement_id: str, params: RetrieveParams | None = None
+    ) -> Entitlement:
+        _require_id("retrieve", entitlement_id)
+        body = await self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(entitlement_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Entitlement.model_validate(body["data"])
+
+    async def lookup(self, params: LookupParams) -> Entitlement:
+        _require_lookup_params(params)
+        body = await self._http.request(
+            Request(method="GET", path="/entitlements/lookup", query=_encode_lookup_params(params))
+        )
+        return Entitlement.model_validate(body["data"])
+
+    async def grant(self, body: GrantBody) -> Entitlement:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="entitlements.grant: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="POST", path="/entitlements/grants", body=payload)
+        )
+        return Entitlement.model_validate(response["data"])
+
+    async def consume(self, body: ConsumeBody) -> Entitlement:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="entitlements.consume: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = await self._http.request(
+            Request(method="POST", path="/entitlements/consume", body=payload)
+        )
+        return Entitlement.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Entitlement]:
+        """Async iterate every entitlement matching ``params``."""
+        start_page = params.page if params is not None and params.page is not None else 0
+        http = self._http
+
+        async def fetch(page: int) -> tuple[list[Entitlement], bool]:
+            page_params = (
+                params.model_copy(update={"page": page})
+                if params is not None
+                else ListParams(page=page)
+            )
+            body = await http.request(
+                Request(method="GET", path="/entitlements", query=_encode_list_params(page_params))
+            )
+            response = ListEntitlementsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.5.0/src/threecommon/entitlements/types.py

@@ -0,0 +1,142 @@
+"""Public types for the entitlements 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 Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Source of an entitlement grant.
+#:
+#: * ``subscription_recurring`` — cycle grant from a subscription renewal.
+#: * ``one_time_addon`` — top-up purchase (consumed first by ``consume``).
+#: * ``manual`` — admin-applied grant.
+EntitlementGrantSource = Literal[
+    "subscription_recurring",
+    "one_time_addon",
+    "manual",
+]
+
+
+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 EntitlementGrant(_BaseModel):
+    """One grant in an entitlement's grant history."""
+
+    id: str
+    source: EntitlementGrantSource
+    source_id: str | None = Field(
+        default=None, serialization_alias="sourceId", validation_alias="sourceId"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    amount: int
+    remaining: int
+    added_at: str = Field(serialization_alias="addedAt", validation_alias="addedAt")
+
+
+class Entitlement(_BaseModel):
+    """One entitlement balance record as returned by the API.
+
+    Optional fields are populated only when the server returned them — list
+    responses with a ``fields`` filter omit unrequested values.
+    """
+
+    id: str
+    host_id: str | None = Field(
+        default=None, serialization_alias="hostId", validation_alias="hostId"
+    )
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    feature_key: str | None = Field(
+        default=None, serialization_alias="featureKey", validation_alias="featureKey"
+    )
+    balance: int | None = None
+    grants: list[EntitlementGrant] | None = None
+    total_granted: int | None = Field(
+        default=None, serialization_alias="totalGranted", validation_alias="totalGranted"
+    )
+    total_consumed: int | None = Field(
+        default=None, serialization_alias="totalConsumed", validation_alias="totalConsumed"
+    )
+    metadata: dict[str, str] | 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 ListEntitlementsResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/entitlements``."""
+
+    data: list[Entitlement]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/entitlements``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    feature_key: str | None = Field(
+        default=None, serialization_alias="featureKey", validation_alias="featureKey"
+    )
+    min_balance: int | None = Field(
+        default=None, serialization_alias="minBalance", validation_alias="minBalance"
+    )
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/entitlements/{id}``."""
+
+    fields: str | None = None
+
+
+class LookupParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/entitlements/lookup``."""
+
+    contact_id: str = Field(serialization_alias="contactId", validation_alias="contactId")
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    fields: str | None = None
+
+
+class GrantBody(_BaseModel):
+    """Body accepted by ``POST /v1/entitlements/grants``."""
+
+    contact_id: str = Field(serialization_alias="contactId", validation_alias="contactId")
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    amount: int
+    grant_id: str = Field(serialization_alias="grantId", validation_alias="grantId")
+    metadata: dict[str, str] | None = None
+
+
+class ConsumeBody(_BaseModel):
+    """Body accepted by ``POST /v1/entitlements/consume``."""
+
+    contact_id: str = Field(serialization_alias="contactId", validation_alias="contactId")
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    amount: int
+    reason: str | None = None