threecommon 0.2.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.2.0 → threecommon-0.3.0}/PKG-INFO

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

{threecommon-0.2.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.2.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.2.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.2.0/CHANGELOG.md

@@ -1,29 +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]
-
-## 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.