documentors 0.1.0__py3-none-any.whl

documentors/__init__.py

@@ -0,0 +1,59 @@
+"""DocuMentors Python SDK — secure document lifecycle management."""
+
+from .client import DocumentorsClient
+from .exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DocumentorsError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    APIKey,
+    APIKeyCreated,
+    Document,
+    DocumentVersion,
+    LegalHold,
+    PaginatedResponse,
+    PhishingVerdict,
+    PIIFinding,
+    RetentionPolicy,
+    ScanHistoryEntry,
+    ScanResult,
+    TokenResponse,
+    URLThreat,
+    User,
+)
+
+__all__ = [
+    "DocumentorsClient",
+    # Exceptions
+    "DocumentorsError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "ConflictError",
+    # Models
+    "Document",
+    "DocumentVersion",
+    "PaginatedResponse",
+    "ScanResult",
+    "PIIFinding",
+    "ScanHistoryEntry",
+    "PhishingVerdict",
+    "URLThreat",
+    "LegalHold",
+    "RetentionPolicy",
+    "User",
+    "APIKey",
+    "APIKeyCreated",
+    "TokenResponse",
+]
+
+__version__ = "0.1.0"

documentors/_transport.py

@@ -0,0 +1,173 @@
+"""HTTP transport with retry, error mapping, and auth injection."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DocumentorsError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+logger = logging.getLogger("documentors")
+
+_STATUS_MAP: dict[int, type[DocumentorsError]] = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+}
+
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_BACKOFF_FACTOR = 0.5
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class Transport:
+    """Low-level HTTP helper used by resource modules."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        headers: dict[str, str],
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        backoff_factor: float = _DEFAULT_BACKOFF_FACTOR,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._headers = headers
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._backoff_factor = backoff_factor
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._headers,
+            timeout=self._timeout,
+            follow_redirects=True,
+        )
+
+    # -- public helpers -----------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        files: Optional[Any] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with retry and error mapping."""
+        url = path if path.startswith("http") else path
+        headers = {**self._headers, **(extra_headers or {})}
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                resp = self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=_strip_none(params),
+                    data=data,
+                    files=files,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    self._sleep(attempt)
+                    continue
+                raise DocumentorsError(f"Connection error: {exc}") from exc
+
+            if resp.status_code < 400:
+                return resp
+
+            if resp.status_code in _RETRYABLE_STATUS and attempt < self._max_retries:
+                retry_after = _parse_retry_after(resp)
+                self._sleep(attempt, retry_after)
+                continue
+
+            self._raise_for_status(resp)
+
+        raise DocumentorsError(f"Request failed after {self._max_retries} retries") from last_exc
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- internals ----------------------------------------------------------
+
+    def _sleep(self, attempt: int, override: Optional[float] = None) -> None:
+        delay = override if override is not None else self._backoff_factor * (2 ** (attempt - 1))
+        logger.debug("Retry attempt %d — sleeping %.1fs", attempt, delay)
+        time.sleep(delay)
+
+    @staticmethod
+    def _raise_for_status(resp: httpx.Response) -> None:
+        detail = ""
+        details: dict[str, Any] = {}
+        try:
+            body = resp.json()
+            detail = body.get("detail", body.get("message", ""))
+            details = body if isinstance(body, dict) else {}
+        except Exception:
+            detail = resp.text[:500]
+
+        if resp.status_code == 429:
+            raise RateLimitError(
+                detail or "Rate limit exceeded",
+                retry_after=_parse_retry_after(resp),
+                details=details,
+            )
+
+        exc_cls = _STATUS_MAP.get(resp.status_code, ServerError if resp.status_code >= 500 else DocumentorsError)
+        raise exc_cls(
+            detail or f"HTTP {resp.status_code}",
+            details=details,
+        )
+
+
+def _strip_none(params: Optional[dict[str, Any]]) -> Optional[dict[str, Any]]:
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse_retry_after(resp: httpx.Response) -> Optional[int]:
+    val = resp.headers.get("Retry-After")
+    if val is None:
+        return None
+    try:
+        return int(val)
+    except ValueError:
+        return None

documentors/admin.py

