ritten-python-sdk 1.0.0__py3-none-any.whl

ritten/__init__.py

@@ -0,0 +1,73 @@
+"""
+Ritten SDK.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+from ritten.ritten import Ritten
+from ritten.auth import Auth
+from ritten.config import Config
+from ritten.exceptions import (
+    RittenError,
+    RittenClientError,
+    RittenConnectionError,
+    RittenAPIError,
+    RittenAuthError,
+    RittenUnauthorizedError,
+    RittenValidationError,
+    RittenNotFoundError,
+    RittenRateLimitError,
+    RittenServerError,
+)
+from ritten.resources import (
+    Resource,
+    Calendar,
+    Cases,
+    Contacts,
+    Facilities,
+    Forms,
+    Insurance,
+    Organizations,
+    Patients,
+    Programs,
+    Users,
+)
+from ritten.storage import TokenStorage, MemoryStorage
+
+__all__ = [
+    "Ritten",
+    "Auth",
+    "Config",
+    "TokenStorage",
+    "MemoryStorage",
+    "RittenError",
+    "RittenClientError",
+    "RittenConnectionError",
+    "RittenAPIError",
+    "RittenAuthError",
+    "RittenUnauthorizedError",
+    "RittenValidationError",
+    "RittenNotFoundError",
+    "RittenRateLimitError",
+    "RittenServerError",
+    "Resource",
+    "Calendar",
+    "Cases",
+    "Contacts",
+    "Facilities",
+    "Forms",
+    "Insurance",
+    "Organizations",
+    "Patients",
+    "Programs",
+    "Users",
+]
+
+
+try:
+    __version__ = version("ritten-python-sdk")
+except PackageNotFoundError:
+    __version__ = "unknown"

ritten/auth.py

@@ -0,0 +1,91 @@
+"""
+Ritten SDK Authentication Handler.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from ritten.config import Config
+from ritten.exceptions import RittenAuthError, RittenUnauthorizedError
+
+
+class Auth(httpx.Auth):
+    """Authentication handler for the Ritten API."""
+
+    def __init__(self, config: Config):
+        self.config = config
+
+    @property
+    def access_token(self) -> str | None:
+        """Fetch the access token."""
+        token = self.config.storage.get_token()
+        return token
+
+    @access_token.setter
+    def access_token(self, value: str) -> Auth:
+        """Set a new access token."""
+        self.config.storage.set_token(value)
+
+        return self
+
+    @property
+    def client_id(self) -> str | None:
+        """Fetch the client ID for authentication."""
+        return self.config.client_id
+
+    @property
+    def client_secret(self) -> str | None:
+        """Fetch the client secret for authentication."""
+        return self.config.client_secret
+
+    def _fetch_new_token(self) -> None:
+        """Fetch a new access token using client credentials."""
+        if not self.config.client_id or not self.config.client_secret:
+            raise RittenAuthError(
+                "Client ID and Client Secret are required to fetch a new access token."
+            )
+
+        response = httpx.post(
+            f"{self.config.base_url}/oauth/token",
+            json={
+                "grant_type": "client_credentials",
+                "client_id": self.config.client_id,
+                "client_secret": self.config.client_secret,
+                "audience": self.config.audience,
+            },
+        )
+
+        if response.status_code == 200:
+            self.access_token = response.json()["access_token"]
+
+    def add_bearer_token(self, request: httpx.Request) -> httpx.Request:
+        """Add the Bearer token to the request headers."""
+        request.headers["Authorization"] = f"Bearer {self.access_token}"
+        return request
+
+    def auth_flow(self, request: httpx.Request):
+        """Controls the entire authentication workflow."""
+
+        if not self.access_token:
+            self._fetch_new_token()
+        self.add_bearer_token(request)
+
+        response = yield request
+
+        # Handle Expiration (401 Unauthorized)
+        if response.status_code == 401:
+            self._fetch_new_token()
+            self.add_bearer_token(request)
+
+            # replays the API call
+            retry_request = yield request
+
+            # if still fails
+            if retry_request.status_code == 401:
+                retry_request.read()
+                response = retry_request.json()
+                raise RittenUnauthorizedError(
+                    message=response.get("message", "Unauthorized request."),
+                    status_code=retry_request.status_code,
+                )

