threecommon 0.1.0__py3-none-any.whl

threecommon/events/service.py

@@ -0,0 +1,170 @@
+"""Sync and async events 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.events.types import (
+    Event,
+    ListEventsResponse,
+    ListParams,
+    RetrieveParams,
+    UpdateBody,
+)
+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 _require_id(method: str, event_id: str) -> None:
+    if not event_id:
+        msg = f"events.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(event_id: str) -> str:
+    return f"/events/{quote(event_id, safe='')}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class EventsService:
+    """Sync events service — bound as ``client.events`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListEventsResponse:
+        """List the authenticated host's events (one page).
+
+        For full iteration use [list_auto_paginate][EventsService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/events", query=_encode_list_params(params))
+        )
+        return ListEventsResponse.model_validate(body)
+
+    def retrieve(self, event_id: str, params: RetrieveParams | None = None) -> Event:
+        """Retrieve a single event by ID."""
+        _require_id("retrieve", event_id)
+        body = self._http.request(
+            Request(method="GET", path=_path_for(event_id), query=_encode_retrieve_params(params))
+        )
+        return Event.model_validate(body["data"])
+
+    def update(self, event_id: str, body: UpdateBody) -> Event:
+        """Update an event's basic fields. Only fields you provide change."""
+        _require_id("update", event_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="events.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(event_id), body=payload)
+        )
+        return Event.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Event]:
+        """Iterate every event 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[Event], 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="/events", query=_encode_list_params(page_params))
+            )
+            response = ListEventsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncEventsService:
+    """Async events service — bound as ``client.events`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListEventsResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/events", query=_encode_list_params(params))
+        )
+        return ListEventsResponse.model_validate(body)
+
+    async def retrieve(self, event_id: str, params: RetrieveParams | None = None) -> Event:
+        _require_id("retrieve", event_id)
+        body = await self._http.request(
+            Request(method="GET", path=_path_for(event_id), query=_encode_retrieve_params(params))
+        )
+        return Event.model_validate(body["data"])
+
+    async def update(self, event_id: str, body: UpdateBody) -> Event:
+        _require_id("update", event_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="events.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(event_id), body=payload)
+        )
+        return Event.model_validate(response["data"])
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Event]:
+        """Async iterate every event 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[Event], 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="/events", query=_encode_list_params(page_params))
+            )
+            response = ListEventsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon/events/types.py

@@ -0,0 +1,124 @@
+"""Public types for the events resource.
+
+Hand-curated friendly aliases over the auto-generated OpenAPI types in
+[threecommon._generated][]. Field names match the Python convention
+(snake_case in the SDK; the wire payload preserves camelCase via Pydantic
+field aliases).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+#: Lifecycle status of an event. Surface-mirrors the API enum; future
+#: server-side additions will arrive as raw strings until the SDK is updated.
+EventStatus = Literal[
+    "draft",
+    "open",
+    "closed",
+    "unpublished",
+    "cancelled",
+    "postponed",
+    "schedule",
+]
+
+
+class _BaseModel(BaseModel):
+    """Base class with our default ``ConfigDict``.
+
+    ``populate_by_name=True`` lets customers construct via either snake_case
+    or camelCase. ``extra="ignore"`` keeps the SDK forward-compatible: new
+    server-side fields don't break older SDKs.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="ignore",
+        str_strip_whitespace=False,
+    )
+
+
+class Event(_BaseModel):
+    """One event 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
+    name: str | None = None
+    type: str | None = None
+    schedule: str | None = None
+    start: str | None = None  # ISO 8601
+    status: EventStatus | None = None
+    items_sold: int | None = Field(
+        default=None, serialization_alias="itemsSold", validation_alias="itemsSold"
+    )
+    revenue_cents: int | None = Field(
+        default=None, serialization_alias="revenueCents", validation_alias="revenueCents"
+    )
+    min_price_cents: int | None = Field(
+        default=None, serialization_alias="minPriceCents", validation_alias="minPriceCents"
+    )
+    max_price_cents: int | None = Field(
+        default=None, serialization_alias="maxPriceCents", validation_alias="maxPriceCents"
+    )
+    currency: str | None = None
+    is_public: bool | None = Field(
+        default=None, serialization_alias="isPublic", validation_alias="isPublic"
+    )
+    is_virtual: bool | None = Field(
+        default=None, serialization_alias="isVirtual", validation_alias="isVirtual"
+    )
+
+
+class ListEventsResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/events``."""
+
+    data: list[Event]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/events``.
+
+    All fields are optional; pass only what you need.
+    """
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    status: EventStatus | None = None
+    search: str | None = None
+    start_before: str | None = Field(
+        default=None, serialization_alias="startBefore", validation_alias="startBefore"
+    )
+    start_after: str | None = Field(
+        default=None, serialization_alias="startAfter", validation_alias="startAfter"
+    )
+    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"
+    )
+    filters: str | None = None
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/events/{id}``."""
+
+    fields: str | None = None
+
+
+class UpdateBody(_BaseModel):
+    """Body shape accepted by ``PATCH /v1/events/{id}``.
+
+    Only fields you provide are changed.
+    """
+
+    name: str | None = None

threecommon/filters/__init__.py

@@ -0,0 +1,51 @@
+"""Typed builder + wire types for the API's ``filters`` query parameter.
+
+Every endpoint that accepts ``filters`` consumes this same shape, so the
+builder lives in a shared package rather than per-resource. Build filters
+with :func:`field`, combine groups with :func:`and_` / :func:`or_` /
+:func:`combine`, and serialize before passing as the ``filters`` query
+argument:
+
+    from threecommon import filters
+
+    f = filters.and_(
+        filters.field("status").is_any_of(["open"]),
+        filters.field("ticket_sum").is_greater_than(10),
+    )
+    client.events.list(filters=f.serialize())
+
+"""
+
+from threecommon.filters.builder import (
+    CombinedFilters,
+    FieldRef,
+    SerializableFilter,
+    and_,
+    combine,
+    field,
+    or_,
+)
+from threecommon.filters.types import (
+    FilterCondition,
+    FilterGroup,
+    FilterLogic,
+    FilterOperator,
+    FilterRange,
+    FilterValue,
+)
+
+__all__ = (
+    "CombinedFilters",
+    "FieldRef",
+    "FilterCondition",
+    "FilterGroup",
+    "FilterLogic",
+    "FilterOperator",
+    "FilterRange",
+    "FilterValue",
+    "SerializableFilter",
+    "and_",
+    "combine",
+    "field",
+    "or_",
+)

threecommon/filters/builder.py

@@ -0,0 +1,188 @@
+"""Typed filter builder. Produces JSON payloads for the API's ``filters`` arg."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from dataclasses import asdict
+from typing import Any
+
+from threecommon.filters.types import (
+    FilterCondition,
+    FilterGroup,
+    FilterRange,
+    FilterValue,
+)
+
+
+class FieldRef:
+    """Reference to a single field. Operator methods produce a [FilterCondition]."""
+
+    __slots__ = ("_name",)
+
+    def __init__(self, name: str) -> None:
+        if not name:
+            msg = "filters.field: name must be a non-empty string"
+            raise ValueError(msg)
+        self._name = name
+
+    # Existence
+    def is_empty(self) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_empty")
+
+    def is_not_empty(self) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_not_empty")
+
+    # Equality
+    def is_equal_to(self, value: str | int | float | bool) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_equal_to", value=value)
+
+    def is_not_equal_to(self, value: str | int | float | bool) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_not_equal_to", value=value)
+
+    # Set membership
+    def is_equal_to_any_of(self, values: Iterable[str | int | float]) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_equal_to_any_of", value=list(values))
+
+    def is_not_equal_to_any_of(self, values: Iterable[str | int | float]) -> FilterCondition:
+        return FilterCondition(
+            field=self._name, operator="is_not_equal_to_any_of", value=list(values)
+        )
+
+    def is_any_of(self, values: Iterable[str | int | float]) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_any_of", value=list(values))
+
+    def is_none_of(self, values: Iterable[str | int | float]) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_none_of", value=list(values))
+
+    # Substring
+    def contains(self, value: str) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="contains", value=value)
+
+    def contains_exactly(self, value: str) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="contains_exactly", value=value)
+
+    # Date
+    def is_before(self, value: str) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_before", value=value)
+
+    def is_after(self, value: str) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_after", value=value)
+
+    # Numeric
+    def is_greater_than(self, value: int | float) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_greater_than", value=value)
+
+    def is_greater_than_or_equal_to(self, value: int | float) -> FilterCondition:
+        return FilterCondition(
+            field=self._name, operator="is_greater_than_or_equal_to", value=value
+        )
+
+    def is_less_than(self, value: int | float) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_less_than", value=value)
+
+    def is_less_than_or_equal_to(self, value: int | float) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_less_than_or_equal_to", value=value)
+
+    # Range
+    def is_between(self, value: FilterRange) -> FilterCondition:
+        return FilterCondition(field=self._name, operator="is_between", value=value)
+
+
+def field(name: str) -> FieldRef:
+    """Reference a field by name. See [FieldRef] for available operators."""
+    return FieldRef(name)
+
+
+class SerializableFilter:
+    """A [FilterGroup] augmented with JSON-string convenience methods.
+
+    Returned by :func:`and_` / :func:`or_`. Can be nested inside another
+    group because it exposes the underlying [group][SerializableFilter.group].
+    """
+
+    __slots__ = ("group",)
+
+    def __init__(self, group: FilterGroup) -> None:
+        self.group = group
+
+    def to_filters(self) -> list[FilterGroup]:
+        """Return ``[group]`` — the wire-format expects an array of groups."""
+        return [self.group]
+
+    def serialize(self) -> str:
+        """JSON-string form, ready to assign to the ``filters`` query param."""
+        return json.dumps([_dump(self.group)], separators=(",", ":"))
+
+
+class CombinedFilters:
+    """Multiple top-level groups joined implicitly with AND.
+
+    Most callers want :func:`and_` / :func:`or_` instead — use :func:`combine`
+    only when you specifically need an array of independent groups.
+    """
+
+    __slots__ = ("groups",)
+
+    def __init__(self, groups: list[FilterGroup]) -> None:
+        if not groups:
+            msg = "filters.combine: at least one group is required"
+            raise ValueError(msg)
+        self.groups = groups
+
+    def to_filters(self) -> list[FilterGroup]:
+        return list(self.groups)
+
+    def serialize(self) -> str:
+        return json.dumps([_dump(g) for g in self.groups], separators=(",", ":"))
+
+
+def and_(*items: FilterCondition | FilterGroup | SerializableFilter) -> SerializableFilter:
+    """Combine items with AND. At least one is required."""
+    return _make("and", items)
+
+
+def or_(*items: FilterCondition | FilterGroup | SerializableFilter) -> SerializableFilter:
+    """Combine items with OR. At least one is required."""
+    return _make("or", items)
+
+
+def combine(*groups: FilterGroup | SerializableFilter) -> CombinedFilters:
+    """Combine multiple top-level groups."""
+    flattened = [g.group if isinstance(g, SerializableFilter) else g for g in groups]
+    return CombinedFilters(flattened)
+
+
+def _make(
+    logic: str,
+    items: tuple[FilterCondition | FilterGroup | SerializableFilter, ...],
+) -> SerializableFilter:
+    if not items:
+        msg = f"filters.{logic}_: at least one condition or group is required"
+        raise ValueError(msg)
+    flattened: list[FilterCondition | FilterGroup] = []
+    for it in items:
+        if isinstance(it, SerializableFilter):
+            flattened.append(it.group)
+        else:
+            flattened.append(it)
+    return SerializableFilter(FilterGroup(logic=logic, conditions=tuple(flattened)))  # type: ignore[arg-type]
+
+
+def _dump(node: FilterCondition | FilterGroup) -> dict[str, Any]:
+    """Recursively convert a condition/group into the JSON-shape dict."""
+    if isinstance(node, FilterGroup):
+        return {
+            "logic": node.logic,
+            "conditions": [_dump(c) for c in node.conditions],
+        }
+    payload: dict[str, Any] = {"field": node.field, "operator": node.operator}
+    if node.value is not None:
+        payload["value"] = _dump_value(node.value)
+    return payload
+
+
+def _dump_value(value: FilterValue) -> Any:
+    if isinstance(value, FilterRange):
+        return asdict(value)
+    return value

