dcr-client 0.4.3__py3-none-any.whl

dcr_client/__init__.py

@@ -0,0 +1,138 @@
+"""DCR Platform Python SDK.
+
+Usage::
+
+    from dcr_client import DCRClient
+
+    client = DCRClient(
+        base_url="http://localhost:8000",
+        username="admin@example.com",
+        password="secret",
+        tenant_id="your-tenant-uuid",
+    )
+"""
+
+from dcr_client.client import DCRClient
+from dcr_client.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DCRError,
+    ForbiddenError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from dcr_client.hashing import (
+    hash_identifier,
+    hash_identifier_legacy,
+    hash_activation_key,
+    hash_activation_key_for_platforms,
+    verify_hash_format,
+)
+from dcr_client.normalize import (
+    normalize_email,
+    normalize_phone,
+    normalize_name,
+    normalize_identifier,
+    normalize_for_platform,
+    SUPPORTED_PLATFORMS,
+)
+from dcr_client.prepare import prepare_csv
+from dcr_client.encrypt import encrypt_csv, encrypt_rows, EncryptResult
+from dcr_client.models import (
+    AIQueryUsageResponse,
+    AIStatusResponse,
+    AlertHistoryEntry,
+    AlertRule,
+    AnalyzeResponse,
+    BulkUploadResult,
+    ChunkUploadResult,
+    CompileIRResponse,
+    Dataset,
+    DictionaryStatusResponse,
+    DSRRequest,
+    DUA,
+    Job,
+    MatchResult,
+    Notification,
+    QueryAIResponse,
+    QueryResult,
+    RecommendationResponse,
+    RecommendedQuery,
+    ReportRun,
+    ReportTemplate,
+    RetentionPolicy,
+    Room,
+    TextToSQLResponse,
+    TokenResponse,
+    Upload,
+    UserInfo,
+    WebhookSubscription,
+)
+
+__version__ = "0.4.3"
+SDK_VERSION = __version__
+
+__all__ = [
+    # Client
+    "DCRClient",
+    "SDK_VERSION",
+    # Exceptions
+    "DCRError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "ServerError",
+    # AI Models
+    "QueryAIResponse",
+    "CompileIRResponse",
+    "TextToSQLResponse",
+    "AnalyzeResponse",
+    "AIStatusResponse",
+    "AIQueryUsageResponse",
+    "DictionaryStatusResponse",
+    "RecommendedQuery",
+    "RecommendationResponse",
+    # Models
+    "TokenResponse",
+    "UserInfo",
+    "Upload",
+    "BulkUploadResult",
+    "ChunkUploadResult",
+    "Dataset",
+    "Room",
+    "MatchResult",
+    "Job",
+    "QueryResult",
+    "DUA",
+    "ReportTemplate",
+    "ReportRun",
+    "AlertRule",
+    "AlertHistoryEntry",
+    "RetentionPolicy",
+    "WebhookSubscription",
+    "DSRRequest",
+    "Notification",
+    # Normalization & Hashing
+    "normalize_email",
+    "normalize_phone",
+    "normalize_name",
+    "normalize_identifier",
+    "normalize_for_platform",
+    "SUPPORTED_PLATFORMS",
+    "hash_identifier",
+    "hash_identifier_legacy",
+    "hash_activation_key",
+    "hash_activation_key_for_platforms",
+    "verify_hash_format",
+    "prepare_csv",
+    "encrypt_csv",
+    "encrypt_rows",
+    "EncryptResult",
+]

dcr_client/_http.py

