documentors 0.1.0__py3-none-any.whl

documentors/compliance.py

@@ -0,0 +1,137 @@
+"""Compliance operations — legal holds, eDiscovery, records management."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from uuid import UUID
+
+from ._transport import Transport
+from .models import LegalHold, RetentionPolicy
+
+
+class Compliance:
+    """``client.compliance.*`` — governance and compliance workflows."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    # -- Legal Holds --------------------------------------------------------
+
+    def create_legal_hold(
+        self,
+        *,
+        name: str,
+        description: Optional[str] = None,
+        custodian_ids: Optional[list[str]] = None,
+    ) -> LegalHold:
+        """Create a new legal hold."""
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if custodian_ids is not None:
+            body["custodian_ids"] = custodian_ids
+        resp = self._t.post("/api/v1/governance/holds", json=body)
+        return LegalHold.model_validate(resp.json())
+
+    def get_legal_hold(self, hold_id: UUID | str) -> LegalHold:
+        """Get a legal hold by ID."""
+        resp = self._t.get(f"/api/v1/governance/holds/{hold_id}")
+        return LegalHold.model_validate(resp.json())
+
+    def list_legal_holds(self, *, status: Optional[str] = None) -> list[LegalHold]:
+        """List all legal holds."""
+        resp = self._t.get("/api/v1/governance/holds", params={"status": status})
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", data.get("holds", []))
+        return [LegalHold.model_validate(h) for h in items]
+
+    def release_legal_hold(self, hold_id: UUID | str) -> LegalHold:
+        """Release (close) a legal hold."""
+        resp = self._t.post(f"/api/v1/governance/holds/{hold_id}/release")
+        return LegalHold.model_validate(resp.json())
+
+    def add_custodian(self, hold_id: UUID | str, *, user_id: str) -> dict[str, Any]:
+        """Add a custodian to a legal hold."""
+        resp = self._t.post(
+            f"/api/v1/governance/holds/{hold_id}/custodians",
+            json={"user_id": user_id},
+        )
+        return resp.json()
+
+    def place_document(self, hold_id: UUID | str, *, document_id: str) -> dict[str, Any]:
+        """Place a document under legal hold (prevents deletion)."""
+        resp = self._t.post(
+            f"/api/v1/governance/holds/{hold_id}/documents",
+            json={"document_id": document_id},
+        )
+        return resp.json()
+
+    def get_custody_chain(self, hold_id: UUID | str) -> list[dict[str, Any]]:
+        """Get HMAC-signed chain of custody logs."""
+        resp = self._t.get(f"/api/v1/governance/holds/{hold_id}/custody-chain")
+        data = resp.json()
+        return data if isinstance(data, list) else data.get("entries", [])
+
+    # -- eDiscovery ---------------------------------------------------------
+
+    def search(
+        self,
+        *,
+        query: str,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+        custodians: Optional[list[str]] = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """Run an eDiscovery search (boolean / proximity)."""
+        body: dict[str, Any] = {"query": query, "limit": limit}
+        if date_from is not None:
+            body["date_from"] = date_from
+        if date_to is not None:
+            body["date_to"] = date_to
+        if custodians is not None:
+            body["custodians"] = custodians
+        resp = self._t.post("/api/v1/ediscovery/search", json=body)
+        return resp.json()
+
+    def create_review_set(self, *, name: str, search_id: Optional[str] = None) -> dict[str, Any]:
+        """Create a review set for tagging and production."""
+        body: dict[str, Any] = {"name": name}
+        if search_id is not None:
+            body["search_id"] = search_id
+        resp = self._t.post("/api/v1/ediscovery/review-sets", json=body)
+        return resp.json()
+
+    # -- Records Management -------------------------------------------------
+
+    def list_retention_policies(self) -> list[RetentionPolicy]:
+        """List all retention policies."""
+        resp = self._t.get("/api/v1/governance/retention/policies")
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", data.get("policies", []))
+        return [RetentionPolicy.model_validate(p) for p in items]
+
+    def create_retention_policy(
+        self,
+        *,
+        name: str,
+        retention_days: int,
+        template: Optional[str] = None,
+    ) -> RetentionPolicy:
+        """Create a retention policy.
+
+        ``template`` can be ``HIPAA_6YR``, ``SOX_7YR``, ``GDPR_3YR``, ``IRS_7YR``.
+        """
+        body: dict[str, Any] = {"name": name, "retention_days": retention_days}
+        if template is not None:
+            body["template"] = template
+        resp = self._t.post("/api/v1/governance/retention/policies", json=body)
+        return RetentionPolicy.model_validate(resp.json())
+
+    def declare_record(self, document_id: UUID | str, *, policy_id: str) -> dict[str, Any]:
+        """Declare a document as a record under a retention policy."""
+        resp = self._t.post(
+            f"/api/v1/records/declare",
+            json={"policy_id": policy_id},
+        )
+        return resp.json()

documentors/documents.py

@@ -0,0 +1,118 @@
+"""Document operations — upload, list, get, delete, versions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, BinaryIO, Optional
+from uuid import UUID
+
+from ._transport import Transport
+from .models import Document, DocumentVersion, PaginatedResponse
+
+
+class Documents:
+    """``client.documents.*`` — CRUD and version management."""
+
+    _PREFIX = "/api/v1/documents"
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        search: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 50,
+    ) -> PaginatedResponse:
+        """List documents with optional filters."""
+        resp = self._t.get(
+            self._PREFIX,
+            params={"status": status, "search": search, "skip": skip, "limit": limit},
+        )
+        return PaginatedResponse.model_validate(resp.json())
+
+    def get(self, document_id: UUID | str) -> Document:
+        """Retrieve a single document by ID."""
+        resp = self._t.get(f"{self._PREFIX}/{document_id}")
+        return Document.model_validate(resp.json())
+
+    def upload(
+        self,
+        file: str | Path | BinaryIO,
+        *,
+        title: Optional[str] = None,
+        classification: Optional[str] = None,
+        project_id: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> Document:
+        """Upload a new document.
+
+        ``file`` may be a file path, or an open binary file object.
+        """
+        if isinstance(file, (str, Path)):
+            path = Path(file)
+            with open(path, "rb") as fh:
+                return self._do_upload(
+                    fh,
+                    filename=path.name,
+                    title=title,
+                    classification=classification,
+                    project_id=project_id,
+                    metadata=metadata,
+                )
+        return self._do_upload(
+            file,
+            filename=getattr(file, "name", "upload"),
+            title=title,
+            classification=classification,
+            project_id=project_id,
+            metadata=metadata,
+        )
+
+    def delete(self, document_id: UUID | str) -> None:
+        """Delete a document by ID."""
+        self._t.delete(f"{self._PREFIX}/{document_id}")
+
+    def versions(self, document_id: UUID | str) -> list[DocumentVersion]:
+        """List version history for a document."""
+        resp = self._t.get(f"{self._PREFIX}/{document_id}/versions")
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", data.get("versions", []))
+        return [DocumentVersion.model_validate(v) for v in items]
+
+    def download(self, document_id: UUID | str) -> bytes:
+        """Download the raw content of a document."""
+        resp = self._t.get(f"{self._PREFIX}/{document_id}/download")
+        return resp.content
+
+    # -- internal -----------------------------------------------------------
+
+    def _do_upload(
+        self,
+        fh: BinaryIO,
+        *,
+        filename: str,
+        title: Optional[str],
+        classification: Optional[str],
+        project_id: Optional[str],
+        metadata: Optional[dict[str, Any]],
+    ) -> Document:
+        form: dict[str, Any] = {}
+        if title is not None:
+            form["title"] = title
+        if classification is not None:
+            form["classification"] = classification
+        if project_id is not None:
+            form["project_id"] = project_id
+        if metadata is not None:
+            import json
+            form["metadata"] = json.dumps(metadata)
+
+        resp = self._t.post(
+            f"{self._PREFIX}/upload",
+            files={"file": (filename, fh)},
+            data=form,
+        )
+        return Document.model_validate(resp.json())

documentors/exceptions.py

@@ -0,0 +1,55 @@
+"""Exceptions raised by the DocumentorsClient SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class DocumentorsError(Exception):
+    """Base exception for all SDK errors."""
+
+    def __init__(self, message: str, *, details: Optional[dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.details = details or {}
+
+
+class AuthenticationError(DocumentorsError):
+    """Raised when authentication fails (401)."""
+
+
+class PermissionDeniedError(DocumentorsError):
+    """Raised when the caller lacks required scope or role (403)."""
+
+
+class NotFoundError(DocumentorsError):
+    """Raised when the requested resource does not exist (404)."""
+
+
+class ValidationError(DocumentorsError):
+    """Raised when request validation fails (422)."""
+
+
+class RateLimitError(DocumentorsError):
+    """Raised when rate limit is exceeded (429).
+
+    Attributes:
+        retry_after: Seconds until the caller may retry.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        *,
+        retry_after: Optional[int] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.retry_after = retry_after
+
+
+class ServerError(DocumentorsError):
+    """Raised on 5xx responses from the platform."""
+
+
+class ConflictError(DocumentorsError):
+    """Raised when the operation conflicts with current state (409)."""

documentors/models.py

@@ -0,0 +1,224 @@
+"""Pydantic response models for the DocuMentors API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Pagination envelope
+# ---------------------------------------------------------------------------
+
+class PaginatedResponse(BaseModel):
+    """Wrapper returned by paginated list endpoints."""
+
+    items: list[dict[str, Any]] = Field(default_factory=list)
+    total: int = 0
+    skip: int = 0
+    limit: int = 50
+
+
+# ---------------------------------------------------------------------------
+# Auth
+# ---------------------------------------------------------------------------
+
+class TokenUser(BaseModel):
+    email: str
+    full_name: Optional[str] = None
+    is_superuser: bool = False
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    expires_in: int = 900
+    user: Optional[TokenUser] = None
+
+
+# ---------------------------------------------------------------------------
+# Documents
+# ---------------------------------------------------------------------------
+
+class Document(BaseModel):
+    id: UUID
+    title: Optional[str] = None
+    filename: Optional[str] = None
+    status: Optional[str] = None
+    classification: Optional[str] = None
+    organization_id: Optional[UUID] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    file_size: Optional[int] = None
+    content_type: Optional[str] = None
+    version: Optional[int] = None
+
+
+class DocumentVersion(BaseModel):
+    id: UUID
+    document_id: UUID
+    version_number: int
+    created_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    change_summary: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# PII / Security
+# ---------------------------------------------------------------------------
+
+class PIIFinding(BaseModel):
+    type: str
+    confidence: float
+    start_offset: Optional[int] = None
+    end_offset: Optional[int] = None
+    masked_value: Optional[str] = None
+    risk_level: Optional[str] = None
+
+
+class ScanResult(BaseModel):
+    scan_id: UUID
+    document_id: UUID
+    status: str = "completed"
+    findings: list[PIIFinding] = Field(default_factory=list)
+    entity_count: Optional[int] = None
+    scanned_at: Optional[datetime] = None
+
+
+class ScanHistoryEntry(BaseModel):
+    scan_id: UUID
+    document_id: UUID
+    status: str
+    entity_count: Optional[int] = None
+    scanned_at: Optional[datetime] = None
+
+
+class PhishingVerdict(BaseModel):
+    is_phishing: bool
+    confidence: float
+    verdict: str = "legitimate"
+    signals: Optional[dict[str, float]] = None
+    threat_indicators: list[str] = Field(default_factory=list)
+
+
+class URLThreat(BaseModel):
+    url: str
+    is_threat: bool
+    confidence: float = 0.0
+    threat_type: Optional[str] = None
+    source: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Governance / Compliance
+# ---------------------------------------------------------------------------
+
+class LegalHold(BaseModel):
+    id: UUID
+    name: str
+    status: Optional[str] = None
+    description: Optional[str] = None
+    created_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    released_at: Optional[datetime] = None
+
+
+class RetentionPolicy(BaseModel):
+    id: UUID
+    name: str
+    retention_days: int
+    template: Optional[str] = None
+    status: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+# ---------------------------------------------------------------------------
+# Admin / Users
+# ---------------------------------------------------------------------------
+
+class User(BaseModel):
+    id: UUID
+    email: str
+    full_name: Optional[str] = None
+    is_active: bool = True
+    is_superuser: bool = False
+    organization_id: Optional[UUID] = None
+    org_role: Optional[str] = None
+    created_at: Optional[datetime] = None
+
+
+class APIKey(BaseModel):
+    id: UUID
+    api_key_prefix: str
+    name: str
+    is_active: bool = True
+    created_at: Optional[datetime] = None
+    last_used_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+    rate_limit_override: Optional[int] = None
+
+
+class APIKeyCreated(APIKey):
+    """Returned only on key creation — contains the one-time secret."""
+
+    api_key_secret: str
+
+
+# ---------------------------------------------------------------------------
+# Devices
+# ---------------------------------------------------------------------------
+
+class Device(BaseModel):
+    id: UUID
+    device_name: str
+    status: Optional[str] = None
+    activated_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+    last_seen_at: Optional[datetime] = None
+
+
+class ActivationCode(BaseModel):
+    id: UUID
+    code: Optional[str] = None
+    max_uses: int = 1
+    uses: int = 0
+    expires_at: Optional[datetime] = None
+    created_at: Optional[datetime] = None
+
+
+# ---------------------------------------------------------------------------
+# Org Members
+# ---------------------------------------------------------------------------
+
+class OrgMember(BaseModel):
+    id: int
+    organization_id: UUID
+    user_id: int
+    role: str
+    department_id: Optional[UUID] = None
+    is_active: bool = True
+    joined_at: Optional[datetime] = None
+    last_active_at: Optional[datetime] = None
+    user_email: str = ""
+    user_username: str = ""
+    user_full_name: Optional[str] = None
+    department_name: Optional[str] = None
+    documents_count: int = 0
+    projects_count: int = 0
+
+
+class OrgInvitation(BaseModel):
+    id: int
+    organization_id: UUID
+    organization_name: str = ""
+    email: str
+    role: str = "member"
+    department_id: Optional[UUID] = None
+    invited_by_id: int
+    invited_by_name: str = ""
+    status: str  # pending, accepted, declined, expired
+    invited_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None

documentors/security.py

@@ -0,0 +1,132 @@
+"""Security operations — PII detection, phishing analysis, redaction."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from uuid import UUID
+
+from ._transport import Transport
+from .models import PhishingVerdict, PIIFinding, ScanHistoryEntry, ScanResult, URLThreat
+
+
+class Security:
+    """``client.security.*`` — PII scanning, phishing detection, redaction."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    # -- PII scanning -------------------------------------------------------
+
+    def detect_pii(
+        self,
+        document_id: UUID | str,
+        *,
+        min_confidence: float = 0.70,
+    ) -> ScanResult:
+        """Trigger a PII scan on a document. Returns findings."""
+        resp = self._t.post(
+            f"/api/v1/documents/{document_id}/scan",
+            json={"min_confidence": min_confidence},
+        )
+        return ScanResult.model_validate(resp.json())
+
+    def get_scan_results(
+        self,
+        document_id: UUID | str,
+        *,
+        scan_id: Optional[UUID | str] = None,
+    ) -> ScanResult:
+        """Retrieve results for a specific (or latest) scan."""
+        params: dict[str, Any] = {}
+        if scan_id is not None:
+            params["scan_id"] = str(scan_id)
+        resp = self._t.get(f"/api/v1/documents/{document_id}/scan-results", params=params)
+        return ScanResult.model_validate(resp.json())
+
+    def scan_history(self, document_id: UUID | str) -> list[ScanHistoryEntry]:
+        """List past scans for a document."""
+        resp = self._t.get(f"/api/v1/documents/{document_id}/scan-history")
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("items", [])
+        return [ScanHistoryEntry.model_validate(e) for e in items]
+
+    def redact_pii(
+        self,
+        document_id: UUID | str,
+        *,
+        strategy: str = "MASK",
+        entity_types: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """Apply redaction to detected PII entities.
+
+        ``strategy`` can be ``MASK``, ``REPLACE``, or ``REMOVE``.
+        """
+        body: dict[str, Any] = {"strategy": strategy}
+        if entity_types is not None:
+            body["entity_types"] = entity_types
+        resp = self._t.post(f"/api/v1/documents/{document_id}/redact", json=body)
+        return resp.json()
+
+    # -- Phishing detection -------------------------------------------------
+
+    def analyze_email(
+        self,
+        *,
+        email_content: str,
+        sender: str,
+        recipient: str,
+        subject: str,
+        headers: Optional[dict[str, str]] = None,
+    ) -> PhishingVerdict:
+        """Analyze a single email for phishing indicators."""
+        body: dict[str, Any] = {
+            "email_content": email_content,
+            "sender": sender,
+            "recipient": recipient,
+            "subject": subject,
+        }
+        if headers is not None:
+            body["headers"] = headers
+        resp = self._t.post("/api/v1/phishing/analyze/email", json=body)
+        return PhishingVerdict.model_validate(resp.json())
+
+    def analyze_emails(
+        self,
+        emails: list[dict[str, Any]],
+    ) -> list[PhishingVerdict]:
+        """Batch-analyze up to 50 emails."""
+        resp = self._t.post("/api/v1/phishing/analyze/email/batch", json={"emails": emails})
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("results", [])
+        return [PhishingVerdict.model_validate(v) for v in items]
+
+    def analyze_url(self, url: str) -> URLThreat:
+        """Check a single URL against threat intelligence."""
+        resp = self._t.post("/api/v1/phishing/analyze/url", json={"url": url})
+        return URLThreat.model_validate(resp.json())
+
+    def analyze_urls(self, urls: list[str]) -> list[URLThreat]:
+        """Batch-check up to 200 URLs."""
+        resp = self._t.post("/api/v1/phishing/analyze/urls", json={"urls": urls})
+        data = resp.json()
+        items = data if isinstance(data, list) else data.get("results", [])
+        return [URLThreat.model_validate(t) for t in items]
+
+    def check_domain(self, domain: str) -> dict[str, Any]:
+        """Get domain reputation information."""
+        resp = self._t.get("/api/v1/phishing/analyze/domain", params={"domain": domain})
+        return resp.json()
+
+    def submit_feedback(
+        self,
+        *,
+        verdict_id: str,
+        is_correct: bool,
+        notes: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Submit false-positive / false-negative feedback."""
+        body: dict[str, Any] = {"verdict_id": verdict_id, "is_correct": is_correct}
+        if notes is not None:
+            body["notes"] = notes
+        resp = self._t.post("/api/v1/phishing/feedback", json=body)
+        return resp.json()