commet-sdk 0.1.0__py3-none-any.whl

commet/__init__.py

@@ -0,0 +1,21 @@
+from ._exceptions import CommetAPIError, CommetError, CommetValidationError
+from ._http import ApiResponse
+from .client import Commet
+from .resources.webhooks import Webhooks
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("commet")
+except Exception:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "ApiResponse",
+    "Commet",
+    "CommetAPIError",
+    "CommetError",
+    "CommetValidationError",
+    "Webhooks",
+]

commet/_customer.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._http import ApiResponse
+    from .resources.features import FeaturesResource
+    from .resources.portal import PortalResource
+    from .resources.seats import SeatsResource
+    from .resources.subscriptions import SubscriptionsResource
+    from .resources.usage import UsageResource
+
+
+class CustomerContext:
+    """Customer-scoped API context.
+
+    All operations are automatically scoped to the customer's external_id.
+
+    Usage::
+
+        customer = commet.customer("user_123")
+
+        customer.features.get("team_members")
+        customer.seats.add("editor")
+        customer.usage.track("api_calls")
+    """
+
+    def __init__(
+        self,
+        external_id: str,
+        *,
+        features: FeaturesResource,
+        seats: SeatsResource,
+        usage: UsageResource,
+        subscriptions: SubscriptionsResource,
+        portal: PortalResource,
+    ) -> None:
+        self._external_id = external_id
+        self.features = _CustomerFeatures(external_id, features)
+        self.seats = _CustomerSeats(external_id, seats)
+        self.usage = _CustomerUsage(external_id, usage)
+        self.subscription = _CustomerSubscription(external_id, subscriptions)
+        self.portal = _CustomerPortal(external_id, portal)
+
+
+class _CustomerFeatures:
+    def __init__(self, external_id: str, resource: FeaturesResource) -> None:
+        self._external_id = external_id
+        self._resource = resource
+
+    def get(self, code: str) -> ApiResponse:
+        return self._resource.get(code=code, external_id=self._external_id)
+
+    def check(self, code: str) -> ApiResponse:
+        return self._resource.check(code=code, external_id=self._external_id)
+
+    def can_use(self, code: str) -> ApiResponse:
+        return self._resource.can_use(code=code, external_id=self._external_id)
+
+    def list(self) -> ApiResponse:
+        return self._resource.list(self._external_id)
+
+
+class _CustomerSeats:
+    def __init__(self, external_id: str, resource: SeatsResource) -> None:
+        self._external_id = external_id
+        self._resource = resource
+
+    def add(self, seat_type: str, count: int = 1) -> ApiResponse:
+        return self._resource.add(
+            seat_type=seat_type, count=count, external_id=self._external_id
+        )
+
+    def remove(self, seat_type: str, count: int = 1) -> ApiResponse:
+        return self._resource.remove(
+            seat_type=seat_type, count=count, external_id=self._external_id
+        )
+
+    def set(self, seat_type: str, count: int) -> ApiResponse:
+        return self._resource.set(
+            seat_type=seat_type, count=count, external_id=self._external_id
+        )
+
+    def get_balance(self, seat_type: str) -> ApiResponse:
+        return self._resource.get_balance(seat_type=seat_type, external_id=self._external_id)
+
+
+class _CustomerUsage:
+    def __init__(self, external_id: str, resource: UsageResource) -> None:
+        self._external_id = external_id
+        self._resource = resource
+
+    def track(
+        self,
+        feature: str,
+        value: int | None = None,
+        properties: dict[str, str] | None = None,
+    ) -> ApiResponse:
+        return self._resource.track(
+            feature=feature, external_id=self._external_id, value=value, properties=properties
+        )
+
+
+class _CustomerSubscription:
+    def __init__(self, external_id: str, resource: SubscriptionsResource) -> None:
+        self._external_id = external_id
+        self._resource = resource
+
+    def get(self) -> ApiResponse:
+        return self._resource.get(self._external_id)
+
+
+class _CustomerPortal:
+    def __init__(self, external_id: str, resource: PortalResource) -> None:
+        self._external_id = external_id
+        self._resource = resource
+
+    def get_url(self) -> ApiResponse:
+        return self._resource.get_url(external_id=self._external_id)

