threecommon 0.1.0__tar.gz → 0.3.0__tar.gz

threecommon-0.3.0/CHANGELOG.md

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

{threecommon-0.1.0 → threecommon-0.3.0}/PKG-INFO

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

{threecommon-0.1.0 → threecommon-0.3.0}/src/threecommon/client.py

@@ -20,6 +20,7 @@ from threecommon._core.telemetry import Telemetry
 from threecommon.config import RetryDelay, resolve_config
 from threecommon.events.service import AsyncEventsService, EventsService
 from threecommon.invoices.service import AsyncInvoicesService, InvoicesService
+from threecommon.subscriptions.service import AsyncSubscriptionsService, SubscriptionsService
 
 if TYPE_CHECKING:  # pragma: no cover
     import logging
@@ -51,6 +52,9 @@ class ThreeCommon:
     invoices: InvoicesService
     """Invoices resource — list, retrieve, create, update, finalize, void, record_payment."""
 
+    subscriptions: SubscriptionsService
+    """Subscriptions resource — list, retrieve, create, update, activate, cancel, bill, renew."""
+
     _http: HTTPClient
     _telemetry: Telemetry
 
@@ -93,6 +97,7 @@ class ThreeCommon:
         )
         self.events = EventsService(self._http)
         self.invoices = InvoicesService(self._http)
+        self.subscriptions = SubscriptionsService(self._http)
 
     def close(self) -> None:
         """Close the underlying httpx client (no-op if you supplied your own)."""
@@ -120,6 +125,7 @@ class AsyncThreeCommon:
 
     events: AsyncEventsService
     invoices: AsyncInvoicesService
+    subscriptions: AsyncSubscriptionsService
 
     _http: AsyncHTTPClient
     _telemetry: Telemetry
@@ -163,6 +169,7 @@ class AsyncThreeCommon:
         )
         self.events = AsyncEventsService(self._http)
         self.invoices = AsyncInvoicesService(self._http)
+        self.subscriptions = AsyncSubscriptionsService(self._http)
 
     async def aclose(self) -> None:
         """Close the underlying async httpx client."""

{threecommon-0.1.0 → threecommon-0.3.0}/src/threecommon/invoices/__init__.py

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

{threecommon-0.1.0 → threecommon-0.3.0}/src/threecommon/invoices/service.py

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

{threecommon-0.1.0 → threecommon-0.3.0}/src/threecommon/invoices/types.py

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

threecommon-0.3.0/src/threecommon/subscriptions/__init__.py

@@ -0,0 +1,57 @@
+"""Subscriptions resource — sync and async clients plus public types.
+
+Most callers reach this module through
+[ThreeCommon.subscriptions][threecommon.ThreeCommon] /
+[AsyncThreeCommon.subscriptions][threecommon.AsyncThreeCommon]; importing the
+service classes directly is supported for advanced wiring.
+"""
+
+from threecommon.subscriptions.service import (
+    AsyncSubscriptionsService,
+    SubscriptionsService,
+)
+from threecommon.subscriptions.types import (
+    BillSubscriptionResult,
+    CancelBody,
+    CancelImmediatelyBody,
+    CreateBody,
+    CreateBodyItem,
+    ListParams,
+    ListSubscriptionsResponse,
+    RenewSubscriptionResult,
+    RetrieveParams,
+    Subscription,
+    SubscriptionInvoicePreview,
+    SubscriptionInvoicePreviewLineItem,
+    SubscriptionInvoiceRef,
+    SubscriptionItem,
+    SubscriptionProration,
+    SubscriptionStatus,
+    SubscriptionTaxId,
+    UpdateBody,
+    UpdateSubscriptionResult,
+)
+
+__all__ = (
+    "AsyncSubscriptionsService",
+    "BillSubscriptionResult",
+    "CancelBody",
+    "CancelImmediatelyBody",
+    "CreateBody",
+    "CreateBodyItem",
+    "ListParams",
+    "ListSubscriptionsResponse",
+    "RenewSubscriptionResult",
+    "RetrieveParams",
+    "Subscription",
+    "SubscriptionInvoicePreview",
+    "SubscriptionInvoicePreviewLineItem",
+    "SubscriptionInvoiceRef",
+    "SubscriptionItem",
+    "SubscriptionProration",
+    "SubscriptionStatus",
+    "SubscriptionTaxId",
+    "SubscriptionsService",
+    "UpdateBody",
+    "UpdateSubscriptionResult",
+)

threecommon-0.3.0/src/threecommon/subscriptions/service.py

