threecommon 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -5,6 +5,34 @@ versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## 0.7.0
+
+### Added
+
+- Features resource. The new `client.features` surface covers the feature
+  catalog: `list`, `resolve` (resolve a feature's live value for a customer),
+  `retrieve`, `create`, `update`, `archive`, `unarchive`, and a
+  `list_auto_paginate` iterator. Both sync and async surfaces.
+- New public types on `threecommon.features`: `Feature`, `FeatureType`,
+  `ResolvedFeature`, the `ResolvedFeatureValue` discriminated union and its
+  `ResolvedFeatureBoolean`/`ResolvedFeatureQuantity`/`ResolvedFeatureEnum`/
+  `ResolvedFeatureDuration` members, `CreateBody`, `UpdateBody`, `ListParams`,
+  `RetrieveParams`, `ResolveParams`, and the `ListFeaturesResponse` envelope.
+
+## 0.6.0
+
+### Added
+
+- Prices resource. The new `client.prices` surface covers the price catalog:
+  `list`, `retrieve`, `create`, `update`, `archive`, `unarchive`, and a
+  `list_auto_paginate` iterator. Both sync and async surfaces.
+- New public types on `threecommon.prices`: `Price`, `PriceRecurring`,
+  `PriceFeature` (the boolean/quantity/enum/duration grant union) and its
+  `PriceFeatureBoolean`/`PriceFeatureQuantity`/`PriceFeatureEnum`/
+  `PriceFeatureDuration` members, `CreateBody`, `UpdateBody`, `ListParams`,
+  `RetrieveParams`, the `ListPricesResponse` envelope, and the
+  `PriceType`/`PriceCurrency`/`PriceInterval` literal unions.
+
 ## 0.5.0
 
 ### Added

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

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

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

@@ -21,7 +21,9 @@ 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.features.service import AsyncFeaturesService, FeaturesService
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
+from threecommon.prices.service import AsyncPricesService, PricesService
 from threecommon.subscriptions.service import AsyncSubscriptionsService, SubscriptionsService
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -66,6 +68,14 @@ class ThreeCommon:
     """Entitlements resource — ``list``, ``retrieve``, ``lookup``, ``grant``,
     ``consume``, plus ``list_auto_paginate``."""
 
+    prices: PricesService
+    """Prices resource — ``list``, ``retrieve``, ``create``, ``update``,
+    ``archive``, ``unarchive``, plus ``list_auto_paginate``."""
+
+    features: FeaturesService
+    """Features resource — ``list``, ``resolve``, ``retrieve``, ``create``,
+    ``update``, ``archive``, ``unarchive``, plus ``list_auto_paginate``."""
+
     _http: HTTPClient
     _telemetry: Telemetry
 
@@ -111,6 +121,8 @@ class ThreeCommon:
         self.subscriptions = SubscriptionsService(self._http)
         self.contacts = ContactsService(self._http)
         self.entitlements = EntitlementsService(self._http)
+        self.prices = PricesService(self._http)
+        self.features = FeaturesService(self._http)
 
     def close(self) -> None:
         """Close the underlying httpx client (no-op if you supplied your own)."""
@@ -141,6 +153,8 @@ class AsyncThreeCommon:
     subscriptions: AsyncSubscriptionsService
     contacts: AsyncContactsService
     entitlements: AsyncEntitlementsService
+    prices: AsyncPricesService
+    features: AsyncFeaturesService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -187,6 +201,8 @@ class AsyncThreeCommon:
         self.subscriptions = AsyncSubscriptionsService(self._http)
         self.contacts = AsyncContactsService(self._http)
         self.entitlements = AsyncEntitlementsService(self._http)
+        self.prices = AsyncPricesService(self._http)
+        self.features = AsyncFeaturesService(self._http)
 
     async def aclose(self) -> None:
         """Close the underlying async httpx client."""

threecommon-0.7.0/src/threecommon/features/__init__.py

@@ -0,0 +1,42 @@
+"""Features resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.features][threecommon.ThreeCommon] /
+[AsyncThreeCommon.features][threecommon.AsyncThreeCommon]; importing the service
+classes directly is supported for advanced wiring.
+"""
+
+from threecommon.features.service import AsyncFeaturesService, FeaturesService
+from threecommon.features.types import (
+    CreateBody,
+    Feature,
+    FeatureType,
+    ListFeaturesResponse,
+    ListParams,
+    ResolvedFeature,
+    ResolvedFeatureBoolean,
+    ResolvedFeatureDuration,
+    ResolvedFeatureEnum,
+    ResolvedFeatureQuantity,
+    ResolveParams,
+    RetrieveParams,
+    UpdateBody,
+)
+
+__all__ = (
+    "AsyncFeaturesService",
+    "CreateBody",
+    "Feature",
+    "FeatureType",
+    "FeaturesService",
+    "ListFeaturesResponse",
+    "ListParams",
+    "ResolveParams",
+    "ResolvedFeature",
+    "ResolvedFeatureBoolean",
+    "ResolvedFeatureDuration",
+    "ResolvedFeatureEnum",
+    "ResolvedFeatureQuantity",
+    "RetrieveParams",
+    "UpdateBody",
+)

threecommon-0.7.0/src/threecommon/features/service.py

@@ -0,0 +1,251 @@
+"""Sync and async features 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.errors.classes import ValidationError
+from threecommon.features.types import (
+    CreateBody,
+    Feature,
+    ListFeaturesResponse,
+    ListParams,
+    ResolvedFeature,
+    ResolveParams,
+    RetrieveParams,
+    UpdateBody,
+)
+from threecommon.pagination import AsyncIter, Iter
+
+if TYPE_CHECKING:
+    from threecommon._core.http_client import AsyncHTTPClient, HTTPClient
+
+
+def _qval(value: object) -> str:
+    # The wire (and every other SDK) renders query booleans lowercase.
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+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: _qval(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_resolve_params(params: ResolveParams) -> 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, feature_id: str) -> None:
+    if not feature_id:
+        msg = f"features.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(feature_id: str) -> str:
+    return f"/features/{quote(feature_id, safe='')}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class FeaturesService:
+    """Sync features service — bound as ``client.features`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListFeaturesResponse:
+        """List the host's feature catalog (one page).
+
+        For full iteration use [list_auto_paginate][FeaturesService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/features", query=_encode_list_params(params))
+        )
+        return ListFeaturesResponse.model_validate(body)
+
+    def resolve(self, params: ResolveParams) -> ResolvedFeature:
+        """Resolve a feature's live value for a customer.
+
+        Walks active subscriptions -> prices -> feature grants. Raises
+        [NotFoundError][threecommon.NotFoundError] if the feature key is unknown.
+        """
+        body = self._http.request(
+            Request(method="GET", path="/features/resolve", query=_encode_resolve_params(params))
+        )
+        return ResolvedFeature.model_validate(body["data"])
+
+    def retrieve(self, feature_id: str, params: RetrieveParams | None = None) -> Feature:
+        """Retrieve a single feature by id."""
+        _require_id("retrieve", feature_id)
+        body = self._http.request(
+            Request(method="GET", path=_path_for(feature_id), query=_encode_retrieve_params(params))
+        )
+        return Feature.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Feature:
+        """Create a feature in the catalog."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="features.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = self._http.request(Request(method="POST", path="/features", body=payload))
+        return Feature.model_validate(response["data"])
+
+    def update(self, feature_id: str, body: UpdateBody) -> Feature:
+        """Apply a partial update to a feature. Set a field to ``None`` to clear it."""
+        _require_id("update", feature_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="features.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = self._http.request(
+            Request(method="PATCH", path=_path_for(feature_id), body=payload)
+        )
+        return Feature.model_validate(response["data"])
+
+    def archive(self, feature_id: str) -> Feature:
+        """Soft-archive a feature. Idempotent."""
+        _require_id("archive", feature_id)
+        response = self._http.request(
+            Request(method="POST", path=f"{_path_for(feature_id)}/archive", body={})
+        )
+        return Feature.model_validate(response["data"])
+
+    def unarchive(self, feature_id: str) -> Feature:
+        """Reactivate a previously archived feature. Idempotent."""
+        _require_id("unarchive", feature_id)
+        response = self._http.request(
+            Request(method="POST", path=f"{_path_for(feature_id)}/unarchive", body={})
+        )
+        return Feature.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Feature]:
+        """Iterate every feature 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[Feature], 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="/features", query=_encode_list_params(page_params))
+            )
+            response = ListFeaturesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncFeaturesService:
+    """Async features service — bound as ``client.features`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListFeaturesResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/features", query=_encode_list_params(params))
+        )
+        return ListFeaturesResponse.model_validate(body)
+
+    async def resolve(self, params: ResolveParams) -> ResolvedFeature:
+        body = await self._http.request(
+            Request(method="GET", path="/features/resolve", query=_encode_resolve_params(params))
+        )
+        return ResolvedFeature.model_validate(body["data"])
+
+    async def retrieve(self, feature_id: str, params: RetrieveParams | None = None) -> Feature:
+        _require_id("retrieve", feature_id)
+        body = await self._http.request(
+            Request(method="GET", path=_path_for(feature_id), query=_encode_retrieve_params(params))
+        )
+        return Feature.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Feature:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="features.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = await self._http.request(Request(method="POST", path="/features", body=payload))
+        return Feature.model_validate(response["data"])
+
+    async def update(self, feature_id: str, body: UpdateBody) -> Feature:
+        _require_id("update", feature_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="features.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = await self._http.request(
+            Request(method="PATCH", path=_path_for(feature_id), body=payload)
+        )
+        return Feature.model_validate(response["data"])
+
+    async def archive(self, feature_id: str) -> Feature:
+        _require_id("archive", feature_id)
+        response = await self._http.request(
+            Request(method="POST", path=f"{_path_for(feature_id)}/archive", body={})
+        )
+        return Feature.model_validate(response["data"])
+
+    async def unarchive(self, feature_id: str) -> Feature:
+        _require_id("unarchive", feature_id)
+        response = await self._http.request(
+            Request(method="POST", path=f"{_path_for(feature_id)}/unarchive", body={})
+        )
+        return Feature.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Feature]:
+        """Async iterate every feature 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[Feature], 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="/features", query=_encode_list_params(page_params))
+            )
+            response = ListFeaturesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.7.0/src/threecommon/features/types.py

@@ -0,0 +1,175 @@
+"""Public types for the features 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 Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Feature value shape.
+#:
+#: * ``boolean`` — pure on/off.
+#: * ``quantity`` — countable; drives entitlement balance.
+#: * ``enum`` — one of a fixed ordered set of values.
+#: * ``duration`` — number of days (or unlimited).
+FeatureType = Literal["boolean", "quantity", "enum", "duration"]
+
+
+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 Feature(_BaseModel):
+    """One feature in the host's catalog.
+
+    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"
+    )
+    key: str | None = None
+    name: str | None = None
+    description: str | None = None
+    type: FeatureType | None = None
+    enum_values: list[str] | None = Field(
+        default=None, serialization_alias="enumValues", validation_alias="enumValues"
+    )
+    active: bool | None = None
+    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 ResolvedFeatureBoolean(_BaseModel):
+    """Resolved value of a boolean feature."""
+
+    type: Literal["boolean"]
+    enabled: bool
+
+
+class ResolvedFeatureQuantity(_BaseModel):
+    """Resolved value of a quantity feature. ``quantity`` ``None`` = unlimited."""
+
+    type: Literal["quantity"]
+    quantity: int | None
+    balance: int | None = None
+
+
+class ResolvedFeatureEnum(_BaseModel):
+    """Resolved value of an enum feature."""
+
+    type: Literal["enum"]
+    enum_value: str | None = Field(serialization_alias="enumValue", validation_alias="enumValue")
+
+
+class ResolvedFeatureDuration(_BaseModel):
+    """Resolved value of a duration feature. ``duration_days`` ``None`` = unlimited."""
+
+    type: Literal["duration"]
+    duration_days: int | None = Field(
+        serialization_alias="durationDays", validation_alias="durationDays"
+    )
+
+
+#: The resolved type-specific value of a feature for a customer. Discriminated
+#: on ``type``.
+ResolvedFeatureValue = Annotated[
+    ResolvedFeatureBoolean
+    | ResolvedFeatureQuantity
+    | ResolvedFeatureEnum
+    | ResolvedFeatureDuration,
+    Field(discriminator="type"),
+]
+
+
+class ResolvedFeature(_BaseModel):
+    """The resolved state of a feature for a customer, returned by
+    ``GET /v1/features/resolve``. Combines the catalog feature, the resolved
+    value, and the subscriptions that contributed it.
+    """
+
+    feature: Feature
+    value: ResolvedFeatureValue
+    contributing_subscription_ids: list[str] = Field(
+        serialization_alias="contributingSubscriptionIds",
+        validation_alias="contributingSubscriptionIds",
+    )
+
+
+class ListFeaturesResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/features``."""
+
+    data: list[Feature]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/features``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    type: FeatureType | None = None
+    active: bool | None = None
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/features/{id}``."""
+
+    fields: str | None = None
+
+
+class ResolveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/features/resolve``."""
+
+    contact_id: str = Field(serialization_alias="contactId", validation_alias="contactId")
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/features``."""
+
+    key: str
+    name: str
+    type: FeatureType
+    description: str | None = None
+    enum_values: list[str] | None = Field(
+        default=None, serialization_alias="enumValues", validation_alias="enumValues"
+    )
+    metadata: dict[str, str] | None = None
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/features/{id}``.
+
+    Only fields you set are sent. ``description`` and ``metadata`` accept an
+    explicit ``None`` to clear the value server-side. ``key`` and ``type`` are
+    immutable.
+    """
+
+    name: str | None = None
+    description: str | None = None
+    enum_values: list[str] | None = Field(
+        default=None, serialization_alias="enumValues", validation_alias="enumValues"
+    )
+    metadata: dict[str, str] | None = None