ritten/config.py

@@ -0,0 +1,85 @@
+"""
+Ritten SDK Configuration.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+from typing import Any
+from pydantic import (
+    BaseModel,
+    Field,
+    field_validator,
+    ConfigDict,
+)
+from ritten.storage import TokenStorage, MemoryStorage
+from ritten.exceptions import RittenError
+
+
+class Config(BaseModel):
+    """Configuration for the Ritten SDK client."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    base_url: str = Field(
+        default="https://api.ritten.io/v1",
+        description="Base URL for the Ritten API.",
+    )
+
+    audience: str = Field(
+        default="https://external-api.ritten.io",
+        description="Audience for OAuth token requests.",
+    )
+
+    # Authentication
+    tenant_id: str | None = Field(
+        default="ritclinic",
+        description="Tenant ID for the Ritten API.",
+    )
+
+    client_id: str | None = Field(
+        default=None,
+        description="Client ID for authentication.",
+    )
+    client_secret: str | None = Field(
+        default=None,
+        description="Client secret for authentication.",
+    )
+
+    storage: TokenStorage = Field(
+        default=MemoryStorage(),
+        description="Token storage mechanism. Defaults to in-memory storage.",
+    )
+
+    @field_validator("storage", mode="after")
+    @classmethod
+    def validate_storage_interface(cls, value: Any) -> Any:
+        """Validates that the provided storage object implements the `TokenStorage` protocol if it is not None."""
+        if value is None:
+            return value
+
+        if not isinstance(value, TokenStorage):
+            raise RittenError(
+                "The provided storage object must implement the `TokenStorage` protocol."
+            )
+
+        return value
+
+    # Connection pooling and timeout settings
+    timeout: float = Field(
+        default=30.0,
+        description="The timeout in seconds for the HTTP client.",
+    )
+    max_connections: int = Field(
+        default=10,
+        description="Maximum number of concurrent connections in the pool.",
+    )
+    max_keepalive_connections: int = Field(
+        default=5,
+        description="Maximum number of keep-alive connections to maintain.",
+    )
+
+    keepalive_expiry: float = Field(
+        default=5.0,
+        description="Time in seconds before a keep-alive connection is closed. Keep this low for serverless.",
+    )

ritten/decorators.py

