threecommon 0.1.0__py3-none-any.whl

threecommon/invoices/service.py

@@ -0,0 +1,266 @@
+"""Sync and async invoices 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.invoices.types import (
+    CreateBody,
+    Invoice,
+    ListInvoicesResponse,
+    ListParams,
+    PaymentBody,
+    RetrieveParams,
+    UpdateBody,
+    VoidBody,
+)
+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, invoice_id: str) -> None:
+    if not invoice_id:
+        msg = f"invoices.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(invoice_id: str) -> str:
+    return f"/invoices/{quote(invoice_id, safe='')}"
+
+
+def _action_path(invoice_id: str, action: str) -> str:
+    return f"{_path_for(invoice_id)}/{action}"
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class InvoicesService:
+    """Sync invoices service — bound as ``client.invoices`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListInvoicesResponse:
+        """List the host's invoices (one page).
+
+        For full iteration use [list_auto_paginate][InvoicesService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/invoices", query=_encode_list_params(params))
+        )
+        return ListInvoicesResponse.model_validate(body)
+
+    def retrieve(self, invoice_id: str, params: RetrieveParams | None = None) -> Invoice:
+        """Retrieve a single invoice by id."""
+        _require_id("retrieve", invoice_id)
+        body = self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(invoice_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Invoice.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Invoice:
+        """Create a draft invoice. Totals are computed server-side from line items."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="invoices.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(Request(method="POST", path="/invoices", body=payload))
+        return Invoice.model_validate(response["data"])
+
+    def update(self, invoice_id: str, body: UpdateBody) -> Invoice:
+        """Revise a draft invoice. Only legal while in draft."""
+        _require_id("update", invoice_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="invoices.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(invoice_id), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    def finalize(self, invoice_id: str) -> Invoice:
+        """Finalize a draft invoice: assign a number, stamp ``issuedAt``, set status ``open``."""
+        _require_id("finalize", invoice_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "finalize"), body={})
+        )
+        return Invoice.model_validate(response["data"])
+
+    def void(self, invoice_id: str, body: VoidBody | None = None) -> Invoice:
+        """Void an invoice. Permitted from ``draft`` or ``open``; paid invoices cannot be voided."""
+        _require_id("void", invoice_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "void"), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    def record_payment(self, invoice_id: str, body: PaymentBody) -> Invoice:
+        """Record a manual payment against an open invoice.
+
+        Cumulative payments meeting the total transition the invoice to ``paid``.
+        """
+        _require_id("record_payment", invoice_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body",
+                message="invoices.record_payment: body must be non-None",
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "payments"), body=payload)
+        )
+        return Invoice.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
+
+        def fetch(page: int) -> tuple[list[Invoice], 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="/invoices", query=_encode_list_params(page_params))
+            )
+            response = ListInvoicesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncInvoicesService:
+    """Async invoices service — bound as ``client.invoices`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListInvoicesResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/invoices", query=_encode_list_params(params))
+        )
+        return ListInvoicesResponse.model_validate(body)
+
+    async def retrieve(self, invoice_id: str, params: RetrieveParams | None = None) -> Invoice:
+        _require_id("retrieve", invoice_id)
+        body = await self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(invoice_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Invoice.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Invoice:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="invoices.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="/invoices", body=payload))
+        return Invoice.model_validate(response["data"])
+
+    async def update(self, invoice_id: str, body: UpdateBody) -> Invoice:
+        _require_id("update", invoice_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="invoices.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(invoice_id), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    async def finalize(self, invoice_id: str) -> Invoice:
+        _require_id("finalize", invoice_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "finalize"), body={})
+        )
+        return Invoice.model_validate(response["data"])
+
+    async def void(self, invoice_id: str, body: VoidBody | None = None) -> Invoice:
+        _require_id("void", invoice_id)
+        payload = body.model_dump(by_alias=True, exclude_none=True) if body is not None else {}
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(invoice_id, "void"), body=payload)
+        )
+        return Invoice.model_validate(response["data"])
+
+    async def record_payment(self, invoice_id: str, body: PaymentBody) -> Invoice:
+        _require_id("record_payment", invoice_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body",
+                message="invoices.record_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=_action_path(invoice_id, "payments"), body=payload)
+        )
+        return Invoice.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
+        http = self._http
+
+        async def fetch(page: int) -> tuple[list[Invoice], 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="/invoices", query=_encode_list_params(page_params))
+            )
+            response = ListInvoicesResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon/invoices/types.py