threecommon-0.7.0/src/threecommon/prices/__init__.py

@@ -0,0 +1,46 @@
+"""Prices resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.prices][threecommon.ThreeCommon] /
+[AsyncThreeCommon.prices][threecommon.AsyncThreeCommon]; importing the service
+classes directly is supported for advanced wiring.
+"""
+
+from threecommon.prices.service import AsyncPricesService, PricesService
+from threecommon.prices.types import (
+    CreateBody,
+    ListParams,
+    ListPricesResponse,
+    Price,
+    PriceCurrency,
+    PriceFeature,
+    PriceFeatureBoolean,
+    PriceFeatureDuration,
+    PriceFeatureEnum,
+    PriceFeatureQuantity,
+    PriceInterval,
+    PriceRecurring,
+    PriceType,
+    RetrieveParams,
+    UpdateBody,
+)
+
+__all__ = (
+    "AsyncPricesService",
+    "CreateBody",
+    "ListParams",
+    "ListPricesResponse",
+    "Price",
+    "PriceCurrency",
+    "PriceFeature",
+    "PriceFeatureBoolean",
+    "PriceFeatureDuration",
+    "PriceFeatureEnum",
+    "PriceFeatureQuantity",
+    "PriceInterval",
+    "PriceRecurring",
+    "PriceType",
+    "PricesService",
+    "RetrieveParams",
+    "UpdateBody",
+)