@@ -0,0 +1,475 @@
+"""Internal HTTP wrapper with retry, envelope unwrapping, and error mapping."""
+
+from __future__ import annotations
+
+import json as _json
+import logging
+from typing import Any, Optional
+from urllib.parse import urlsplit
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+logger = logging.getLogger("dcr_client")
+
+_SDK_VERSION = "0.4.3"
+
+from dcr_client.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DCRError,
+    ForbiddenError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_STATUS_MAP: dict[int, type[DCRError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+class _APIKeyAdapter(HTTPAdapter):
+    """The adapter of the API key endpoints: a key's create and rotate on the
+    no-POST-retry policy it is built with, a key's revoke (``.../revoke``) on
+    the policy every other endpoint has. Revoking twice ends in the same
+    state, so a 502/503/504 of a rolling deploy is retried for it; a create
+    or rotate retried after a commit whose answer was lost would issue a
+    second key."""
+
+    #: The last path segment of a key's revoke.
+    REVOKE_SUFFIX = "/revoke"
+
+    def __init__(self, issue_retries: Retry, revoke_retries: Retry) -> None:
+        super().__init__(max_retries=issue_retries)
+        self._revoke = HTTPAdapter(max_retries=revoke_retries)
+
+    def adapter_for(self, url: str) -> HTTPAdapter:
+        """The adapter that sends a request to ``url``."""
+        if urlsplit(url).path.rstrip("/").endswith(self.REVOKE_SUFFIX):
+            return self._revoke
+        return self
+
+    def send(self, request, **kwargs):  # type: ignore[no-untyped-def]
+        target = self.adapter_for(request.url or "")
+        if target is self:
+            return super().send(request, **kwargs)
+        return target.send(request, **kwargs)
+
+    def close(self) -> None:
+        self._revoke.close()
+        super().close()
+
+
+class _CompileAdapter(HTTPAdapter):
+    """The adapter of the IR run (``/api/v1/query/ai/compile``): a run sent
+    with an AI answer's ``credit_ref`` on the no-POST-retry policy it is built
+    with, any other run on the policy every other endpoint has.
+
+    The query engine gives the answer's credits back when it refuses the run
+    of that plan — a 503 while the room's overlap is refreshed
+    (QUERY_UNAVAILABLE_013) as much as any other refusal. It charges them
+    again once a later run of the plan is accepted, so a retry the caller did
+    not see would run the plan and charge it unseen once the 503 lifted: the
+    caller sees the 503 and decides whether to send the run again. A 502, 503
+    or 504 the gateway answers itself (the engine never saw the run, as while
+    its pods restart) gives nothing back and is not retried either: the caller
+    sends the run again with the same ``credit_ref``, which the engine judges
+    as new. A run without a reference keeps the retry of a 503 a retry can
+    lift."""
+
+    def __init__(self, referenced_retries: Retry, other_retries: Retry) -> None:
+        super().__init__(max_retries=referenced_retries)
+        self._other = HTTPAdapter(max_retries=other_retries)
+
+    @staticmethod
+    def carries_credit_ref(body: Any) -> bool:
+        """Whether a request body is a JSON object naming a ``credit_ref``."""
+        if not body:
+            return False
+        try:
+            payload = _json.loads(body)
+        except (TypeError, ValueError):
+            return False
+        return isinstance(payload, dict) and bool(payload.get("credit_ref"))
+
+    def adapter_for(self, body: Any) -> HTTPAdapter:
+        """The adapter that sends a run whose body is ``body``."""
+        if self.carries_credit_ref(body):
+            return self
+        return self._other
+
+    def send(self, request, **kwargs):  # type: ignore[no-untyped-def]
+        target = self.adapter_for(request.body)
+        if target is self:
+            return super().send(request, **kwargs)
+        return target.send(request, **kwargs)
+
+    def close(self) -> None:
+        self._other.close()
+        super().close()
+
+
+class HTTPClient:
+    """Low-level HTTP client that wraps ``requests.Session``.
+
+    Features:
+    - Automatic retry on 502/503/504 (3 attempts with backoff). A response
+      that carries ``Retry-After`` is retried after the time it names: the
+      query engine sends one with a 503 a retry can lift — the room's overlap
+      is being refreshed, or could not be checked (QUERY_UNAVAILABLE_013) —
+      so a retry waits for it instead of asking again at once.
+    - The AI endpoints (``/api/v1/ai/``) are not retried on a status, nor on
+      a read error after the request was sent: each call is charged and runs a
+      provider call, and their 503 is the AI provider failing
+      (AI_UNAVAILABLE_001 / AI_UNAVAILABLE_003), which three retries in three
+      seconds do not lift: each retry would be charged, call the provider and
+      be refunded again. A connection that never reached the server is still
+      retried.
+    - A key's create and rotate (``POST`` under
+      ``/api/v1/auth/org/api-keys``) are not retried on a status, nor on a
+      read error after the request was sent: their 503 (AUTH_UNAVAILABLE_002)
+      and 504 can come after a commit whose answer was lost, so the key may
+      have been saved, and an unseen retry could issue a second key or rotate
+      the deprecated one again. The caller lists the keys and decides. A key's
+      revoke is retried as everywhere (revoking twice ends in the same state),
+      and so are listing and reading keys (``GET``); a connection that never
+      reached the server is still retried.
+    - The IR run (``/api/v1/query/ai/compile``) sent with an AI answer's
+      ``credit_ref`` is not retried on a status, nor on a read error after the
+      request was sent: a refusal of that plan's run, its 503 included, gives
+      the answer's credits back and a later accepted run charges them again,
+      so a retry the caller did not see would run the plan and charge it
+      unseen once the refusal lifted. A run without a reference keeps every
+      endpoint's policy.
+    - When the retries run out, the last response is raised as its typed
+      :class:`DCRError` (a :class:`ServerError` carrying the platform's
+      ``error_code``), not as urllib3's untyped ``RetryError``.
+    - Unwraps the DCR ``{"success": true, "data": ...}`` envelope.
+    - Maps HTTP error codes to typed :class:`DCRError` subclasses.
+    """
+
+    #: Path prefix of the AI endpoints, mounted on an adapter of their own.
+    AI_PATH_PREFIX = "/api/v1/ai/"
+
+    #: Path of the IR run, mounted on an adapter of its own
+    #: (:class:`_CompileAdapter`): a run that carries an AI answer's
+    #: ``credit_ref`` is not retried on a status.
+    AI_COMPILE_PATH = "/api/v1/query/ai/compile"
+
+    #: Path prefix of the API key endpoints, mounted on an adapter of their own
+    #: (:class:`_APIKeyAdapter`): a POST under it issues, rotates or revokes a
+    #: key.
+    API_KEYS_PATH_PREFIX = "/api/v1/auth/org/api-keys"
+
+    def __init__(self, base_url: str, timeout: float = 30.0, api_version: str | None = None) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._token: Optional[str] = None
+        self._tenant_id: Optional[str] = None
+        self._api_key: Optional[str] = None
+        self._api_version = api_version
+        self._server_api_version: str | None = None
+
+        self._session = requests.Session()
+
+        retry_strategy = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=[502, 503, 504],
+            allowed_methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self._session.mount("http://", adapter)
+        self._session.mount("https://", adapter)
+
+        # The AI endpoints: a request that never reached the server is
+        # retried for every method; a 502/503/504 or a read error only for a
+        # GET (status, usage, a dictionary's status: no charge and no
+        # provider call). A POST is charged and calls the AI provider, so a
+        # retry would be charged, call the provider and be refunded again; a
+        # GET that a rolling deploy answered 503 once is asked again, as on
+        # every other endpoint. urllib3 applies read and status retries only
+        # to allowed_methods. requests picks the longest mounted prefix, so
+        # this adapter serves every URL under it.
+        ai_retry_strategy = Retry(
+            total=3,
+            connect=3,
+            read=3,
+            status=3,
+            other=0,
+            backoff_factor=0.5,
+            status_forcelist=[502, 503, 504],
+            allowed_methods=["GET"],
+            raise_on_status=False,
+        )
+        self._session.mount(self._base_url + self.AI_PATH_PREFIX, HTTPAdapter(max_retries=ai_retry_strategy))
+
+        # The IR run: sent with an AI answer's credit_ref it is on the AI
+        # endpoints' rule (no status or read retry of a POST), since a refusal
+        # of the run — a 503 a retry can lift included — gave the answer's
+        # credits back, and a later accepted run charges them again: a retry
+        # the caller did not see would run and charge it unseen. Without one
+        # it keeps every endpoint's policy.
+        self._session.mount(self._base_url + self.AI_COMPILE_PATH, _CompileAdapter(ai_retry_strategy, retry_strategy))
+
+        # The API key endpoints, on the same rule as the AI ones: a create or
+        # rotate is retried only when it never reached the server. Answered
+        # 503/504 it may have committed (the platform's message says to check
+        # the key list), so a retry the caller does not see could issue a
+        # second key, or rotate the now deprecated key again and re-time its
+        # grace. A GET (list, get, scopes) is retried, and a revoke keeps every
+        # endpoint's policy.
+        key_retry_strategy = Retry(
+            total=3,
+            connect=3,
+            read=3,
+            status=3,
+            other=0,
+            backoff_factor=0.5,
+            status_forcelist=[502, 503, 504],
+            allowed_methods=["GET"],
+            raise_on_status=False,
+        )
+        self._session.mount(self._base_url + self.API_KEYS_PATH_PREFIX, _APIKeyAdapter(key_retry_strategy, retry_strategy))
+
+    # ------------------------------------------------------------------
+    # Auth helpers
+    # ------------------------------------------------------------------
+
+    def set_auth(self, token: str, tenant_id: Optional[str] = None) -> None:
+        """Store the access token and optional tenant ID for subsequent requests."""
+        self._token = token
+        if tenant_id is not None:
+            self._tenant_id = tenant_id
+
+    def set_tenant(self, tenant_id: str) -> None:
+        """Update only the tenant ID."""
+        self._tenant_id = tenant_id
+
+    def set_api_key(self, key: str) -> None:
+        """Store an API key for use in the ``Authorization: ApiKey`` header.
+
+        When an API key is set it takes precedence over any Bearer token.
+        """
+        self._api_key = key
+
+    # ------------------------------------------------------------------
+    # Header construction
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+        }
+        if self._api_key:
+            headers["Authorization"] = f"ApiKey {self._api_key}"
+        elif self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        if self._tenant_id:
+            headers["X-Tenant-ID"] = self._tenant_id
+        headers["User-Agent"] = f"dcr-python-sdk/{_SDK_VERSION}"
+        if self._api_version:
+            headers["X-API-Version"] = self._api_version
+        return headers
+
+    # ------------------------------------------------------------------
+    # Deprecation & version tracking
+    # ------------------------------------------------------------------
+
+    def _check_deprecation_headers(self, resp: requests.Response) -> None:
+        """Log deprecation and version mismatch warnings from response headers."""
+        warning = resp.headers.get("X-API-Deprecation-Warning")
+        if warning:
+            sunset = resp.headers.get("Sunset", "unknown")
+            logger.warning("[DCR] Endpoint deprecated: %s (Sunset: %s)", warning, sunset)
+
+        version_warning = resp.headers.get("X-API-Version-Warning")
+        if version_warning:
+            logger.warning("[DCR] API version mismatch: %s", version_warning)
+
+        server_version = resp.headers.get("X-API-Version")
+        if server_version:
+            self._server_api_version = server_version
+
+    @property
+    def server_api_version(self) -> str | None:
+        """The API version reported by the server in the last response."""
+        return self._server_api_version
+
+    # ------------------------------------------------------------------
+    # Error handling
+    # ------------------------------------------------------------------
+
+    def _handle_error(self, resp: requests.Response) -> None:
+        """Raise a typed :class:`DCRError` based on the HTTP status code."""
+        if resp.ok:
+            return
+
+        # Try to extract structured error info from the response body.
+        message = resp.reason or "Unknown error"
+        error_code = ""
+        try:
+            body = resp.json()
+            if isinstance(body, dict):
+                # Format 1: {"success": false, "error": {"code": "...", "message": "..."}}
+                if "error" in body and isinstance(body["error"], dict):
+                    error_obj = body["error"]
+                    message = error_obj.get("message", message)
+                    error_code = error_obj.get("code", "")
+                # Format 2: {"error_code": "...", "message": "..."}
+                elif "message" in body:
+                    message = body["message"]
+                    error_code = body.get("error_code", "")
+        except (ValueError, KeyError):
+            # Body wasn't valid JSON, or didn't carry the envelope keys
+            # we look for. Keep the upstream status-code-derived `message`
+            # value so the eventual exception still has something useful.
+            pass
+
+        status = resp.status_code
+
+        # 5xx → ServerError
+        if status >= 500:
+            raise ServerError(message, status_code=status, error_code=error_code)
+
+        exc_cls = _STATUS_MAP.get(status, DCRError)
+        raise exc_cls(message, status_code=status, error_code=error_code)
+
+    # ------------------------------------------------------------------
+    # Envelope unwrapping
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _unwrap(data: Any) -> Any:
+        """Unwrap the DCR API envelope.
+
+        The backend wraps successful responses as::
+
+            {"success": true, "data": <payload>, "meta": {...}}
+
+        This helper returns the inner ``data`` value when the envelope is
+        detected; otherwise the raw value is returned untouched.
+        """
+        if isinstance(data, dict) and data.get("success") is True and "data" in data:
+            return data["data"]
+        return data
+
+    # ------------------------------------------------------------------
+    # HTTP verbs
+    # ------------------------------------------------------------------
+
+    def _url(self, path: str) -> str:
+        if path.startswith("/"):
+            return f"{self._base_url}{path}"
+        return f"{self._base_url}/{path}"
+
+    def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """Perform a GET request and return the unwrapped JSON body."""
+        resp = self._session.get(
+            self._url(path),
+            headers=self._headers(),
+            params=params,
+            timeout=self._timeout,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        if not resp.content:
+            return None
+        return self._unwrap(resp.json())
+
+    def post(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        files: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        """Perform a POST request and return the unwrapped JSON body."""
+        headers = self._headers()
+        # When uploading files, let requests set the Content-Type with boundary.
+        if files is not None:
+            headers.pop("Content-Type", None)
+
+        resp = self._session.post(
+            self._url(path),
+            headers=headers,
+            json=json if files is None and data is None else None,
+            data=data,
+            files=files,
+            timeout=timeout or self._timeout,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        if not resp.content:
+            return None
+        return self._unwrap(resp.json())
+
+    def put(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        """Perform a PUT request and return the unwrapped JSON body."""
+        resp = self._session.put(
+            self._url(path),
+            headers=self._headers(),
+            json=json,
+            timeout=self._timeout,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        if not resp.content:
+            return None
+        return self._unwrap(resp.json())
+
+    def patch(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        """Perform a PATCH request and return the unwrapped JSON body."""
+        resp = self._session.patch(
+            self._url(path),
+            headers=self._headers(),
+            json=json,
+            timeout=self._timeout,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        if not resp.content:
+            return None
+        return self._unwrap(resp.json())
+
+    def delete(self, path: str) -> Any:
+        """Perform a DELETE request and return the unwrapped JSON body."""
+        resp = self._session.delete(
+            self._url(path),
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        if not resp.content:
+            return None
+        return self._unwrap(resp.json())
+
+    def get_stream(self, path: str, params: Optional[dict[str, Any]] = None) -> requests.Response:
+        """Perform a streaming GET request and return the raw Response.
+
+        The caller is responsible for iterating over the response.
+        """
+        resp = self._session.get(
+            self._url(path),
+            headers=self._headers(),
+            params=params,
+            timeout=self._timeout,
+            stream=True,
+        )
+        self._check_deprecation_headers(resp)
+        self._handle_error(resp)
+        return resp