@@ -0,0 +1,195 @@
+"""Public types for the invoices 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
+
+#: 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"]
+
+#: Invoice currency code; all line amounts must match.
+InvoiceCurrency = Literal["USD", "CAD"]
+
+
+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 InvoiceLineItem(_BaseModel):
+    """One line on an invoice."""
+
+    description: str
+    quantity: int
+    unit_amount: int = Field(serialization_alias="unitAmount", validation_alias="unitAmount")
+    product_id: str | None = Field(
+        default=None, serialization_alias="productId", validation_alias="productId"
+    )
+    tax_amount: int | None = Field(
+        default=None, serialization_alias="taxAmount", validation_alias="taxAmount"
+    )
+
+
+class InvoicePayment(_BaseModel):
+    """One recorded payment against an invoice."""
+
+    id: str
+    amount: int
+    paid_at: str = Field(serialization_alias="paidAt", validation_alias="paidAt")
+    idempotency_key: str | None = Field(
+        default=None, serialization_alias="idempotencyKey", validation_alias="idempotencyKey"
+    )
+    note: str | None = None
+
+
+class Invoice(_BaseModel):
+    """One invoice 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"
+    )
+    customer_id: str | None = Field(
+        default=None, serialization_alias="customerId", validation_alias="customerId"
+    )
+    number: str | None = None
+    currency: InvoiceCurrency | None = None
+    line_items: list[InvoiceLineItem] | None = Field(
+        default=None, serialization_alias="lineItems", validation_alias="lineItems"
+    )
+    payments: list[InvoicePayment] | None = None
+    subtotal: int | None = None
+    tax_total: int | None = Field(
+        default=None, serialization_alias="taxTotal", validation_alias="taxTotal"
+    )
+    total: int | None = None
+    amount_paid: int | None = Field(
+        default=None, serialization_alias="amountPaid", validation_alias="amountPaid"
+    )
+    amount_due: int | None = Field(
+        default=None, serialization_alias="amountDue", validation_alias="amountDue"
+    )
+    status: InvoiceStatus | None = None
+    notes: str | None = None
+    issued_at: str | None = Field(
+        default=None, serialization_alias="issuedAt", validation_alias="issuedAt"
+    )
+    due_at: str | None = Field(default=None, serialization_alias="dueAt", validation_alias="dueAt")
+    paid_at: str | None = Field(
+        default=None, serialization_alias="paidAt", validation_alias="paidAt"
+    )
+    voided_at: str | None = Field(
+        default=None, serialization_alias="voidedAt", validation_alias="voidedAt"
+    )
+    subscription_id: str | None = Field(
+        default=None, serialization_alias="subscriptionId", validation_alias="subscriptionId"
+    )
+    quote_id: str | None = Field(
+        default=None, serialization_alias="quoteId", validation_alias="quoteId"
+    )
+    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 ListInvoicesResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/invoices``."""
+
+    data: list[Invoice]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/invoices``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    status: InvoiceStatus | None = None
+    customer_id: str | None = Field(
+        default=None, serialization_alias="customerId", validation_alias="customerId"
+    )
+    issued_after: str | None = Field(
+        default=None, serialization_alias="issuedAfter", validation_alias="issuedAfter"
+    )
+    issued_before: str | None = Field(
+        default=None, serialization_alias="issuedBefore", validation_alias="issuedBefore"
+    )
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/invoices/{id}``."""
+
+    fields: str | None = None
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/invoices``."""
+
+    customer_id: str = Field(serialization_alias="customerId", validation_alias="customerId")
+    currency: InvoiceCurrency
+    line_items: list[InvoiceLineItem] = Field(
+        serialization_alias="lineItems", validation_alias="lineItems"
+    )
+    notes: str | None = None
+    due_at: str | None = Field(default=None, serialization_alias="dueAt", validation_alias="dueAt")
+    subscription_id: str | None = Field(
+        default=None, serialization_alias="subscriptionId", validation_alias="subscriptionId"
+    )
+    quote_id: str | None = Field(
+        default=None, serialization_alias="quoteId", validation_alias="quoteId"
+    )
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/invoices/{id}``.
+
+    Only fields you provide are changed.
+    """
+
+    customer_id: str | None = Field(
+        default=None, serialization_alias="customerId", validation_alias="customerId"
+    )
+    line_items: list[InvoiceLineItem] | None = Field(
+        default=None, serialization_alias="lineItems", validation_alias="lineItems"
+    )
+    notes: str | None = None
+    due_at: str | None = Field(default=None, serialization_alias="dueAt", validation_alias="dueAt")
+
+
+class VoidBody(_BaseModel):
+    """Body accepted by ``POST /v1/invoices/{id}/void``."""
+
+    reason: str | None = None
+
+
+class PaymentBody(_BaseModel):
+    """Body accepted by ``POST /v1/invoices/{id}/payments``."""
+
+    payment: int
+    idempotency_key: str | None = Field(
+        default=None, serialization_alias="idempotencyKey", validation_alias="idempotencyKey"
+    )
+    note: str | None = None