threecommon-0.7.0/src/threecommon/prices/service.py

@@ -0,0 +1,227 @@
+"""Sync and async prices 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.errors.classes import ValidationError
+from threecommon.pagination import AsyncIter, Iter
+from threecommon.prices.types import (
+    CreateBody,
+    ListParams,
+    ListPricesResponse,
+    Price,
+    RetrieveParams,
+    UpdateBody,
+)
+
+if TYPE_CHECKING:
+    from threecommon._core.http_client import AsyncHTTPClient, HTTPClient
+
+
+def _qval(value: object) -> str:
+    # The wire (and every other SDK) renders query booleans lowercase.
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+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: _qval(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 _require_id(method: str, price_id: str) -> None:
+    if not price_id:
+        msg = f"prices.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(price_id: str) -> str:
+    return f"/prices/{quote(price_id, safe='')}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class PricesService:
+    """Sync prices service — bound as ``client.prices`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListPricesResponse:
+        """List the host's prices (one page).
+
+        For full iteration use [list_auto_paginate][PricesService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/prices", query=_encode_list_params(params))
+        )
+        return ListPricesResponse.model_validate(body)
+
+    def retrieve(self, price_id: str, params: RetrieveParams | None = None) -> Price:
+        """Retrieve a single price by id."""
+        _require_id("retrieve", price_id)
+        body = self._http.request(
+            Request(method="GET", path=_path_for(price_id), query=_encode_retrieve_params(params))
+        )
+        return Price.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Price:
+        """Create a price for a product."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="prices.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = self._http.request(Request(method="POST", path="/prices", body=payload))
+        return Price.model_validate(response["data"])
+
+    def update(self, price_id: str, body: UpdateBody) -> Price:
+        """Apply a partial update to a price. Set a field to ``None`` to clear it."""
+        _require_id("update", price_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="prices.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = self._http.request(
+            Request(method="PATCH", path=_path_for(price_id), body=payload)
+        )
+        return Price.model_validate(response["data"])
+
+    def archive(self, price_id: str) -> Price:
+        """Soft-archive a price. Idempotent."""
+        _require_id("archive", price_id)
+        response = self._http.request(
+            Request(method="POST", path=f"{_path_for(price_id)}/archive", body={})
+        )
+        return Price.model_validate(response["data"])
+
+    def unarchive(self, price_id: str) -> Price:
+        """Reactivate a previously archived price. Idempotent."""
+        _require_id("unarchive", price_id)
+        response = self._http.request(
+            Request(method="POST", path=f"{_path_for(price_id)}/unarchive", body={})
+        )
+        return Price.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Price]:
+        """Iterate every price 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[Price], 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="/prices", query=_encode_list_params(page_params))
+            )
+            response = ListPricesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncPricesService:
+    """Async prices service — bound as ``client.prices`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListPricesResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/prices", query=_encode_list_params(params))
+        )
+        return ListPricesResponse.model_validate(body)
+
+    async def retrieve(self, price_id: str, params: RetrieveParams | None = None) -> Price:
+        _require_id("retrieve", price_id)
+        body = await self._http.request(
+            Request(method="GET", path=_path_for(price_id), query=_encode_retrieve_params(params))
+        )
+        return Price.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Price:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="prices.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = await self._http.request(Request(method="POST", path="/prices", body=payload))
+        return Price.model_validate(response["data"])
+
+    async def update(self, price_id: str, body: UpdateBody) -> Price:
+        _require_id("update", price_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="prices.update: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_unset=True)
+        response = await self._http.request(
+            Request(method="PATCH", path=_path_for(price_id), body=payload)
+        )
+        return Price.model_validate(response["data"])
+
+    async def archive(self, price_id: str) -> Price:
+        _require_id("archive", price_id)
+        response = await self._http.request(
+            Request(method="POST", path=f"{_path_for(price_id)}/archive", body={})
+        )
+        return Price.model_validate(response["data"])
+
+    async def unarchive(self, price_id: str) -> Price:
+        _require_id("unarchive", price_id)
+        response = await self._http.request(
+            Request(method="POST", path=f"{_path_for(price_id)}/unarchive", body={})
+        )
+        return Price.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Price]:
+        """Async iterate every price 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[Price], 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="/prices", query=_encode_list_params(page_params))
+            )
+            response = ListPricesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.7.0/src/threecommon/prices/types.py

@@ -0,0 +1,186 @@
+"""Public types for the prices 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 Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Price cadence.
+#:
+#: * ``recurring`` — billed on a fixed cadence (subscription-backed).
+#: * ``one_time`` — single charge, typically an add-on / top-up pack.
+PriceType = Literal["recurring", "one_time"]
+
+#: Settlement currency of a price.
+PriceCurrency = Literal["USD", "CAD"]
+
+#: Cadence unit of a recurring price.
+PriceInterval = Literal["day", "week", "month", "year"]
+
+
+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 PriceRecurring(_BaseModel):
+    """Recurring cadence descriptor, present when ``type`` is ``recurring``."""
+
+    interval: PriceInterval
+    interval_count: int = Field(
+        serialization_alias="intervalCount", validation_alias="intervalCount"
+    )
+
+
+class PriceFeatureBoolean(_BaseModel):
+    """A boolean feature grant — the feature is on or off."""
+
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    type: Literal["boolean"]
+    enabled: bool
+
+
+class PriceFeatureQuantity(_BaseModel):
+    """A metered feature grant. ``quantity`` ``None`` means unlimited."""
+
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    type: Literal["quantity"]
+    quantity: int | None
+    rollover_enabled: bool = Field(
+        serialization_alias="rolloverEnabled", validation_alias="rolloverEnabled"
+    )
+    rollover_cap: int | None = Field(
+        default=None, serialization_alias="rolloverCap", validation_alias="rolloverCap"
+    )
+    expire_on_cancel: bool | None = Field(
+        default=None, serialization_alias="expireOnCancel", validation_alias="expireOnCancel"
+    )
+
+
+class PriceFeatureEnum(_BaseModel):
+    """An enum feature grant — selects one named value."""
+
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    type: Literal["enum"]
+    enum_value: str = Field(serialization_alias="enumValue", validation_alias="enumValue")
+
+
+class PriceFeatureDuration(_BaseModel):
+    """A duration feature grant. ``duration_days`` ``None`` means unlimited."""
+
+    feature_key: str = Field(serialization_alias="featureKey", validation_alias="featureKey")
+    type: Literal["duration"]
+    duration_days: int | None = Field(
+        serialization_alias="durationDays", validation_alias="durationDays"
+    )
+
+
+#: One typed feature grant on a price. Discriminated on ``type``.
+PriceFeature = Annotated[
+    PriceFeatureBoolean | PriceFeatureQuantity | PriceFeatureEnum | PriceFeatureDuration,
+    Field(discriminator="type"),
+]
+
+
+class Price(_BaseModel):
+    """One price 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"
+    )
+    product_id: str | None = Field(
+        default=None, serialization_alias="productId", validation_alias="productId"
+    )
+    type: PriceType | None = None
+    currency: PriceCurrency | None = None
+    unit_amount: int | None = Field(
+        default=None, serialization_alias="unitAmount", validation_alias="unitAmount"
+    )
+    recurring: PriceRecurring | None = None
+    features: list[PriceFeature] | None = None
+    nickname: str | None = None
+    active: bool | None = None
+    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 ListPricesResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/prices``."""
+
+    data: list[Price]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/prices``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    product_id: str | None = Field(
+        default=None, serialization_alias="productId", validation_alias="productId"
+    )
+    type: PriceType | None = None
+    active: bool | None = None
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/prices/{id}``."""
+
+    fields: str | None = None
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/prices``.
+
+    ``recurring`` is required when ``type`` is ``recurring`` and forbidden when
+    ``type`` is ``one_time``.
+    """
+
+    product_id: str = Field(serialization_alias="productId", validation_alias="productId")
+    type: PriceType
+    currency: PriceCurrency
+    unit_amount: int = Field(serialization_alias="unitAmount", validation_alias="unitAmount")
+    recurring: PriceRecurring | None = None
+    features: list[PriceFeature] | None = None
+    nickname: str | None = None
+    metadata: dict[str, str] | None = None
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/prices/{id}``.
+
+    Only fields you set are sent. ``features``, ``nickname``, and ``metadata``
+    accept an explicit ``None`` to clear the value server-side.
+    """
+
+    unit_amount: int | None = Field(
+        default=None, serialization_alias="unitAmount", validation_alias="unitAmount"
+    )
+    recurring: PriceRecurring | None = None
+    features: list[PriceFeature] | None = None
+    nickname: str | None = None
+    metadata: dict[str, str] | None = None