@@ -0,0 +1,250 @@
+"""Admin operations — users, organizations, API keys, audit logs, devices."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from uuid import UUID
+
+from ._transport import Transport
+from .models import ActivationCode, APIKey, APIKeyCreated, Device, OrgInvitation, OrgMember, PaginatedResponse, User
+
+
+class Admin:
+    """``client.admin.*`` — administrative endpoints (requires admin/superuser role)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    # -- Users --------------------------------------------------------------
+
+    def list_users(
+        self,
+        *,
+        is_active: Optional[bool] = None,
+        search: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 50,
+    ) -> PaginatedResponse:
+        """List platform users with optional filters."""
+        resp = self._t.get(
+            "/api/v1/users",
+            params={"is_active": is_active, "search": search, "skip": skip, "limit": limit},
+        )
+        return PaginatedResponse.model_validate(resp.json())
+
+    def get_user(self, user_id: UUID | str) -> User:
+        """Get a user by ID."""
+        resp = self._t.get(f"/api/v1/users/{user_id}")
+        return User.model_validate(resp.json())
+
+    def disable_user(self, user_id: UUID | str) -> dict[str, Any]:
+        """Disable a user account."""
+        resp = self._t.patch(f"/api/v1/users/{user_id}", json={"is_active": False})
+        return resp.json()
+
+    def enable_user(self, user_id: UUID | str) -> dict[str, Any]:
+        """Re-enable a user account."""
+        resp = self._t.patch(f"/api/v1/users/{user_id}", json={"is_active": True})
+        return resp.json()
+
+    # -- API Keys -----------------------------------------------------------
+
+    def list_api_keys(
+        self,
+        *,
+        status: Optional[str] = None,
+    ) -> list[APIKey]:
+        """List API keys for the organization."""
+        resp = self._t.get("/api/v1/admin/api-keys", params={"status": status})
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", data.get("keys", []))
+        return [APIKey.model_validate(k) for k in items]
+
+    def create_api_key(
+        self,
+        *,
+        organization_id: UUID | str,
+        name: str,
+        description: Optional[str] = None,
+        key_type: str = "custom",
+        permissions: Optional[list[dict[str, Any]]] = None,
+        rate_limit_override: Optional[int] = None,
+        ip_whitelist: Optional[list[str]] = None,
+        expires_at: Optional[str] = None,
+    ) -> APIKeyCreated:
+        """Create a new API key. The secret is returned only once."""
+        body: dict[str, Any] = {
+            "organization_id": str(organization_id),
+            "name": name,
+            "key_type": key_type,
+        }
+        if description is not None:
+            body["description"] = description
+        if permissions is not None:
+            body["permissions"] = permissions
+        if rate_limit_override is not None:
+            body["rate_limit_override"] = rate_limit_override
+        if ip_whitelist is not None:
+            body["ip_whitelist"] = ip_whitelist
+        if expires_at is not None:
+            body["expires_at"] = expires_at
+        resp = self._t.post("/api/v1/admin/api-keys", json=body)
+        return APIKeyCreated.model_validate(resp.json())
+
+    def revoke_api_key(self, key_id: UUID | str) -> dict[str, Any]:
+        """Revoke an API key immediately."""
+        resp = self._t.post(f"/api/v1/admin/api-keys/{key_id}/revoke")
+        return resp.json()
+
+    def get_api_key_usage(self, key_id: UUID | str) -> dict[str, Any]:
+        """Get usage statistics for an API key."""
+        resp = self._t.get(f"/api/v1/admin/api-keys/{key_id}/usage")
+        return resp.json()
+
+    # -- Audit Logs ---------------------------------------------------------
+
+    def get_audit_logs(
+        self,
+        *,
+        user_id: Optional[str] = None,
+        action: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 50,
+    ) -> PaginatedResponse:
+        """Query the security audit trail."""
+        resp = self._t.get(
+            "/api/v1/audit-logs",
+            params={"user_id": user_id, "action": action, "skip": skip, "limit": limit},
+        )
+        return PaginatedResponse.model_validate(resp.json())
+
+    # -- Devices ------------------------------------------------------------
+
+    def list_devices(
+        self,
+        *,
+        status: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> list[Device]:
+        """List all registered devices (admin view)."""
+        resp = self._t.get(
+            "/api/v1/admin/devices",
+            params={"status": status, "user_id": user_id},
+        )
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", data.get("devices", []))
+        return [Device.model_validate(d) for d in items]
+
+    def create_activation_code(
+        self,
+        *,
+        target_user_id: Optional[str] = None,
+        target_email: Optional[str] = None,
+        max_uses: int = 1,
+        expiry_hours: int = 24,
+    ) -> ActivationCode:
+        """Generate a device activation code."""
+        body: dict[str, Any] = {"max_uses": max_uses, "expiry_hours": expiry_hours}
+        if target_user_id is not None:
+            body["target_user_id"] = target_user_id
+        if target_email is not None:
+            body["target_email"] = target_email
+        resp = self._t.post("/api/v1/admin/devices/activation-codes", json=body)
+        return ActivationCode.model_validate(resp.json())
+
+    def suspend_device(self, device_id: UUID | str) -> dict[str, Any]:
+        """Suspend a device."""
+        resp = self._t.post(f"/api/v1/admin/devices/{device_id}/suspend")
+        return resp.json()
+
+    def reactivate_device(self, device_id: UUID | str) -> dict[str, Any]:
+        """Reactivate a suspended device."""
+        resp = self._t.post(f"/api/v1/admin/devices/{device_id}/reactivate")
+        return resp.json()
+
+    def revoke_device(self, device_id: UUID | str) -> dict[str, Any]:
+        """Force-revoke a device (admin)."""
+        resp = self._t.delete(f"/api/v1/admin/devices/{device_id}")
+        return resp.json()
+
+    # -- Org Members --------------------------------------------------------
+
+    def invite_user(
+        self,
+        org_id: UUID | str,
+        *,
+        email: str,
+        role: str = "member",
+        department_id: Optional[UUID | str] = None,
+        message: Optional[str] = None,
+    ) -> OrgInvitation:
+        """Invite a user to the organization."""
+        body: dict[str, Any] = {"email": email, "role": role}
+        if department_id is not None:
+            body["department_id"] = str(department_id)
+        if message is not None:
+            body["message"] = message
+        resp = self._t.post(f"/api/organizations/{org_id}/users", json=body)
+        return OrgInvitation.model_validate(resp.json())
+
+    def list_org_members(
+        self,
+        org_id: UUID | str,
+        *,
+        role: Optional[str] = None,
+        search: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 50,
+    ) -> PaginatedResponse:
+        """List members of an organization."""
+        resp = self._t.get(
+            f"/api/organizations/{org_id}/users",
+            params={"role": role, "search": search, "skip": skip, "limit": limit},
+        )
+        return PaginatedResponse.model_validate(resp.json())
+
+    def update_member_role(
+        self,
+        org_id: UUID | str,
+        user_id: int | str,
+        *,
+        role: Optional[str] = None,
+        department_id: Optional[UUID | str] = None,
+        is_active: Optional[bool] = None,
+    ) -> OrgMember:
+        """Update an organization member's role or status."""
+        body: dict[str, Any] = {}
+        if role is not None:
+            body["role"] = role
+        if department_id is not None:
+            body["department_id"] = str(department_id)
+        if is_active is not None:
+            body["is_active"] = is_active
+        resp = self._t.patch(f"/api/organizations/{org_id}/users/{user_id}", json=body)
+        return OrgMember.model_validate(resp.json())
+
+    def remove_member(self, org_id: UUID | str, user_id: int | str) -> None:
+        """Remove a member from the organization."""
+        self._t.delete(f"/api/organizations/{org_id}/users/{user_id}")
+
+    def accept_invitation(self, invitation_id: int | str, token: str) -> dict[str, Any]:
+        """Accept an organization invitation."""
+        resp = self._t.post(
+            f"/api/users/invitations/{invitation_id}/accept",
+            json={"token": token},
+        )
+        return resp.json()
+
+    def decline_invitation(
+        self,
+        invitation_id: int | str,
+        token: str,
+        *,
+        reason: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Decline an organization invitation."""
+        body: dict[str, Any] = {"token": token}
+        if reason is not None:
+            body["reason"] = reason
+        resp = self._t.post(f"/api/users/invitations/{invitation_id}/decline", json=body)
+        return resp.json()

documentors/client.py

@@ -0,0 +1,98 @@
+"""Top-level DocumentorsClient — single entry point for the SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._transport import Transport
+from .admin import Admin
+from .compliance import Compliance
+from .documents import Documents
+from .models import TokenResponse
+from .security import Security
+
+
+class DocumentorsClient:
+    """Synchronous client for the DocuMentors platform API.
+
+    Authenticate with either an API key or JWT credentials::
+
+        # API key auth (recommended for integrations)
+        client = DocumentorsClient(
+            base_url="https://sandbox.docu-mentors.com",
+            api_key="dk_sandbox_abc123...",
+        )
+
+        # JWT auth (interactive / admin scripts)
+        client = DocumentorsClient(
+            base_url="https://sandbox.docu-mentors.com",
+        )
+        client.login(email="admin@example.com", password="secret")
+
+    Resource namespaces:
+
+    - ``client.documents`` — upload, list, download, delete, versions
+    - ``client.security`` — PII detection, phishing analysis, redaction
+    - ``client.compliance`` — legal holds, eDiscovery, records management
+    - ``client.admin`` — users, API keys, audit logs, devices
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: Optional[str] = None,
+        jwt_token: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+    ) -> None:
+        headers: dict[str, str] = {
+            "Accept": "application/json",
+            "User-Agent": "documentors-python/0.1.0",
+        }
+        if api_key is not None:
+            headers["X-API-Key"] = api_key
+        elif jwt_token is not None:
+            headers["Authorization"] = f"Bearer {jwt_token}"
+
+        self._transport = Transport(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            max_retries=max_retries,
+            backoff_factor=backoff_factor,
+        )
+
+        self.documents = Documents(self._transport)
+        self.security = Security(self._transport)
+        self.compliance = Compliance(self._transport)
+        self.admin = Admin(self._transport)
+
+    def login(self, *, email: str, password: str) -> TokenResponse:
+        """Authenticate with email/password and store the JWT for subsequent requests.
+
+        Returns the token response including user details.
+        """
+        resp = self._transport.post(
+            "/api/v1/auth/login",
+            json={"email": email, "password": password},
+        )
+        token = TokenResponse.model_validate(resp.json())
+        self._transport._headers["Authorization"] = f"Bearer {token.access_token}"
+        return token
+
+    def health(self) -> dict:
+        """Check platform health."""
+        resp = self._transport.get("/health")
+        return resp.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._transport.close()
+
+    def __enter__(self) -> DocumentorsClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()