threecommon/pagination/__init__.py

@@ -0,0 +1,12 @@
+"""Pagination module — exports the sync and async auto-paginating iterators.
+
+User usually receive these from resource methods (e.g.
+``client.events.list_auto_paginate(...)``) rather than constructing them
+directly. Importing the submodule directly is supported::
+
+    from threecommon.pagination import Iter, AsyncIter
+"""
+
+from threecommon.pagination.auto_paginator import AsyncIter, Iter
+
+__all__ = ("AsyncIter", "Iter")

threecommon/pagination/auto_paginator.py

@@ -0,0 +1,98 @@
+"""auto-paginating iterators returned by every list endpoint.
+
+Two flavors:
+
+* [Iter][threecommon.pagination.Iter] — sync iterator. Use ``for ev in iter:``.
+* [AsyncIter][threecommon.pagination.AsyncIter] — async iterator.
+  Use ``async for ev in iter:``.
+
+Both walk pages lazily — one HTTP call per page, only when the user
+drains the previous page's buffer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+#: Synchronous page-fetch callback. Returns ``(page_items, has_more)``.
+SyncFetchPage = Callable[[int], tuple[list[T], bool]]
+
+#: Asynchronous page-fetch callback. Returns ``(page_items, has_more)``.
+AsyncFetchPage = Callable[[int], Awaitable[tuple[list[T], bool]]]
+
+
+class Iter(Generic[T]):
+    """Sync auto-paginating iterator. ``for ev in iter:`` drives the pages."""
+
+    __slots__ = ("_buffer", "_fetch_page", "_has_more", "_index", "_page")
+
+    def __init__(self, *, fetch_page: SyncFetchPage[T], start_page: int = 0) -> None:
+        self._fetch_page = fetch_page
+        self._page = start_page
+        self._buffer: list[T] = []
+        self._index = 0
+        self._has_more = True
+
+    def __iter__(self) -> Iterator[T]:
+        return self
+
+    def __next__(self) -> T:
+        if self._index < len(self._buffer):
+            value = self._buffer[self._index]
+            self._index += 1
+            return value
+        if not self._has_more:
+            raise StopIteration
+
+        data, has_more = self._fetch_page(self._page)
+        self._buffer = data
+        self._index = 0
+        self._has_more = has_more
+        self._page += 1
+
+        if not self._buffer:
+            raise StopIteration
+
+        value = self._buffer[self._index]
+        self._index += 1
+        return value
+
+
+class AsyncIter(Generic[T]):
+    """Async auto-paginating iterator. ``async for ev in iter:`` drives the pages."""
+
+    __slots__ = ("_buffer", "_fetch_page", "_has_more", "_index", "_page")
+
+    def __init__(self, *, fetch_page: AsyncFetchPage[T], start_page: int = 0) -> None:
+        self._fetch_page = fetch_page
+        self._page = start_page
+        self._buffer: list[T] = []
+        self._index = 0
+        self._has_more = True
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if self._index < len(self._buffer):
+            value = self._buffer[self._index]
+            self._index += 1
+            return value
+        if not self._has_more:
+            raise StopAsyncIteration
+
+        data, has_more = await self._fetch_page(self._page)
+        self._buffer = data
+        self._index = 0
+        self._has_more = has_more
+        self._page += 1
+
+        if not self._buffer:
+            raise StopAsyncIteration
+
+        value = self._buffer[self._index]
+        self._index += 1
+        return value

threecommon/version.py

@@ -0,0 +1,10 @@
+"""SDK package version.
+
+Replaced by the release pipeline at publish time (currently static; will
+become dynamic via hatch-vcs once the path-prefixed-tag wiring lands — see
+the comment in pyproject.toml).
+"""
+
+__version__ = "0.0.0.dev0"
+
+VERSION = __version__