commet/_exceptions.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class CommetError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+        details: object = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+
+
+class CommetAPIError(CommetError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str | None = None,
+        details: object = None,
+    ) -> None:
+        super().__init__(message, code=code, status_code=status_code, details=details)
+
+
+class CommetValidationError(CommetError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        validation_errors: dict[str, list[str]],
+    ) -> None:
+        super().__init__(message)
+        self.validation_errors = validation_errors

commet/_http.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+import httpx
+
+from ._exceptions import CommetAPIError, CommetValidationError
+
+logger = logging.getLogger("commet")
+
+# -- Case conversion --
+
+_UPPER_AFTER_LOWER = re.compile(r"(.)([A-Z][a-z]+)")
+_LOWER_BEFORE_UPPER = re.compile(r"([a-z0-9])([A-Z])")
+
+_RETRYABLE_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504})
+
+_BASE_URLS = {
+    "production": "https://commet.co",
+    "sandbox": "https://sandbox.commet.co",
+}
+
+
+def _to_snake(name: str) -> str:
+    return _LOWER_BEFORE_UPPER.sub(r"\1_\2", _UPPER_AFTER_LOWER.sub(r"\1_\2", name)).lower()
+
+
+def _to_camel(name: str) -> str:
+    parts = name.split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def _convert_keys(obj: Any, fn: Any) -> Any:
+    if isinstance(obj, dict):
+        return {fn(k): _convert_keys(v, fn) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_convert_keys(i, fn) for i in obj]
+    return obj
+
+
+def build_body(**kwargs: Any) -> dict[str, Any]:
+    """Build request body, stripping None values."""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+# -- Response --
+
+
+@dataclass
+class ApiResponse:
+    success: bool
+    data: Any = None
+    code: str | None = None
+    message: str | None = None
+    has_more: bool | None = None
+    next_cursor: str | None = None
+
+
+# -- HTTP Client --
+
+
+class CommetHTTPClient:
+    def __init__(
+        self,
+        api_key: str,
+        environment: str,
+        *,
+        timeout: float = 30.0,
+        retries: int = 3,
+    ) -> None:
+        base_url = _BASE_URLS[environment]
+        self._client = httpx.Client(
+            base_url=f"{base_url}/api",
+            headers={
+                "x-api-key": api_key,
+                "Content-Type": "application/json",
+                "User-Agent": f"commet-python/{_get_version()}",
+            },
+            timeout=timeout,
+        )
+        self._max_retries = retries
+
+    def close(self) -> None:
+        self._client.close()
+
+    def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        clean = (
+            {_to_camel(k): v for k, v in params.items() if v is not None}
+            if params
+            else None
+        )
+        return self._request(
+            "GET", endpoint, params=clean, idempotency_key=idempotency_key, timeout=timeout
+        )
+
+    def post(
+        self,
+        endpoint: str,
+        body: dict[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        return self._request(
+            "POST", endpoint, body=body, idempotency_key=idempotency_key, timeout=timeout
+        )
+
+    def put(
+        self,
+        endpoint: str,
+        body: dict[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        return self._request(
+            "PUT", endpoint, body=body, idempotency_key=idempotency_key, timeout=timeout
+        )
+
+    def delete(
+        self,
+        endpoint: str,
+        body: dict[str, Any] | None = None,
+        *,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        return self._request(
+            "DELETE", endpoint, body=body, idempotency_key=idempotency_key, timeout=timeout
+        )
+
+    # -- Internals --
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> ApiResponse:
+        headers: dict[str, str] = {}
+        if method == "POST":
+            headers["Idempotency-Key"] = idempotency_key or f"sdk_{uuid4().hex}"
+
+        json_body = _convert_keys(body, _to_camel) if body else None
+
+        logger.debug("%s %s", method, endpoint)
+        if json_body:
+            logger.debug("Body: %s", json_body)
+
+        return self._execute(
+            method, endpoint, json_body=json_body, params=params, headers=headers, timeout=timeout
+        )
+
+    def _execute(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        attempt: int = 1,
+    ) -> ApiResponse:
+        try:
+            resp = self._client.request(
+                method, endpoint, json=json_body, params=params, headers=headers, timeout=timeout
+            )
+        except httpx.TimeoutException:
+            if attempt <= self._max_retries:
+                self._wait(attempt)
+                return self._execute(
+                    method, endpoint, json_body=json_body, params=params,
+                    headers=headers, timeout=timeout, attempt=attempt + 1,
+                )
+            raise
+
+        logger.debug("Response: %d", resp.status_code)
+
+        if resp.status_code in _RETRYABLE_STATUS_CODES and attempt <= self._max_retries:
+            self._wait(attempt)
+            return self._execute(
+                method, endpoint, json_body=json_body, params=params,
+                headers=headers, timeout=timeout, attempt=attempt + 1,
+            )
+
+        try:
+            data = resp.json()
+        except Exception:
+            if resp.status_code == 404:
+                return ApiResponse(success=False, code="not_found", message="Resource not found")
+            raise CommetAPIError(
+                f"Invalid JSON response: {resp.status_code}",
+                status_code=resp.status_code,
+                code="INVALID_JSON",
+            )
+
+        if resp.is_error:
+            self._handle_error(resp.status_code, data)
+
+        converted = _convert_keys(data, _to_snake)
+        return ApiResponse(
+            success=converted.get("success", True),
+            data=converted.get("data"),
+            code=converted.get("code"),
+            message=converted.get("message"),
+            has_more=converted.get("has_more"),
+            next_cursor=converted.get("next_cursor"),
+        )
+
+    def _handle_error(self, status_code: int, data: Any) -> None:
+        if not isinstance(data, dict):
+            raise CommetAPIError(
+                f"Request failed with status {status_code}", status_code=status_code
+            )
+
+        if data.get("code") == "validation_error" and isinstance(data.get("details"), list):
+            errors: dict[str, list[str]] = {}
+            for detail in data["details"]:
+                field = detail.get("field", "unknown")
+                errors.setdefault(field, []).append(detail.get("message", ""))
+            raise CommetValidationError(
+                data.get("message", "Validation failed"), validation_errors=errors
+            )
+
+        raise CommetAPIError(
+            data.get("message", f"Request failed with status {status_code}"),
+            status_code=status_code,
+            code=data.get("code"),
+            details=data.get("details"),
+        )
+
+    def _wait(self, attempt: int) -> None:
+        delay = min(1.0 * (2 ** (attempt - 1)), 8.0)
+        logger.debug("Retrying in %ss (attempt %d/%d)", delay, attempt, self._max_retries)
+        time.sleep(delay)
+
+
+def _get_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("commet")
+    except Exception:
+        return "0.1.0"

commet/client.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from ._customer import CustomerContext
+from ._http import CommetHTTPClient, _BASE_URLS
+from .resources.credit_packs import CreditPacksResource
+from .resources.customers import CustomersResource
+from .resources.features import FeaturesResource
+from .resources.plans import PlansResource
+from .resources.portal import PortalResource
+from .resources.seats import SeatsResource
+from .resources.subscriptions import SubscriptionsResource
+from .resources.usage import UsageResource
+from .resources.webhooks import Webhooks
+
+logger = logging.getLogger("commet")
+
+Environment = Literal["sandbox", "production"]
+
+
+class Commet:
+    """Commet SDK client.
+
+    Usage::
+
+        from commet import Commet
+
+        commet = Commet(api_key="ck_xxx")
+
+        # Direct resource access
+        commet.customers.create(email="user@example.com")
+        commet.usage.track(feature="api_calls", external_id="user_123")
+
+        # Customer-scoped context
+        customer = commet.customer("user_123")
+        customer.usage.track("api_calls")
+
+        # Context manager
+        with Commet(api_key="ck_xxx") as commet:
+            commet.usage.track(feature="api_calls", external_id="user_123")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        environment: Environment = "sandbox",
+        timeout: float = 30.0,
+        retries: int = 3,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Commet SDK: API key is required")
+
+        if not api_key.startswith("ck_"):
+            raise ValueError("Commet SDK: Invalid API key format. Expected format: ck_xxx...")
+
+        if environment not in _BASE_URLS:
+            raise ValueError(
+                f"Commet SDK: Invalid environment '{environment}'. Must be 'sandbox' or 'production'"
+            )
+
+        self._environment = environment
+        self._http = CommetHTTPClient(
+            api_key, environment, timeout=timeout, retries=retries
+        )
+
+        self.customers = CustomersResource(self._http)
+        self.credit_packs = CreditPacksResource(self._http)
+        self.plans = PlansResource(self._http)
+        self.usage = UsageResource(self._http)
+        self.seats = SeatsResource(self._http)
+        self.subscriptions = SubscriptionsResource(self._http)
+        self.portal = PortalResource(self._http)
+        self.features = FeaturesResource(self._http)
+        self.webhooks = Webhooks()
+
+        logger.debug("Initialized in %s mode", environment)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Commet:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def customer(self, external_id: str) -> CustomerContext:
+        """Create a customer-scoped context for cleaner API usage."""
+        return CustomerContext(
+            external_id,
+            features=self.features,
+            seats=self.seats,
+            usage=self.usage,
+            subscriptions=self.subscriptions,
+            portal=self.portal,
+        )
+
+    @property
+    def environment(self) -> str:
+        return self._environment
+
+    def is_sandbox(self) -> bool:
+        return self._environment == "sandbox"
+
+    def is_production(self) -> bool:
+        return self._environment == "production"

commet/resources/credit_packs.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient
+
+
+class CreditPacksResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def list(self) -> ApiResponse:
+        return self._http.get("/credit-packs")

commet/resources/customers.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class CustomersResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        email: str,
+        external_id: str | None = None,
+        full_name: str | None = None,
+        domain: str | None = None,
+        website: str | None = None,
+        timezone: str | None = None,
+        language: str | None = None,
+        industry: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        address: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.post(
+            "/customers",
+            build_body(
+                billing_email=email,
+                external_id=external_id,
+                full_name=full_name,
+                domain=domain,
+                website=website,
+                timezone=timezone,
+                language=language,
+                industry=industry,
+                metadata=metadata,
+                address=address,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def create_batch(
+        self,
+        customers: list[dict[str, Any]],
+        *,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        mapped = [
+            build_body(
+                billing_email=c.get("email"),
+                external_id=c.get("external_id"),
+                full_name=c.get("full_name"),
+                domain=c.get("domain"),
+                website=c.get("website"),
+                timezone=c.get("timezone"),
+                language=c.get("language"),
+                industry=c.get("industry"),
+                metadata=c.get("metadata"),
+                address=c.get("address"),
+            )
+            for c in customers
+        ]
+        return self._http.post(
+            "/customers/batch", {"customers": mapped}, idempotency_key=idempotency_key
+        )
+
+    def get(self, customer_id: str) -> ApiResponse:
+        return self._http.get(f"/customers/{customer_id}")
+
+    def update(
+        self,
+        customer_id: str,
+        *,
+        email: str | None = None,
+        external_id: str | None = None,
+        full_name: str | None = None,
+        domain: str | None = None,
+        website: str | None = None,
+        timezone: str | None = None,
+        language: str | None = None,
+        industry: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.put(
+            f"/customers/{customer_id}",
+            build_body(
+                billing_email=email,
+                external_id=external_id,
+                full_name=full_name,
+                domain=domain,
+                website=website,
+                timezone=timezone,
+                language=language,
+                industry=industry,
+                metadata=metadata,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def list(
+        self,
+        *,
+        external_id: str | None = None,
+        is_active: bool | None = None,
+        search: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ApiResponse:
+        return self._http.get(
+            "/customers",
+            build_body(
+                external_id=external_id,
+                is_active=is_active,
+                search=search,
+                limit=limit,
+                cursor=cursor,
+            ),
+        )
+
+    def archive(self, customer_id: str, *, idempotency_key: str | None = None) -> ApiResponse:
+        return self._http.put(
+            f"/customers/{customer_id}",
+            {"is_active": False},
+            idempotency_key=idempotency_key,
+        )

commet/resources/features.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient
+
+
+class FeaturesResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def get(
+        self,
+        *,
+        code: str,
+        external_id: str,
+    ) -> ApiResponse:
+        return self._http.get(f"/features/{code}", {"external_id": external_id})
+
+    def check(
+        self,
+        *,
+        code: str,
+        external_id: str,
+    ) -> ApiResponse:
+        result = self._http.get(f"/features/{code}", {"external_id": external_id})
+
+        if not result.success or not result.data:
+            return ApiResponse(
+                success=False,
+                data={"allowed": False},
+                message=result.message,
+            )
+
+        return ApiResponse(
+            success=True,
+            data={"allowed": result.data.get("allowed", False)},
+            message=result.message,
+        )
+
+    def can_use(
+        self,
+        *,
+        code: str,
+        external_id: str,
+    ) -> ApiResponse:
+        return self._http.get(
+            f"/features/{code}", {"external_id": external_id, "action": "canUse"}
+        )
+
+    def list(self, external_id: str) -> ApiResponse:
+        return self._http.get("/features", {"external_id": external_id})

commet/resources/plans.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class PlansResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        include_private: bool | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ApiResponse:
+        return self._http.get("/plans", build_body(
+            include_private=include_private, limit=limit, cursor=cursor
+        ))
+
+    def get(self, plan_code: str) -> ApiResponse:
+        return self._http.get(f"/plans/{plan_code}")

commet/resources/portal.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class PortalResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def get_url(
+        self,
+        *,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        email: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.post(
+            "/portal/request-access",
+            build_body(customer_id=customer_id, external_id=external_id, email=email),
+            idempotency_key=idempotency_key,
+        )

commet/resources/seats.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class SeatsResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def add(
+        self,
+        *,
+        seat_type: str,
+        count: int,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.post(
+            "/seats",
+            build_body(
+                seat_type=seat_type, count=count,
+                customer_id=customer_id, external_id=external_id,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def remove(
+        self,
+        *,
+        seat_type: str,
+        count: int,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.delete(
+            "/seats",
+            build_body(
+                seat_type=seat_type, count=count,
+                customer_id=customer_id, external_id=external_id,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def set(
+        self,
+        *,
+        seat_type: str,
+        count: int,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.put(
+            "/seats",
+            build_body(
+                seat_type=seat_type, count=count,
+                customer_id=customer_id, external_id=external_id,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def set_all(
+        self,
+        *,
+        seats: dict[str, int],
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.put(
+            "/seats/bulk",
+            build_body(seats=seats, customer_id=customer_id, external_id=external_id),
+            idempotency_key=idempotency_key,
+        )
+
+    def get_balance(
+        self,
+        *,
+        seat_type: str,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+    ) -> ApiResponse:
+        return self._http.get(
+            "/seats/balance",
+            build_body(seat_type=seat_type, customer_id=customer_id, external_id=external_id),
+        )
+
+    def get_all_balances(
+        self,
+        *,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+    ) -> ApiResponse:
+        return self._http.get(
+            "/seats/balances",
+            build_body(customer_id=customer_id, external_id=external_id),
+        )

commet/resources/subscriptions.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class SubscriptionsResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        plan_code: str | None = None,
+        plan_id: str | None = None,
+        billing_interval: str | None = None,
+        initial_seats: dict[str, int] | None = None,
+        skip_trial: bool | None = None,
+        name: str | None = None,
+        start_date: str | None = None,
+        success_url: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.post(
+            "/subscriptions",
+            build_body(
+                customer_id=customer_id,
+                external_id=external_id,
+                plan_code=plan_code,
+                plan_id=plan_id,
+                billing_interval=billing_interval,
+                initial_seats=initial_seats,
+                skip_trial=skip_trial,
+                name=name,
+                start_date=start_date,
+                success_url=success_url,
+            ),
+            idempotency_key=idempotency_key,
+        )
+
+    def get(self, external_id: str) -> ApiResponse:
+        return self._http.get("/subscriptions/active", {"external_id": external_id})
+
+    def cancel(
+        self,
+        subscription_id: str,
+        *,
+        reason: str | None = None,
+        immediate: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        return self._http.post(
+            f"/subscriptions/{subscription_id}/cancel",
+            build_body(reason=reason, immediate=immediate),
+            idempotency_key=idempotency_key,
+        )

commet/resources/usage.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from .._http import ApiResponse, CommetHTTPClient, build_body
+
+
+class UsageResource:
+    def __init__(self, http: CommetHTTPClient) -> None:
+        self._http = http
+
+    def track(
+        self,
+        *,
+        feature: str,
+        customer_id: str | None = None,
+        external_id: str | None = None,
+        value: int | None = None,
+        model: str | None = None,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        cache_read_tokens: int | None = None,
+        cache_write_tokens: int | None = None,
+        idempotency_key: str | None = None,
+        timestamp: str | None = None,
+        properties: dict[str, str] | None = None,
+    ) -> ApiResponse:
+        props = (
+            [{"property": k, "value": v} for k, v in properties.items()] if properties else None
+        )
+
+        body = build_body(
+            feature=feature,
+            customer_id=customer_id,
+            external_id=external_id,
+            idempotency_key=idempotency_key,
+            timestamp=timestamp or datetime.now(timezone.utc).isoformat(),
+            properties=props,
+        )
+
+        if model:
+            body.update(build_body(
+                model=model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cache_read_tokens=cache_read_tokens,
+                cache_write_tokens=cache_write_tokens,
+            ))
+        else:
+            if value is not None:
+                body["value"] = value
+
+        return self._http.post("/usage/events", body, idempotency_key=idempotency_key)
+
+    def track_batch(
+        self,
+        events: list[dict[str, Any]],
+        *,
+        idempotency_key: str | None = None,
+    ) -> ApiResponse:
+        mapped = []
+        for evt in events:
+            props = evt.get("properties")
+            formatted_props = (
+                [{"property": k, "value": v} for k, v in props.items()] if props else None
+            )
+
+            entry = build_body(
+                feature=evt.get("feature"),
+                customer_id=evt.get("customer_id"),
+                external_id=evt.get("external_id"),
+                idempotency_key=evt.get("idempotency_key"),
+                timestamp=evt.get("timestamp") or datetime.now(timezone.utc).isoformat(),
+                properties=formatted_props,
+            )
+
+            if evt.get("model"):
+                entry.update(build_body(
+                    model=evt["model"],
+                    input_tokens=evt.get("input_tokens"),
+                    output_tokens=evt.get("output_tokens"),
+                    cache_read_tokens=evt.get("cache_read_tokens"),
+                    cache_write_tokens=evt.get("cache_write_tokens"),
+                ))
+            elif evt.get("value") is not None:
+                entry["value"] = evt["value"]
+
+            mapped.append(entry)
+
+        return self._http.post(
+            "/usage/events/batch", {"events": mapped}, idempotency_key=idempotency_key
+        )

commet/resources/webhooks.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any
+
+
+class Webhooks:
+    """Webhook signature verification.
+
+    Usage::
+
+        from commet import Webhooks
+
+        webhooks = Webhooks()
+
+        is_valid = webhooks.verify(
+            payload=raw_body,
+            signature=request.headers["x-commet-signature"],
+            secret=WEBHOOK_SECRET,
+        )
+    """
+
+    def verify(self, *, payload: str, signature: str | None, secret: str) -> bool:
+        if not signature or not secret or not payload:
+            return False
+
+        expected = self._sign(payload, secret)
+        return hmac.compare_digest(signature, expected)
+
+    def verify_and_parse(
+        self, *, raw_body: str, signature: str | None, secret: str
+    ) -> dict[str, Any] | None:
+        if not self.verify(payload=raw_body, signature=signature, secret=secret):
+            return None
+
+        try:
+            return json.loads(raw_body)
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    def _sign(self, payload: str, secret: str) -> str:
+        return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

commet_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: commet-sdk
+Version: 0.1.0
+Summary: Commet SDK for Python - Billing and usage tracking for SaaS
+Author: Commet Team
+License-Expression: MIT
+Project-URL: Homepage, https://commet.co
+Project-URL: Repository, https://github.com/commet-labs/commet-python
+Keywords: billing,sdk,payments,invoicing,usage-based-billing,seat-licensing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Dynamic: license-file
+
+# Commet Python SDK
+
+Billing and usage tracking for SaaS applications.
+
+## Installation
+
+```bash
+pip install commet
+```
+
+## Quick start
+
+```python
+from commet import Commet
+
+commet = Commet(api_key="ck_xxx", environment="production")
+
+# Create a customer
+commet.customers.create(email="user@example.com", external_id="user_123")
+
+# Create a subscription
+commet.subscriptions.create(external_id="user_123", plan_code="pro")
+
+# Track usage
+commet.usage.track(feature="api_calls", external_id="user_123")
+
+# Track AI token usage
+commet.usage.track(
+    feature="ai_generation",
+    external_id="user_123",
+    model="claude-sonnet-4-20250514",
+    input_tokens=1000,
+    output_tokens=500,
+)
+```
+
+## Customer context
+
+Scope all operations to a customer to avoid repeating `external_id`:
+
+```python
+customer = commet.customer("user_123")
+
+customer.usage.track("api_calls")
+customer.features.check("custom_branding")
+customer.seats.add("editor", count=3)
+customer.portal.get_url()
+```
+
+## Webhook verification
+
+```python
+from commet import Webhooks
+
+webhooks = Webhooks()
+
+payload = webhooks.verify_and_parse(
+    raw_body=request_body,
+    signature=request.headers["x-commet-signature"],
+    secret="whsec_xxx",
+)
+
+if payload is None:
+    raise ValueError("Invalid webhook signature")
+
+if payload["event"] == "subscription.activated":
+    # handle activation
+    pass
+```
+
+## Context manager
+
+```python
+with Commet(api_key="ck_xxx") as commet:
+    commet.usage.track(feature="api_calls", external_id="user_123")
+# connection pool is automatically closed
+```
+
+## Environments
+
+The SDK defaults to `sandbox`. Set `environment="production"` for live operations:
+
+```python
+commet = Commet(api_key="ck_xxx", environment="production")
+```
+
+## License
+
+MIT

commet_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+commet/__init__.py,sha256=pPfSFM2LkbZYfahEPMovWeYNNSmwVryQOxYA-ar0NVI,458
+commet/_customer.py,sha256=p_uUS0vZ2IBEuCqGf0SmG1RXWppDERuSX73100XKia4,3898
+commet/_exceptions.py,sha256=Ap9e6k2Cuj8gfvhGCLownjAZK3SQQuoRBV5EAh75Z6A,934
+commet/_http.py,sha256=OtD1wAZqjTakh8Btxk81duUrie73Qbr6-uKAP9DOf2o,7739
+commet/client.py,sha256=Q8bliLLM0TQZZEKGr1INSOm-6iREmNOUZ9w8Lj-yoVY,3342
+commet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commet/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commet/resources/credit_packs.py,sha256=bSyh4tMWOyJn2I5HD3Mk9fOm4dIBATfHa2HAq9P1JRs,280
+commet/resources/customers.py,sha256=_n1cjub9KeoJke9lfjxpivZU79EMyjfkZJDQEgMo-lY,3892
+commet/resources/features.py,sha256=bng3RXM90mIAzyUUNLiUDemv_Ihn2yg6kxR657XCeVs,1307
+commet/resources/plans.py,sha256=Rp7F4rEPqb9eR6ZknpEzjQzX4uOIs32vJdoiu7fLPUY,618
+commet/resources/portal.py,sha256=WwquAWQ4-49dNoeSwdGHFoGvhCDyd_Xxo9tc24Yi1nY,639
+commet/resources/seats.py,sha256=ODy-lFnXvLkhzna0kdw4IeygQ5Y1r4jo8NJR702tJGg,2745
+commet/resources/subscriptions.py,sha256=vYwUGMf1C5ZuV_c4X5K4JnKOR4XkO1ccfP-w4JjKgww,1826
+commet/resources/usage.py,sha256=cey0L2hzAAvSiTtfDnezTfp8I2p7NghswEbj5IKu5Jo,3106
+commet/resources/webhooks.py,sha256=5D-JW0Mb6g12zjsGDuhzwtREr26o9bsmA2EGI9majGQ,1188
+commet_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=An1hkhoPcAbt8WBg0BaPNUBbaNyOXnxC5aiz6vTA4dw,1063
+commet_sdk-0.1.0.dist-info/METADATA,sha256=vNLl_87TCoq61fr9FYozYiGz0egtrKvM0erVLg_DmWI,2821
+commet_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+commet_sdk-0.1.0.dist-info/top_level.txt,sha256=3V7AhucjAtcgz0ZwVpx1Cx-wBeViNGSvr3A-4K_rewQ,7
+commet_sdk-0.1.0.dist-info/RECORD,,

commet_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

commet_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Commet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

commet_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commet