@@ -0,0 +1,376 @@
+"""Sync and async subscriptions 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, Any
+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.subscriptions.types import (
+    BillSubscriptionResult,
+    CancelBody,
+    CancelImmediatelyBody,
+    CreateBody,
+    ListParams,
+    ListSubscriptionsResponse,
+    RenewSubscriptionResult,
+    RetrieveParams,
+    Subscription,
+    SubscriptionInvoicePreview,
+    UpdateBody,
+    UpdateSubscriptionResult,
+)
+
+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, subscription_id: str) -> None:
+    if not subscription_id:
+        msg = f"subscriptions.{method}: id must be a non-empty string"
+        raise ValidationError(code="missing_id", message=msg)
+
+
+def _path_for(subscription_id: str) -> str:
+    return f"/subscriptions/{quote(subscription_id, safe='')}"
+
+
+def _action_path(subscription_id: str, action: str) -> str:
+    return f"{_path_for(subscription_id)}/{action}"
+
+
+def _build_update_result(response: dict[str, Any]) -> UpdateSubscriptionResult:
+    payload: dict[str, Any] = {
+        "subscription": response["data"],
+        "proration": response["proration"],
+    }
+    if response.get("invoice") is not None:
+        payload["invoice"] = response["invoice"]
+    return UpdateSubscriptionResult.model_validate(payload)
+
+
+def _build_bill_result(response: dict[str, Any]) -> BillSubscriptionResult:
+    return BillSubscriptionResult.model_validate(
+        {"subscription": response["data"], "invoice": response["invoice"]}
+    )
+
+
+def _build_renew_result(response: dict[str, Any]) -> RenewSubscriptionResult:
+    payload: dict[str, Any] = {"subscription": response["data"]}
+    if response.get("invoice") is not None:
+        payload["invoice"] = response["invoice"]
+    return RenewSubscriptionResult.model_validate(payload)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Sync
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class SubscriptionsService:
+    """Sync subscriptions service — bound as ``client.subscriptions`` on [ThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, params: ListParams | None = None) -> ListSubscriptionsResponse:
+        """List the host's subscriptions (one page).
+
+        For full iteration use
+        [list_auto_paginate][SubscriptionsService.list_auto_paginate].
+        """
+        body = self._http.request(
+            Request(method="GET", path="/subscriptions", query=_encode_list_params(params))
+        )
+        return ListSubscriptionsResponse.model_validate(body)
+
+    def retrieve(self, subscription_id: str, params: RetrieveParams | None = None) -> Subscription:
+        """Retrieve a single subscription by id."""
+        _require_id("retrieve", subscription_id)
+        body = self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(subscription_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Subscription.model_validate(body["data"])
+
+    def create(self, body: CreateBody) -> Subscription:
+        """Create a new subscription against an active recurring Price."""
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.create: body must be non-None"
+            )
+        payload = body.model_dump(by_alias=True, exclude_none=True)
+        response = self._http.request(Request(method="POST", path="/subscriptions", body=payload))
+        return Subscription.model_validate(response["data"])
+
+    def update(self, subscription_id: str, body: UpdateBody) -> UpdateSubscriptionResult:
+        """Apply a mid-cycle price/quantity change with Stripe-style daily proration."""
+        _require_id("update", subscription_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.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(subscription_id), body=payload)
+        )
+        return _build_update_result(response)
+
+    def activate(self, subscription_id: str) -> Subscription:
+        """Transition an incomplete or trialing subscription to ``active``."""
+        _require_id("activate", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "activate"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    def cancel(self, subscription_id: str, body: CancelBody | None = None) -> Subscription:
+        """Schedule cancellation at the end of the current period. Idempotent."""
+        _require_id("cancel", subscription_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(subscription_id, "cancel"), body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    def cancel_immediately(
+        self, subscription_id: str, body: CancelImmediatelyBody | None = None
+    ) -> Subscription:
+        """Admin override — terminate the subscription immediately."""
+        _require_id("cancel_immediately", subscription_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(subscription_id, "cancel-immediately"),
+                body=payload,
+            )
+        )
+        return Subscription.model_validate(response["data"])
+
+    def mark_unpaid(self, subscription_id: str) -> Subscription:
+        """Admin override — mark a subscription ``unpaid`` (terminal)."""
+        _require_id("mark_unpaid", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "mark-unpaid"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    def bill(self, subscription_id: str) -> BillSubscriptionResult:
+        """Generate a draft invoice for the current period without advancing it."""
+        _require_id("bill", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "bill"), body={})
+        )
+        return _build_bill_result(response)
+
+    def renew(self, subscription_id: str) -> RenewSubscriptionResult:
+        """Advance the subscription to its next billing period and generate an invoice."""
+        _require_id("renew", subscription_id)
+        response = self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "renew"), body={})
+        )
+        return _build_renew_result(response)
+
+    def preview_upcoming_invoice(self, subscription_id: str) -> SubscriptionInvoicePreview | None:
+        """Preview the invoice the next renewal will generate.
+
+        Returns ``None`` when the subscription is set to cancel at period end.
+        """
+        _require_id("preview_upcoming_invoice", subscription_id)
+        response = self._http.request(
+            Request(method="GET", path=_action_path(subscription_id, "upcoming"))
+        )
+        invoice = response["data"].get("invoice")
+        if invoice is None:
+            return None
+        return SubscriptionInvoicePreview.model_validate(invoice)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> Iter[Subscription]:
+        """Iterate every subscription 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[Subscription], 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="/subscriptions",
+                    query=_encode_list_params(page_params),
+                )
+            )
+            response = ListSubscriptionsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return Iter(fetch_page=fetch, start_page=start_page)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Async
+# ────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncSubscriptionsService:
+    """Async subscriptions service — bound as ``client.subscriptions`` on [AsyncThreeCommon]."""
+
+    __slots__ = ("_http",)
+
+    def __init__(self, http: AsyncHTTPClient) -> None:
+        self._http = http
+
+    async def list(self, params: ListParams | None = None) -> ListSubscriptionsResponse:
+        body = await self._http.request(
+            Request(method="GET", path="/subscriptions", query=_encode_list_params(params))
+        )
+        return ListSubscriptionsResponse.model_validate(body)
+
+    async def retrieve(
+        self, subscription_id: str, params: RetrieveParams | None = None
+    ) -> Subscription:
+        _require_id("retrieve", subscription_id)
+        body = await self._http.request(
+            Request(
+                method="GET",
+                path=_path_for(subscription_id),
+                query=_encode_retrieve_params(params),
+            )
+        )
+        return Subscription.model_validate(body["data"])
+
+    async def create(self, body: CreateBody) -> Subscription:
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.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="/subscriptions", body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def update(self, subscription_id: str, body: UpdateBody) -> UpdateSubscriptionResult:
+        _require_id("update", subscription_id)
+        if body is None:
+            raise ValidationError(
+                code="missing_body", message="subscriptions.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(subscription_id), body=payload)
+        )
+        return _build_update_result(response)
+
+    async def activate(self, subscription_id: str) -> Subscription:
+        _require_id("activate", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "activate"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def cancel(self, subscription_id: str, body: CancelBody | None = None) -> Subscription:
+        _require_id("cancel", subscription_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(subscription_id, "cancel"), body=payload)
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def cancel_immediately(
+        self, subscription_id: str, body: CancelImmediatelyBody | None = None
+    ) -> Subscription:
+        _require_id("cancel_immediately", subscription_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(subscription_id, "cancel-immediately"),
+                body=payload,
+            )
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def mark_unpaid(self, subscription_id: str) -> Subscription:
+        _require_id("mark_unpaid", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "mark-unpaid"), body={})
+        )
+        return Subscription.model_validate(response["data"])
+
+    async def bill(self, subscription_id: str) -> BillSubscriptionResult:
+        _require_id("bill", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "bill"), body={})
+        )
+        return _build_bill_result(response)
+
+    async def renew(self, subscription_id: str) -> RenewSubscriptionResult:
+        _require_id("renew", subscription_id)
+        response = await self._http.request(
+            Request(method="POST", path=_action_path(subscription_id, "renew"), body={})
+        )
+        return _build_renew_result(response)
+
+    async def preview_upcoming_invoice(
+        self, subscription_id: str
+    ) -> SubscriptionInvoicePreview | None:
+        _require_id("preview_upcoming_invoice", subscription_id)
+        response = await self._http.request(
+            Request(method="GET", path=_action_path(subscription_id, "upcoming"))
+        )
+        invoice = response["data"].get("invoice")
+        if invoice is None:
+            return None
+        return SubscriptionInvoicePreview.model_validate(invoice)
+
+    def list_auto_paginate(self, params: ListParams | None = None) -> AsyncIter[Subscription]:
+        """Async iterate every subscription 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[Subscription], 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="/subscriptions",
+                    query=_encode_list_params(page_params),
+                )
+            )
+            response = ListSubscriptionsResponse.model_validate(body)
+            return response.data, response.has_more
+
+        return AsyncIter(fetch_page=fetch, start_page=start_page)

