V3

README.md

@@ -21,12 +21,6 @@ import contiguity
 client = contiguity.login("your_token_here")
 ```
 
-You can also initialize it with the optional 'debug' flag:
-
-```js
-client = contiguity.login("your_token_here", True)
-```
-
 You can get your token from the Contiguity [dashboard](https://contiguity.co/dashboard).
 
 ## Sending your first email 📤

examples/base/basic_usage.py

@@ -1,5 +1,4 @@
-# ruff: noqa: T201
-from contiguity import Base
+from contiguity.base import Base
 
 # Create a Base instance.
 db = Base("my-base")

examples/base/pydantic_usage.py → examples/base/msgspec_usage.py

@@ -1,11 +1,10 @@
-# ruff: noqa: T201
-from pydantic import BaseModel
+from msgspec import Struct
 
-from contiguity import Base
+from contiguity.base import Base
 
 
 # Create a Pydantic model for the item.
-class MyItem(BaseModel):
+class MyItem(Struct):
     key: str  # Make sure to include the key field.
     name: str
     age: int

pyproject.toml

@@ -10,7 +10,7 @@ dynamic = ["version"]
 description = "Contiguity's official Python SDK"
 readme = "README.md"
 license = {file = "LICENSE.txt"}
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     {name = "Contiguity", email = "help@contiguity.support"},
 ]
@@ -35,18 +35,18 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.27.2",
-    "phonenumbers>=8.13.47,<9.0.0",
-    "pydantic>=2.9.0,<3.0.0",
+    "msgspec>=0.19.0",
+    "phonenumbers>=9.0.15,<10.0.0",
     "typing-extensions>=4.12.2,<5.0.0",
 ]
 
 [dependency-groups]
 dev = [
-    "pre-commit~=3.8.0",
-    "pytest~=8.3.3",
-    "pytest-cov~=5.0.0",
-    "python-dotenv~=1.0.1",
-    "pytest-asyncio~=0.24.0",
+    "pre-commit~=4.3.0",
+    "pytest~=8.4.2",
+    "pytest-asyncio~=1.2.0",
+    "pytest-cov~=7.0.0",
+    "python-dotenv~=1.1.1",
 ]
 
 [project.urls]
@@ -61,7 +61,7 @@ version = {attr = "contiguity.__version__"}
 [tool.ruff]
 src = ["src"]
 line-length = 119
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["ALL"]

src/contiguity/__init__.py

@@ -1,66 +1,51 @@
 from ._client import ApiClient
-from .analytics import EmailAnalytics
-from .base import AsyncBase, Base, BaseItem, InvalidKeyError, ItemConflictError, ItemNotFoundError, QueryResponse
+from .domains import Domains
+from .email import Email
+from .imessage import IMessage
+from .leases import Leases
 from .otp import OTP
-from .quota import Quota
-from .send import Send
-from .template import Template
-from .verify import Verify
+from .text import Text
+from .whatsapp import WhatsApp
 
 
 class Contiguity:
     """
     Create a new instance of the Contiguity class.
+
     Args:
         token (str): The authentication token.
-        debug (bool, optional): A flag indicating whether to enable debug mode. Default is False.
     """
 
     def __init__(
         self,
         *,
         token: str,
-        base_url: str = "https://api.contiguity.co",
-        orwell_base_url: str = "https://orwell.contiguity.co",
-        debug: bool = False,
+        base_url: str = "https://api.contiguity.com",
     ) -> None:
         if not token:
-            msg = "Contiguity requires a token/API key to be provided via contiguity.login('token')"
+            msg = "token cannot be empty"
             raise ValueError(msg)
         self.token = token
         self.base_url = base_url
-        self.orwell_base_url = orwell_base_url
-        self.debug = debug
         self.client = ApiClient(base_url=self.base_url, api_key=token.strip())
-        self.orwell_client = ApiClient(base_url=self.orwell_base_url, api_key=token.strip())
-
-        self.send = Send(client=self.client, debug=self.debug)
-        self.verify = Verify()
-        self.email_analytics = EmailAnalytics(client=self.orwell_client, debug=self.debug)
-        self.quota = Quota(client=self.client, debug=self.debug)
-        self.otp = OTP(client=self.client, debug=self.debug)
-        self.template = Template()
-
 
-def login(token: str, /, *, debug: bool = False) -> Contiguity:
-    return Contiguity(token=token, debug=debug)
+        self.text = Text(client=self.client)
+        self.email = Email(client=self.client)
+        self.otp = OTP(client=self.client)
+        self.imessage = IMessage(client=self.client)
+        self.whatsapp = WhatsApp(client=self.client)
+        self.leases = Leases(client=self.client)
+        self.domains = Domains(client=self.client)
 
 
 __all__ = (
-    "AsyncBase",
-    "Contiguity",
-    "Send",
-    "Verify",
-    "EmailAnalytics",
-    "Quota",
     "OTP",
-    "Template",
-    "Base",
-    "BaseItem",
-    "InvalidKeyError",
-    "ItemConflictError",
-    "ItemNotFoundError",
-    "QueryResponse",
-    "login",
+    "Contiguity",
+    "Domains",
+    "Email",
+    "IMessage",
+    "Leases",
+    "Text",
+    "WhatsApp",
 )
-__version__ = "2.0.0"
+__version__ = "3.0.0"

src/contiguity/_auth.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import os
 
 

src/contiguity/_client.py

@@ -1,20 +1,30 @@
-from __future__ import annotations
+from http import HTTPStatus
 
 from httpx import AsyncClient as HttpxAsyncClient
 from httpx import Client as HttpxClient
+from httpx import Response
 
 from ._auth import get_contiguity_token
+from ._response import ErrorResponse, decode_response
 
 
-class ApiError(Exception):
+class ContiguityApiError(Exception):
     pass
 
 
-class ApiClient(HttpxClient):
+class BaseApiClient:
+    def handle_error(self, response: Response, /, *, fail_message: str = "api request failed") -> None:
+        if not HTTPStatus.OK <= response.status_code <= HTTPStatus.IM_USED:
+            data = decode_response(response.content, type=ErrorResponse)
+            msg = f"{fail_message}. {response.status_code} {data.error}"
+            raise ContiguityApiError(msg)
+
+
+class ApiClient(HttpxClient, BaseApiClient):
     def __init__(
-        self: ApiClient,
+        self: "ApiClient",
         *,
-        base_url: str = "https://api.contiguity.co",
+        base_url: str = "https://api.contiguity.com",
         api_key: str | None = None,
         timeout: int = 5,
     ) -> None:
@@ -23,19 +33,18 @@ def __init__(
         super().__init__(
             headers={
                 "Content-Type": "application/json",
-                "X-API-Key": api_key,
                 "Authorization": f"Token {api_key}",
             },
             timeout=timeout,
             base_url=base_url,
         )
 
 
-class AsyncApiClient(HttpxAsyncClient):
+class AsyncApiClient(HttpxAsyncClient, BaseApiClient):
     def __init__(
-        self: AsyncApiClient,
+        self: "AsyncApiClient",
         *,
-        base_url: str = "https://api.contiguity.co",
+        base_url: str = "https://api.contiguity.com",
         api_key: str | None = None,
         timeout: int = 5,
     ) -> None:
@@ -44,7 +53,6 @@ def __init__(
         super().__init__(
             headers={
                 "Content-Type": "application/json",
-                "X-API-Key": api_key,
                 "Authorization": f"Token {api_key}",
             },
             timeout=timeout,

src/contiguity/_instant_messaging.py

@@ -0,0 +1,112 @@
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Generic, Literal, TypeVar
+
+from ._product import BaseProduct
+from ._response import BaseResponse, decode_response
+
+FallbackCauseT = TypeVar("FallbackCauseT", bound=str)
+
+logger = logging.getLogger(__name__)
+
+
+class IMSendResponse(BaseResponse):
+    message_id: str
+
+
+class IMTypingResponse(BaseResponse):
+    status: str
+
+
+class IMReactionResponse(IMTypingResponse):
+    message: str
+
+
+class InstantMessagingClient(ABC, BaseProduct, Generic[FallbackCauseT]):
+    @property
+    @abstractmethod
+    def _api_path(self) -> str: ...
+
+    def send(  # noqa: PLR0913
+        self,
+        *,
+        to: str,
+        message: str,
+        from_: str | None = None,
+        attachments: Sequence[str] | None = None,
+        fallback_when: Sequence[FallbackCauseT] | None = None,
+        fallback_number: str | None = None,
+    ) -> IMSendResponse:
+        payload = {
+            "to": to,
+            "message": message,
+            "from": from_,
+            "attachments": attachments,
+            "fallback_when": fallback_when,
+            "fallback_number": fallback_number,
+        }
+
+        response = self._client.post(
+            self._api_path,
+            json={k: v for k, v in payload.items() if v is not None},
+        )
+
+        self._client.handle_error(response, fail_message="failed to send instant message")
+        data = decode_response(response.content, type=IMSendResponse)
+        logger.debug("successfully sent %s message to %r", self._api_path[1:], to)
+        return data
+
+    def _typing(self, *, to: str, action: Literal["start", "stop"], from_: str | None = None) -> IMTypingResponse:
+        payload = {
+            "to": to,
+            "action": action,
+            "from": from_,
+        }
+
+        response = self._client.post(
+            f"{self._api_path}/typing",
+            json={k: v for k, v in payload.items() if v is not None},
+        )
+
+        self._client.handle_error(response, fail_message=f"failed to {action} {self._api_path[1:]} typing indicator")
+        data = decode_response(response.content, type=IMTypingResponse)
+        logger.debug("successfully %s %s typing indicator for %r", action, self._api_path[1:], to)
+        return data
+
+    def start_typing(self, *, to: str, from_: str | None = None) -> IMTypingResponse:
+        return self._typing(to=to, action="start", from_=from_)
+
+    def stop_typing(self, *, to: str, from_: str | None = None) -> IMTypingResponse:
+        return self._typing(to=to, action="stop", from_=from_)
+
+    def _reactions(
+        self,
+        *,
+        to: str,
+        action: Literal["add", "remove"],
+        reaction: str,
+        message: str,
+    ) -> IMReactionResponse:
+        payload = {
+            "to": to,
+            "action": action,
+            "reaction": reaction,
+            "message": message,
+        }
+
+        response = self._client.post(
+            f"{self._api_path}/reactions",
+            json={k: v for k, v in payload.items() if v is not None},
+        )
+
+        self._client.handle_error(response, fail_message=f"failed to {action} {self._api_path[1:]} reaction")
+        data = decode_response(response.content, type=IMReactionResponse)
+        logger.debug("successfully %s %s reaction for %r", action, self._api_path[1:], to)
+        return data
+
+    def add_reaction(self, *, to: str, reaction: str, message: str) -> IMReactionResponse:
+        return self._reactions(to=to, action="add", reaction=reaction, message=message)
+
+    def remove_reaction(self, *, to: str, reaction: str, message: str) -> IMReactionResponse:
+        return self._reactions(to=to, action="remove", reaction=reaction, message=message)

src/contiguity/_product.py

@@ -0,0 +1,6 @@
+from ._client import ApiClient
+
+
+class BaseProduct:
+    def __init__(self, *, client: ApiClient) -> None:
+        self._client = client