ritten-python-sdk 1.0.0__tar.gz

ritten_python_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wesley Gonçalves
+
+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.

ritten_python_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: ritten-python-sdk
+Version: 1.0.0
+Summary: Python SDK for connecting applications to the Ritten EMR Platform. Simplifies integration with the Behavioral Health Operations API.
+License-File: LICENSE
+Keywords: ritten,emr,healthcare,sdk,python
+Author: Wesley Gonçalves
+Author-email: dev@wesleygoncalves.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Project-URL: Documentation, https://github.com/wesleygoncalves/ritten-python-sdk/blob/main/README.md
+Project-URL: Homepage, https://github.com/wesleygoncalves/ritten-python-sdk
+Project-URL: changelog, https://github.com/wesleygoncalves/ritten-python-sdk/blob/main/CHANGELOG.md
+Project-URL: issues, https://github.com/wesleygoncalves/ritten-python-sdk/issues
+Project-URL: source, https://github.com/wesleygoncalves/ritten-python-sdk
+Description-Content-Type: text/markdown
+
+# Ritten API Integration
+
+Python SDK for connecting applications to the [Ritten EMR Platform](https://docs.ritten.io/). This library simplifies integration with Ritten's Behavioral Health Operations API, allowing developers to use Ritten API seamlessly from any Python environment.
+
+Ritten API specifications:
+
+- [Documentation](https://docs.ritten.io/)
+- Version: 1
+
+## Installation
+
+The SDK requires **Python 3.10 or higher**. Install it directly via `pip`:
+
+```bash
+pip install ritten-python-sdk
+
+# Using poetry
+poetry add ritten-python-sdk
+
+# Using pipenv
+pipenv install ritten-python-sdk
+```
+
+## Quickstart Guide
+
+To get started, you must first obtain your integrator `client_id` and `client_secret` from your Ritten administrator portal.
+
+---
+
+## Advanced Resources
+
+- Review the official [Ritten API Documentation](https://docs.ritten.io/) for explicit payload schemas.
+- Check the `/examples` directory inside this repository for production-ready boilerplate code.
+
+## About the Author
+
+This SDK is developed and maintained by [Wesley Gonçalves](https://github.com/wesleygoncalves) under MIT license. Contributions and feedback are welcome!
+

ritten_python_sdk-1.0.0/README.md

@@ -0,0 +1,37 @@
+# Ritten API Integration
+
+Python SDK for connecting applications to the [Ritten EMR Platform](https://docs.ritten.io/). This library simplifies integration with Ritten's Behavioral Health Operations API, allowing developers to use Ritten API seamlessly from any Python environment.
+
+Ritten API specifications:
+
+- [Documentation](https://docs.ritten.io/)
+- Version: 1
+
+## Installation
+
+The SDK requires **Python 3.10 or higher**. Install it directly via `pip`:
+
+```bash
+pip install ritten-python-sdk
+
+# Using poetry
+poetry add ritten-python-sdk
+
+# Using pipenv
+pipenv install ritten-python-sdk
+```
+
+## Quickstart Guide
+
+To get started, you must first obtain your integrator `client_id` and `client_secret` from your Ritten administrator portal.
+
+---
+
+## Advanced Resources
+
+- Review the official [Ritten API Documentation](https://docs.ritten.io/) for explicit payload schemas.
+- Check the `/examples` directory inside this repository for production-ready boilerplate code.
+
+## About the Author
+
+This SDK is developed and maintained by [Wesley Gonçalves](https://github.com/wesleygoncalves) under MIT license. Contributions and feedback are welcome!

ritten_python_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ritten-python-sdk"
+version = "1.0.0"
+description = "Python SDK for connecting applications to the Ritten EMR Platform. Simplifies integration with the Behavioral Health Operations API."
+keywords = ["ritten", "emr", "healthcare", "sdk", "python"]
+authors = [
+    {name = "Wesley Gonçalves",email = "dev@wesleygoncalves.com"}
+]
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx >=0.28.1,<0.29.0",
+    "pydantic >=2.13.4,<3.0.0"
+]
+
+[project.urls]
+homepage = "https://github.com/wesleygoncalves/ritten-python-sdk"
+source = "https://github.com/wesleygoncalves/ritten-python-sdk"
+issues = "https://github.com/wesleygoncalves/ritten-python-sdk/issues"
+changelog = "https://github.com/wesleygoncalves/ritten-python-sdk/blob/main/CHANGELOG.md"
+documentation = "https://github.com/wesleygoncalves/ritten-python-sdk/blob/main/README.md"
+
+[tool.poetry]
+packages = [
+    { include = "ritten", from = "src" },
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

ritten_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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_python_sdk-1.0.0/src/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()