threecommon/filters/types.py

@@ -0,0 +1,69 @@
+"""Wire types for the API's ``filters`` query parameter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Union
+
+#: Boolean connector for a [FilterGroup].
+FilterLogic = Literal["and", "or"]
+
+#: Full set of operators supported by the API.
+FilterOperator = Literal[
+    "is_empty",
+    "is_not_empty",
+    "is_equal_to",
+    "is_not_equal_to",
+    "is_equal_to_any_of",
+    "is_not_equal_to_any_of",
+    "is_any_of",
+    "is_none_of",
+    "contains",
+    "contains_exactly",
+    "is_before",
+    "is_after",
+    "is_greater_than",
+    "is_greater_than_or_equal_to",
+    "is_less_than",
+    "is_less_than_or_equal_to",
+    "is_between",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class FilterRange:
+    """Range envelope used by ``is_between``.
+
+    ``start`` and ``end`` must agree on type (both numeric or both ISO date strings).
+    """
+
+    start: int | float | str
+    end: int | float | str
+
+
+#: Every value the wire format accepts.
+FilterValue = Union[
+    str,
+    int,
+    float,
+    bool,
+    "list[str | int | float]",
+    FilterRange,
+]
+
+
+@dataclass(frozen=True, slots=True)
+class FilterCondition:
+    """Single ``field operator value?`` triple."""
+
+    field: str
+    operator: FilterOperator
+    value: FilterValue | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class FilterGroup:
+    """Logical group of conditions or nested groups."""
+
+    logic: FilterLogic
+    conditions: tuple[FilterCondition | FilterGroup, ...]

threecommon/helpers.py

@@ -0,0 +1,19 @@
+"""Small utility helpers exposed at the package root."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def not_none(value: T | None, name: str) -> T:
+    """Return ``value`` if non-None, else raise ``ValueError`` naming the field.
+
+    Used internally by service methods to surface a clean error when a
+    required keyword argument is the literal ``None``.
+    """
+    if value is None:
+        msg = f"{name} must not be None"
+        raise ValueError(msg)
+    return value

threecommon/invoices/__init__.py

@@ -0,0 +1,40 @@
+"""Invoices resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.invoices][threecommon.ThreeCommon] /
+[AsyncThreeCommon.invoices][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
+from threecommon.invoices.types import (
+    CreateBody,
+    Invoice,
+    InvoiceCurrency,
+    InvoiceLineItem,
+    InvoicePayment,
+    InvoiceStatus,
+    ListInvoicesResponse,
+    ListParams,
+    PaymentBody,
+    RetrieveParams,
+    UpdateBody,
+    VoidBody,
+)
+
+__all__ = (
+    "AsyncInvoicesService",
+    "CreateBody",
+    "Invoice",
+    "InvoiceCurrency",
+    "InvoiceLineItem",
+    "InvoicePayment",
+    "InvoiceStatus",
+    "InvoicesService",
+    "ListInvoicesResponse",
+    "ListParams",
+    "PaymentBody",
+    "RetrieveParams",
+    "UpdateBody",
+    "VoidBody",
+)