@@ -0,0 +1,45 @@
+from functools import wraps
+import httpx
+from pydantic import ValidationError
+import json
+from ritten.exceptions import (
+    RittenError,
+    RittenConnectionError,
+    RittenValueError,
+    RittenParseError,
+)
+
+
+def exception_handler(func):
+    """
+    Decorator that translates third-party exceptions into native SDK exceptions.
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+
+        # If it's a RittenError exception, reraise it.
+        except RittenError:
+            raise
+
+        # Network-level failures
+        except httpx.RequestError as e:
+            raise RittenConnectionError(f"A network error occurred: {str(e)}") from e
+
+        # Validation errors
+        except ValidationError as e:
+            raise RittenValueError(f"Data validation failed: {str(e)}") from e
+
+        # JSON parsing errors
+        except json.JSONDecodeError as e:
+            raise RittenParseError(
+                f"Failed to parse API response as JSON: {str(e)}"
+            ) from e
+
+        # The Ultimate Catch-All for anything else
+        except Exception as e:
+            raise RittenError(f"An unexpected SDK error occurred: {str(e)}") from e
+
+    return wrapper

ritten/exceptions.py

@@ -0,0 +1,95 @@
+"""
+Ritten SDK Exceptions.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+
+class RittenError(Exception):
+    """The base exception for all Ritten SDK errors."""
+
+    pass
+
+
+class RittenClientError(RittenError):
+    """Client is misconfigured or used incorrectly."""
+
+    pass
+
+
+class RittenConnectionError(RittenError):
+    """SDK cannot reach the API."""
+
+    pass
+
+
+class RittenValueError(RittenError):
+    """Invalid value provided to a method."""
+
+    pass
+
+
+class RittenParseError(RittenError):
+    """Failed to parse API response."""
+
+    pass
+
+
+class RittenAuthError(RittenError):
+    """Authentication error."""
+
+    pass
+
+
+# HTTP Response Errors
+class RittenAPIError(RittenError):
+    """Base class for errors returned by the Ritten API (HTTP 4xx and 5xx)."""
+
+    def __init__(self, message: str, status_code: int, payload: dict | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload or {}
+
+
+class RittenUnauthorizedError(RittenAPIError):
+    """401 Unauthorized or 403 Forbidden."""
+
+    pass
+
+
+class RittenValidationError(RittenAPIError):
+    """400 Bad Request or 422 Unprocessable Entity."""
+
+    pass
+
+
+class RittenNotFoundError(RittenAPIError):
+    """404 Not Found."""
+
+    pass
+
+
+class RittenRateLimitError(RittenAPIError):
+    """429 Too Many Requests."""
+
+    pass
+
+
+class RittenServerError(RittenAPIError):
+    """5xx Server Errors (e.g., 500, 502, 503)."""
+
+    pass
+
+
+ERROR_MAP = {
+    400: RittenValidationError,
+    403: RittenUnauthorizedError,
+    404: RittenNotFoundError,
+    422: RittenValidationError,
+    429: RittenRateLimitError,
+    500: RittenServerError,
+    502: RittenServerError,
+    503: RittenServerError,
+}
+"""Mapping of HTTP status codes to specific error classes for structured error handling."""

ritten/resources/__init__.py

@@ -0,0 +1,32 @@
+"""
+Ritten SDK Resources.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+from ritten.resources.resource import Resource
+from ritten.resources.calendar import Calendar
+from ritten.resources.cases import Cases
+from ritten.resources.contacts import Contacts
+from ritten.resources.facilities import Facilities
+from ritten.resources.forms import Forms
+from ritten.resources.insurance import Insurance
+from ritten.resources.organizations import Organizations
+from ritten.resources.patients import Patients
+from ritten.resources.programs import Programs
+from ritten.resources.users import Users
+
+__all__ = [
+    "Resource",
+    "Calendar",
+    "Cases",
+    "Contacts",
+    "Facilities",
+    "Forms",
+    "Insurance",
+    "Organizations",
+    "Patients",
+    "Programs",
+    "Users",
+]

ritten/resources/calendar.py

@@ -0,0 +1,32 @@
+"""
+Ritten SDK Calendar Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+
+from ritten.resources.resource import Resource
+
+
+class Calendar(Resource):
+    """
+    Handles all interactions with the Ritten API `/calendar/events` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/calendar/events"
+
+    def list(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Queries calendar events based on specific criteria.
+        The POST body is the query object.
+        """
+        return self._client.post(f"{self._base_path}/list", json=payload).json()
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a new calendar event."""
+        return self._client.post(f"{self._base_path}", json=payload).json()

ritten/resources/cases.py

@@ -0,0 +1,51 @@
+"""
+Ritten SDK Cases Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+
+from ritten.resources.resource import Resource
+
+
+class Cases(Resource):
+    """
+    Handles all interactions with the Ritten API `/cases` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/cases"
+
+    def list(self, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Lists cases in a clinic."""
+        params = {
+            "limit": limit,
+            "offset": offset,
+        }
+        return self._client.get(self._base_path, params=params).json()
+
+    def get(self, id: str) -> Dict[str, Any]:
+        """Retrieves a single case by its ID."""
+        return self._client.get(f"{self._base_path}/{id}").json()
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a new case."""
+        return self._client.post(self._base_path, json=payload).json()
+
+    def update(self, id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Updates an existing case by ID."""
+        return self._client.patch(
+            f"{self._base_path}/{id}",
+            json=payload,
+        ).json()
+
+    def create_note(self, id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a note for a specific case."""
+        return self._client.post(
+            f"{self._base_path}/{id}/notes",
+            json=payload,
+        ).json()

ritten/resources/contacts.py

@@ -0,0 +1,52 @@
+"""
+Ritten SDK Contacts Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+
+from ritten.resources.resource import Resource
+
+
+class Contacts(Resource):
+    """
+    Handles all interactions with the Ritten API `/contacts` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/contacts"
+
+    def list(self, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Lists contacts in a clinic."""
+        params = {"limit": limit, "offset": offset}
+        return self._client.get(self._base_path, params=params).json()
+
+    def get(self, id: str) -> Dict[str, Any]:
+        """Retrieves a single contact by their ID."""
+        return self._client.get(f"{self._base_path}/{id}").json()
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a new contact."""
+        return self._client.post(self._base_path, json=payload).json()
+
+    def update(self, id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Updates an existing contact by ID."""
+        return self._client.patch(
+            f"{self._base_path}/{id}",
+            json=payload,
+        ).json()
+
+    def list_relationships(self, id: str) -> Dict[str, Any]:
+        """Lists a contact's relationships."""
+        return self._client.get(f"{self._base_path}/{id}/relationships").json()
+
+    def create_relationship(self, id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a new relationship for a contact."""
+        return self._client.post(
+            f"{self._base_path}/{id}/relationships",
+            json=payload,
+        ).json()

ritten/resources/facilities.py

@@ -0,0 +1,54 @@
+"""
+Ritten SDK Facilities Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+from datetime import datetime
+
+from ritten.resources.resource import Resource
+from ritten.utils import to_iso_format
+
+
+class Facilities(Resource):
+    """
+    Handles all interactions with the Ritten API `/facilities` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/facilities"
+
+    def list(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+        search: str | None = None,
+        created_after: datetime | None = None,
+    ) -> Dict[str, Any]:
+        """Lists active clinic facilities.
+
+        Arguments:
+            limit: Number of facilities to return (default: 20).
+            offset: Number of facilities to skip for pagination (default: 0).
+            search: Optional case-insensitive search to filter facilities by name.
+            created_after: Optional datetime to filter facilities created after this date.
+        """
+        params = {"limit": limit, "offset": offset}
+        if search:
+            params["search"] = search
+        if created_after:
+            params["createdAfter"] = to_iso_format(created_after)
+        return self._client.get(self._base_path, params=params).json()
+
+    def create(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Creates a new facility."""
+        return self._client.post(self._base_path, json=payload).json()
+
+    def update(self, id: str, name: str) -> None | Dict[str, Any]:
+        """Updates an existing facility by ID."""
+        payload = {"name": name}
+        return self._client.patch(f"{self._base_path}/{id}", json=payload).json()

ritten/resources/forms.py

@@ -0,0 +1,32 @@
+"""
+Ritten SDK Forms Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+
+from ritten.resources.resource import Resource
+
+
+class Forms(Resource):
+    """
+    Handles all interactions with the Ritten API `/forms/definitions` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/forms/definitions"
+
+    def list(
+        self, show_archived: bool, is_tx_plan: bool, field_definition_ids: list[str]
+    ) -> Dict[str, Any]:
+        """List all form definitions configured for the clinic, including section definitions and signature requirements."""
+        params = {
+            "showArchived": show_archived,
+            "isTxPlan": is_tx_plan,
+            "fieldDefinitionIds": field_definition_ids,
+        }
+        return self._client.get(f"{self._base_path}", params=params).json()

ritten/resources/insurance.py

@@ -0,0 +1,29 @@
+"""
+Ritten SDK Insurance Resource.
+
+:copyright: (c) 2026 by Wesley Gonçalves.
+:license: MIT, see LICENSE for more details.
+"""
+
+import httpx
+from typing import Dict, Any
+
+from ritten.resources.resource import Resource
+
+
+class Insurance(Resource):
+    """
+    Handles all interactions with the Ritten API `/insurance/payers` endpoints.
+    """
+
+    def __init__(self, client: httpx.Client):
+        self._client = client
+        self._base_path = "/insurance/payers"
+
+    def list(self) -> Dict[str, Any]:
+        """List all insurance payers."""
+        return self._client.get(f"{self._base_path}").json()
+
+    def get(self, id: str) -> Dict[str, Any]:
+        """Retrieves a single insurance payer by their ID."""
+        return self._client.get(f"{self._base_path}/{id}").json()