threecommon-0.3.0/src/threecommon/subscriptions/types.py

@@ -0,0 +1,359 @@
+"""Public types for the subscriptions 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 a subscription. Future server-side values will arrive
+#: as raw strings until the SDK is updated.
+SubscriptionStatus = Literal[
+    "incomplete",
+    "trialing",
+    "active",
+    "past_due",
+    "canceled",
+    "unpaid",
+]
+
+
+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 SubscriptionItem(_BaseModel):
+    """One billed item on a subscription."""
+
+    id: str
+    price_id: str = Field(serialization_alias="priceId", validation_alias="priceId")
+    quantity: int
+
+
+class SubscriptionTaxId(_BaseModel):
+    """Host tax-ID snapshot carried onto each renewal invoice."""
+
+    type: str
+    value: str
+
+
+class Subscription(_BaseModel):
+    """One subscription 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"
+    )
+    customer_email: str | None = Field(
+        default=None, serialization_alias="customerEmail", validation_alias="customerEmail"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    items: list[SubscriptionItem] | None = None
+    status: SubscriptionStatus | None = None
+    current_period_start: str | None = Field(
+        default=None,
+        serialization_alias="currentPeriodStart",
+        validation_alias="currentPeriodStart",
+    )
+    current_period_end: str | None = Field(
+        default=None,
+        serialization_alias="currentPeriodEnd",
+        validation_alias="currentPeriodEnd",
+    )
+    trial_start: str | None = Field(
+        default=None, serialization_alias="trialStart", validation_alias="trialStart"
+    )
+    trial_end: str | None = Field(
+        default=None, serialization_alias="trialEnd", validation_alias="trialEnd"
+    )
+    billing_cycle_anchor: str | None = Field(
+        default=None,
+        serialization_alias="billingCycleAnchor",
+        validation_alias="billingCycleAnchor",
+    )
+    cancel_at: str | None = Field(
+        default=None, serialization_alias="cancelAt", validation_alias="cancelAt"
+    )
+    cancel_at_period_end: bool | None = Field(
+        default=None,
+        serialization_alias="cancelAtPeriodEnd",
+        validation_alias="cancelAtPeriodEnd",
+    )
+    canceled_at: str | None = Field(
+        default=None, serialization_alias="canceledAt", validation_alias="canceledAt"
+    )
+    cancel_reason: str | None = Field(
+        default=None, serialization_alias="cancelReason", validation_alias="cancelReason"
+    )
+    ended_at: str | None = Field(
+        default=None, serialization_alias="endedAt", validation_alias="endedAt"
+    )
+    started_at: str | None = Field(
+        default=None, serialization_alias="startedAt", validation_alias="startedAt"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    first_failure_at: str | None = Field(
+        default=None,
+        serialization_alias="firstFailureAt",
+        validation_alias="firstFailureAt",
+    )
+    next_retry_at: str | None = Field(
+        default=None,
+        serialization_alias="nextRetryAt",
+        validation_alias="nextRetryAt",
+    )
+    retry_count: int | None = Field(
+        default=None, serialization_alias="retryCount", validation_alias="retryCount"
+    )
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    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 SubscriptionInvoiceRef(_BaseModel):
+    """Slim invoice reference returned alongside renew/bill/update responses."""
+
+    id: str
+    status: str
+    total: int
+    currency: str
+
+
+class SubscriptionProration(_BaseModel):
+    """Proration summary returned by ``PATCH /v1/subscriptions/{id}``."""
+
+    net_amount_minor: int = Field(
+        serialization_alias="netAmountMinor", validation_alias="netAmountMinor"
+    )
+    days_remaining: int = Field(
+        serialization_alias="daysRemaining", validation_alias="daysRemaining"
+    )
+    days_in_cycle: int = Field(serialization_alias="daysInCycle", validation_alias="daysInCycle")
+
+
+class SubscriptionInvoicePreviewLineItem(_BaseModel):
+    """One line item on a subscription invoice preview."""
+
+    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"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+
+
+class SubscriptionInvoicePreview(_BaseModel):
+    """Non-persisted projection of the invoice the next renewal will generate."""
+
+    customer_id: str = Field(serialization_alias="customerId", validation_alias="customerId")
+    subscription_id: str = Field(
+        serialization_alias="subscriptionId", validation_alias="subscriptionId"
+    )
+    currency: str
+    line_items: list[SubscriptionInvoicePreviewLineItem] = Field(
+        serialization_alias="lineItems", validation_alias="lineItems"
+    )
+    subtotal: int
+    total: int
+    period_start: str = Field(serialization_alias="periodStart", validation_alias="periodStart")
+    period_end: str = Field(serialization_alias="periodEnd", validation_alias="periodEnd")
+
+
+class ListSubscriptionsResponse(_BaseModel):
+    """Successful response shape from ``GET /v1/subscriptions``."""
+
+    data: list[Subscription]
+    has_more: bool = Field(serialization_alias="hasMore", validation_alias="hasMore")
+
+
+class UpdateSubscriptionResult(_BaseModel):
+    """Successful response shape from ``PATCH /v1/subscriptions/{id}``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef | None = None
+    proration: SubscriptionProration
+
+
+class BillSubscriptionResult(_BaseModel):
+    """Successful response shape from ``POST /v1/subscriptions/{id}/bill``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef
+
+
+class RenewSubscriptionResult(_BaseModel):
+    """Successful response shape from ``POST /v1/subscriptions/{id}/renew``."""
+
+    subscription: Subscription
+    invoice: SubscriptionInvoiceRef | None = None
+
+
+class ListParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/subscriptions``."""
+
+    page: int | None = None
+    page_size: int | None = Field(
+        default=None, serialization_alias="pageSize", validation_alias="pageSize"
+    )
+    status: SubscriptionStatus | None = None
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    fields: str | None = None
+
+
+class RetrieveParams(_BaseModel):
+    """Query parameters accepted by ``GET /v1/subscriptions/{id}``."""
+
+    fields: str | None = None
+
+
+class CreateBodyItem(_BaseModel):
+    """One item on a multi-item subscription create body."""
+
+    price_id: str = Field(serialization_alias="priceId", validation_alias="priceId")
+    quantity: int | None = None
+
+
+class CreateBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions``."""
+
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    items: list[CreateBodyItem] | None = None
+    contact_id: str | None = Field(
+        default=None, serialization_alias="contactId", validation_alias="contactId"
+    )
+    customer_email: str | None = Field(
+        default=None,
+        serialization_alias="customerEmail",
+        validation_alias="customerEmail",
+    )
+    trial_days: int | None = Field(
+        default=None, serialization_alias="trialDays", validation_alias="trialDays"
+    )
+    billing_cycle_anchor: str | None = Field(
+        default=None,
+        serialization_alias="billingCycleAnchor",
+        validation_alias="billingCycleAnchor",
+    )
+    cancel_at: str | None = Field(
+        default=None, serialization_alias="cancelAt", validation_alias="cancelAt"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    metadata: dict[str, str] | None = None
+
+
+class UpdateBody(_BaseModel):
+    """Body accepted by ``PATCH /v1/subscriptions/{id}``.
+
+    Only fields you provide are changed.
+    """
+
+    price_id: str | None = Field(
+        default=None, serialization_alias="priceId", validation_alias="priceId"
+    )
+    quantity: int | None = None
+    notes: str | None = None
+    tax_ids: list[SubscriptionTaxId] | None = Field(
+        default=None, serialization_alias="taxIds", validation_alias="taxIds"
+    )
+    tax_rate: float | None = Field(
+        default=None, serialization_alias="taxRate", validation_alias="taxRate"
+    )
+    auto_charge: bool | None = Field(
+        default=None, serialization_alias="autoCharge", validation_alias="autoCharge"
+    )
+    dunning_enabled: bool | None = Field(
+        default=None,
+        serialization_alias="dunningEnabled",
+        validation_alias="dunningEnabled",
+    )
+    payment_due_days: int | None = Field(
+        default=None,
+        serialization_alias="paymentDueDays",
+        validation_alias="paymentDueDays",
+    )
+
+
+class CancelBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions/{id}/cancel``."""
+
+    reason: str | None = None
+
+
+class CancelImmediatelyBody(_BaseModel):
+    """Body accepted by ``POST /v1/subscriptions/{id}/cancel-immediately``."""
+
+    reason: str | None = None

threecommon-0.1.0/CHANGELOG.md

@@ -1,16 +0,0 @@
-# Changelog
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-
-- Initial scaffolding.
-- `ThreeCommon` (sync) and `AsyncThreeCommon` (async) clients.
-- Events resource: `list`, `retrieve`, `update`, `list_auto_paginate`.
-- Invoices resource: `list`, `retrieve`, `create`, `update`, `finalize`, `void`,
-  `record_payment`, `list_auto_paginate`. Both sync and async surfaces.
-- Typed exception tree (`AuthError`, `NotFoundError`, `RateLimitError`, …).
-- Conformance harness running shared YAML scenarios against both clients.