apphelm 0.5.0__py3-none-any.whl

apphelm-0.5.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: apphelm
+Version: 0.5.0
+Summary: Official Python server SDK for Apphelm: events, identify, fail-closed feature flags, errors and tracing.
+Project-URL: Homepage, https://apphelm.dev
+Project-URL: Documentation, https://apphelm.dev/docs
+Author-email: SansaVision <support@sansavision.com>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Keywords: analytics,apphelm,error-monitoring,feature-flags,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Apphelm Python SDK
+
+The official Python client for [Apphelm](https://apphelm.dev), for server-side code: product
+events, identify, fail-closed feature flags, error and message reporting, cron check-ins and
+tracing. One module, standard library only, Python 3.10 or later.
+
+```bash
+pip install apphelm
+```
+
+Use a server API key (`ahl_…`) from your Apphelm workspace and keep it secret. Never ship it in
+a browser or mobile app.
+
+```py
+import os
+from apphelm import Apphelm
+
+apphelm = Apphelm(api_key=os.environ["APPHELM_API_KEY"])
+
+# A product event for one person.
+apphelm.capture("org_…", "prd_…", distinct_id=customer.id, event_name="invoice_sent")
+
+# Feature flags fail closed: any network, timeout or API error evaluates to False.
+if apphelm.is_enabled("new-checkout", customer.id, product_id="prd_…"):
+    render_new_checkout()
+variant = apphelm.get_feature_flag("org_…", "prd_…", "pricing-test", customer.id)  # variant, True or False
+```
+
+## Identify
+
+Every trait needs provenance. A trait without a matching `trait_sources` entry raises
+`ValueError` before anything is sent, because the API would reject it.
+
+```py
+apphelm.identify("org_…", "prd_…", external_user_id=account.id,
+                 traits={"plan": "builder"},
+                 trait_sources={"plan": {"sourceType": "auth", "sourceId": "session", "verification": "integration_verified"}})
+```
+
+## Errors and messages
+
+```py
+try:
+    charge(order)
+except Exception as error:
+    apphelm.capture_exception("org_…", "prd_…", error, release=os.environ.get("RELEASE"),
+                              environment="production", tags={"route": "/charges"}, user_id=account.id)
+
+# Report uncaught exceptions (main thread and other threads) as unhandled issues.
+# The previous hooks still run, so the traceback prints and the process exits as before.
+restore = apphelm.capture_unhandled("org_…", "prd_…", release=os.environ.get("RELEASE"), environment="production")
+
+apphelm.capture_message("org_…", "prd_…", "Payment provider fell back to retries", level="warning")
+```
+
+Tracebacks are scrubbed of email addresses, keys and query strings before they are sent, and
+`user_id` is sent only as a hash. Pass `before_send=` to the constructor to change or drop
+exceptions and messages: return the properties (changed or not), or `None` to drop the event. A
+hook that raises drops the event.
+
+## Tracing
+
+```py
+# Continue the caller's trace (from the browser or another service), or start a new one.
+with apphelm.start_transaction("org_…", "prd_…", "POST /charges", traceparent=request.headers.get("traceparent")) as tx:
+    with tx.start_span("db.query", "select order"):
+        ...
+```
+
+`Apphelm(api_key, traces_sample_rate=0.2)` keeps a share of new transactions; a transaction that
+continues an incoming `traceparent` keeps the caller's sampling decision.
+
+## Cron check-ins
+
+```py
+apphelm.check_in("prd_…", monitor="nightly-export", status="ok", duration_ms=5400)
+```
+
+## Errors from the client
+
+Failed requests raise `ApphelmError` with `status` and `code`. Flag checks (`is_enabled`,
+`get_feature_flag`) never raise for a failed request; they return `False`.
+
+## Licence
+
+Proprietary. See `LICENSE`: use requires an active Apphelm service agreement.
+
+Releasing this package: `docs/SDK-RELEASING.md` in the Apphelm repository.

apphelm-0.5.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+apphelm.py,sha256=PyRFeTzIjEP86ZRlIDSXI-v5ES9sSN2b-K9HWMo1uqU,24128
+apphelm-0.5.0.dist-info/METADATA,sha256=5XOHhsuIfpiBpmiudySjNYN0JUuF-VfQx2h_dwN2bRY,4169
+apphelm-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+apphelm-0.5.0.dist-info/licenses/LICENSE,sha256=SqrJtXJHUj3W671E2qinl87jGgbbmqwecIe1VawmUwQ,256
+apphelm-0.5.0.dist-info/RECORD,,

apphelm-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

apphelm-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+Copyright 2026 SansaVision. All rights reserved.
+
+This package may be used only under an active Apphelm service agreement. Redistribution, sublicensing, and reverse engineering are prohibited except where applicable law does not permit those restrictions.

apphelm.py

@@ -0,0 +1,467 @@
+"""Apphelm Python client. Server-side capture, identify, and fail-closed flag evaluation.
+
+Requires Python 3.10+. No third-party dependencies (stdlib only).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import random
+import re
+import sys
+import time
+import threading
+import traceback
+import uuid
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Sequence
+
+__version__ = "0.5.0"
+
+
+def _scrub_stack(stack: str) -> str:
+    """Keep frames useful for grouping without sending emails, keys or query strings."""
+    lines = []
+    for line in stack.splitlines()[-20:]:
+        line = re.sub(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}", "[email]", line)
+        line = re.sub(r"ahl_[A-Za-z0-9._:-]{8,160}", "[key]", line)
+        line = re.sub(r"\?[^\s)\"]*", "", line)
+        lines.append(line.rstrip()[:200])
+    return "\n".join(lines)[:2000]
+
+
+class ApphelmError(Exception):
+    def __init__(self, message: str, status: int = 0, code: str = "request_failed"):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+@dataclass
+class FlagEvaluation:
+    key: str
+    enabled: bool
+    variant: Optional[str]
+    payload: Any
+    reason: str
+
+
+_TRACEPARENT = re.compile(r"^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$")
+_MAX_SPANS = 50
+
+
+class Span:
+    """A timed piece of work inside a transaction (a query, an outgoing call). Use it as a
+    context manager, or call ``finish``; an exception inside the ``with`` marks it an error."""
+
+    def __init__(self, transaction: "Transaction", op: str, description: Optional[str]):
+        self.span_id = os.urandom(8).hex()
+        self._transaction = transaction
+        self._op = op
+        self._description = description[:200] if description else None
+        self._start = time.monotonic()
+        self._finished = False
+
+    def finish(self, status: str = "ok") -> None:
+        if self._finished:
+            return
+        self._finished = True
+        self._transaction._add_span({
+            "span_id": self.span_id, "parent_span_id": self._transaction.span_id, "op": self._op,
+            **({"description": self._description} if self._description else {}),
+            "start_offset_ms": round((self._start - self._transaction._start) * 1000),
+            "duration_ms": round((time.monotonic() - self._start) * 1000),
+            "status": "error" if status == "error" else "ok",
+        })
+
+    def __enter__(self) -> "Span":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self.finish("error" if exc_type is not None else "ok")
+        return False
+
+
+class Transaction:
+    """A sampled unit of work (a request, a job) with up to 50 child spans, sent as one
+    ``$transaction`` event when it finishes. Unsampled transactions send nothing. Pass
+    ``traceparent()`` to services you call so their work joins the same trace, and link
+    errors with ``capture_exception(..., trace_id=transaction.trace_id)``."""
+
+    def __init__(self, client: "Apphelm", workspace_id: str, product_id: str, name: str, op: str,
+                 trace_id: str, parent_span_id: Optional[str], sampled: bool,
+                 release: Optional[str], environment: Optional[str]):
+        self.trace_id = trace_id
+        self.span_id = os.urandom(8).hex()
+        self.sampled = sampled
+        self._client = client
+        self._scope = (workspace_id, product_id)
+        self._name = name[:200]
+        self._op = op
+        self._parent = parent_span_id
+        self._release = release
+        self._environment = environment
+        self._started_at = datetime.now(timezone.utc)
+        self._start = time.monotonic()
+        self._spans: list[dict] = []
+        self._lock = threading.Lock()
+        self._finished = False
+
+    def _add_span(self, span: dict) -> None:
+        with self._lock:
+            if len(self._spans) < _MAX_SPANS:
+                self._spans.append(span)
+
+    def start_span(self, op: str, description: Optional[str] = None) -> Span:
+        return Span(self, op, description)
+
+    def traceparent(self) -> str:
+        """A W3C ``traceparent`` header value that continues this trace in another service."""
+        return f"00-{self.trace_id}-{self.span_id}-{'01' if self.sampled else '00'}"
+
+    def finish(self, status: str = "ok") -> Optional[dict]:
+        """Send the transaction once. A failed send never raises: telemetry must not break the
+        work it measures."""
+        if self._finished or not self.sampled:
+            self._finished = True
+            return None
+        self._finished = True
+        properties: dict[str, Any] = {
+            "trace_id": self.trace_id, "span_id": self.span_id, "name": self._name, "op": self._op,
+            "status": "error" if status == "error" else "ok",
+            "started_at": self._started_at.isoformat().replace("+00:00", "Z"),
+            "duration_ms": round((time.monotonic() - self._start) * 1000),
+            "spans": json.dumps(self._spans),
+        }
+        if self._parent:
+            properties["parent_span_id"] = self._parent
+        if self._release:
+            properties["release"] = str(self._release)[:120]
+        if self._environment:
+            properties["environment"] = str(self._environment)[:40]
+        try:
+            return self._client.ingest(self._scope[0], self._scope[1], "$transaction", properties)
+        except ApphelmError:
+            return None
+
+    def __enter__(self) -> "Transaction":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        self.finish("error" if exc_type is not None else "ok")
+        return False
+
+
+class Apphelm:
+    def __init__(self, api_key: str, base_url: str = "https://apphelm.dev", timeout_seconds: float = 10.0,
+                 traces_sample_rate: float = 1.0,
+                 before_send: Optional[Callable[[dict], Optional[dict]]] = None):
+        """``traces_sample_rate`` (0-1, default 1) is the share of transactions started here
+        that are kept; a transaction continuing an incoming ``traceparent`` keeps the caller's
+        decision instead.
+
+        ``before_send`` is called with each exception's and message's properties before they
+        are sent (after the client's own scrubbing). Return them, changed or not, or ``None``
+        to drop the event. If it raises, the event is dropped: a scrubbing hook that fails
+        must not let data through. The server scrubs again either way."""
+        if not api_key:
+            raise TypeError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout_seconds
+        self._traces_sample_rate = min(1.0, max(0.0, float(traces_sample_rate)))
+        self._before_send = before_send
+        self._exposed: set[tuple[str, str, str, str]] = set()
+
+    def _send_error(self, workspace_id: str, product_id: str, properties: dict) -> dict:
+        """Exceptions and messages go through ``before_send`` first. A dropped event returns
+        ``{"accepted": False, "dropped": True}`` without a request."""
+        if self._before_send is not None:
+            try:
+                kept = self._before_send(properties)
+            except Exception:  # noqa: BLE001 - a failing hook drops the event
+                kept = None
+            if kept is None:
+                return {"accepted": False, "dropped": True}
+            properties = kept
+        return self.ingest(workspace_id, product_id, "$exception", properties)
+
+    def start_transaction(self, workspace_id: str, product_id: str, name: str, op: str = "http.server",
+                          traceparent: Optional[str] = None, release: Optional[str] = None,
+                          environment: Optional[str] = None) -> Transaction:
+        """Start a transaction, as a context manager or finished with ``finish()``. Pass an
+        incoming ``traceparent`` header to continue a trace from another service (a browser
+        page load, a Node service); its sampling decision is kept."""
+        parent = _TRACEPARENT.match((traceparent or "").strip())
+        if parent:
+            trace_id, parent_span_id, sampled = parent.group(1), parent.group(2), (int(parent.group(3), 16) & 1) == 1
+        else:
+            trace_id, parent_span_id, sampled = os.urandom(16).hex(), None, random.random() < self._traces_sample_rate
+        return Transaction(self, workspace_id, product_id, name, op, trace_id, parent_span_id, sampled, release, environment)
+
+    def _request(self, path: str, body: Optional[dict] = None) -> Any:
+        request = urllib.request.Request(
+            f"{self._base_url}/api/v1{path}",
+            data=json.dumps(body or {}).encode("utf-8") if body is not None else None,
+            headers={
+                "accept": "application/json",
+                "authorization": f"Bearer {self._api_key}",
+                "content-type": "application/json",
+            },
+            method="POST" if body is not None else "GET",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                payload = response.read().decode("utf-8") or "{}"
+                try:
+                    return json.loads(payload)
+                except ValueError:
+                    # A proxy or error page can return non-JSON with a 200. Callers that
+                    # fail closed need this to arrive as an ApphelmError, not a ValueError.
+                    raise ApphelmError("Apphelm returned a response that was not JSON.", response.status or 0, "invalid_response")
+        except urllib.error.HTTPError as error:
+            try:
+                detail = json.loads(error.read().decode("utf-8") or "{}")
+                err = detail.get("error", {}) if isinstance(detail, dict) else {}
+                raise ApphelmError(str(err.get("message", f"Apphelm request failed ({error.code})")), error.code, str(err.get("code", "request_failed")))
+            except (ValueError, ApphelmError) as wrapped:
+                if isinstance(wrapped, ApphelmError):
+                    raise
+                raise ApphelmError(f"Apphelm request failed ({error.code})", error.code)
+        except urllib.error.URLError as error:
+            # DNS failure, refused connection, TLS problem or timeout. Without this, a
+            # network blip escaped is_enabled's fail-closed guard and reached the caller.
+            raise ApphelmError(f"Apphelm could not be reached: {error.reason}", 0, "unreachable")
+        except TimeoutError as error:
+            raise ApphelmError(f"Apphelm request timed out: {error}", 0, "timeout")
+
+    def ingest(self, workspace_id: str, product_id: str, event_name: str, properties: Optional[dict] = None, occurred_at: Optional[str] = None, event_id: Optional[str] = None) -> dict:
+        """Send one event. It carries an event id (``event_id``, or a fresh one), so a retry
+        with the same id is stored and charged once."""
+        return self._request("/events", {
+            "workspaceId": workspace_id, "productId": product_id, "eventName": event_name,
+            "privacyMode": "strict", "properties": properties or {},
+            "eventId": event_id or uuid.uuid4().hex,
+            **({"occurredAt": occurred_at} if occurred_at else {}),
+        })
+
+    def capture(self, workspace_id: str, product_id: str, distinct_id: str, event_name: str, properties: Optional[dict] = None, occurred_at: Optional[str] = None) -> dict:
+        """Send a product event for one person, like PostHog's server ``capture``.
+
+        ``distinct_id`` is your user id, or whatever the browser SDK was given as
+        ``distinctId``. Apphelm hashes it at ingest the way the browser does, so the event
+        joins that person's browser events in funnels, retention, unique-people trends and
+        experiments. Without one a server event only ever counts as volume.
+        """
+        person = str(distinct_id).strip()
+        if not person:
+            raise ValueError("distinct_id is required to capture an event for a person; use ingest for anonymous volume.")
+        return self.ingest(workspace_id, product_id, event_name, {**(properties or {}), "distinct_id": person}, occurred_at)
+
+    def identify(
+        self,
+        workspace_id: str,
+        product_id: str,
+        external_user_id: str,
+        traits: Optional[dict] = None,
+        trait_sources: Optional[dict] = None,
+    ) -> dict:
+        """Identify a person.
+
+        Every trait needs explicit provenance: the API rejects a trait without a matching
+        ``trait_sources`` entry, so this raises rather than sending a request that cannot
+        succeed. A source entry looks like
+        ``{"sourceType": "auth", "sourceId": "session", "verification": "integration_verified"}``.
+        """
+        values = traits or {}
+        sources = trait_sources or {}
+        missing = sorted(key for key in values if key not in sources)
+        if missing:
+            raise ValueError(f"Every trait requires provenance in trait_sources. Missing: {', '.join(missing)}")
+        orphaned = sorted(key for key in sources if key not in values)
+        if orphaned:
+            raise ValueError(f"trait_sources has no matching trait value for: {', '.join(orphaned)}")
+        return self.ingest(workspace_id, product_id, "apphelm.identify", {
+            "externalUserId": external_user_id, "traits": values,
+            "traitSources": sources, "consent": [], "isAccountAdmin": False, "isChampion": False,
+        })
+
+    def evaluate_flags(self, product_id: str, distinct_id: str, flag_key: Optional[str] = None, environment: Optional[str] = None) -> list[FlagEvaluation]:
+        body: dict[str, Any] = {"productId": product_id, "distinctId": distinct_id}
+        if flag_key:
+            body["flagKey"] = flag_key
+        if environment:
+            body["environment"] = environment
+        data = self._request("/flags/evaluate", body)
+        return [FlagEvaluation(
+            key=str(row.get("key", "")), enabled=bool(row.get("enabled")),
+            variant=row.get("variant"), payload=row.get("payload"), reason=str(row.get("reason", "")),
+        ) for row in data.get("data", [])]
+
+    def is_enabled(self, flag_key: str, distinct_id: str, product_id: str, environment: Optional[str] = None) -> bool:
+        """Fail-closed: any transport or API failure returns False."""
+        try:
+            return any(row.key == flag_key and row.enabled for row in self.evaluate_flags(product_id, distinct_id, flag_key, environment))
+        except ApphelmError:
+            return False
+        except (TypeError, ValueError):
+            raise
+
+    def get_feature_flag(self, workspace_id: str, product_id: str, flag_key: str, distinct_id: str,
+                         environment: Optional[str] = None, send_exposure: Optional[bool] = None) -> Any:
+        """The flag's variant (``True`` for an enabled boolean flag) or ``False``, fail-closed.
+
+        For a flag a running experiment depends on it also records the exposure the
+        experiment's results divide by; ``send_exposure`` forces that on or off. The
+        exposure never changes what is returned.
+        """
+        body: dict[str, Any] = {"productId": product_id, "distinctId": distinct_id, "flagKey": flag_key}
+        if environment:
+            body["environment"] = environment
+        try:
+            rows = self._request("/flags/evaluate", body).get("data", [])
+        except ApphelmError:
+            return False
+        row = next((item for item in rows if isinstance(item, dict) and item.get("key") == flag_key), None)
+        if row is None:
+            return False
+        if send_exposure if send_exposure is not None else row.get("experiment") is True:
+            try:
+                self.record_exposure(workspace_id, product_id, flag_key, distinct_id, row.get("variant"), bool(row.get("enabled")))
+            except ApphelmError:
+                pass
+        return (row.get("variant") or True) if row.get("enabled") else False
+
+    def record_exposure(self, workspace_id: str, product_id: str, flag_key: str, distinct_id: str,
+                        variant: Optional[str], enabled: bool = True) -> Optional[dict]:
+        """Record that ``distinct_id`` was served a flag: the ``apphelm.flag_evaluated``
+        event experiment results count people from. ``get_feature_flag`` sends it for
+        experiment flags; call it yourself after evaluating some other way. Sent once per
+        flag, person and variant per client (the last 10,000 are remembered)."""
+        chosen = variant or ("on" if enabled else "off")
+        key = (product_id, flag_key, str(distinct_id), chosen)
+        if key in self._exposed:
+            return None
+        if len(self._exposed) >= 10_000:
+            self._exposed.clear()
+        self._exposed.add(key)
+        return self.ingest(workspace_id, product_id, "apphelm.flag_evaluated", {"flag_key": flag_key, "variant": chosen, "distinct_id": str(distinct_id)})
+
+    def capture_message(self, workspace_id: str, product_id: str, message: str, level: str = "info",
+                        fingerprint: Optional[str | Sequence[str]] = None, release: Optional[str] = None,
+                        environment: Optional[str] = None,
+                        tags: Optional[dict[str, str | int | float | bool]] = None) -> dict:
+        """Report a message rather than an exception: something noteworthy with no error
+        object. It becomes an issue grouped by its text (numbers and ids normalised) or by
+        ``fingerprint``, with ``level`` (fatal, error, warning, info or debug) as a tag."""
+        if level not in ("fatal", "error", "warning", "info", "debug"):
+            raise ValueError("level must be fatal, error, warning, info or debug")
+        properties: dict[str, Any] = {"message": str(message)[:240], "name": "Message", "level": level}
+        if fingerprint is not None:
+            parts = [fingerprint] if isinstance(fingerprint, str) else list(fingerprint)
+            properties["fingerprint"] = [str(part)[:200] for part in parts][:10]
+        if release:
+            properties["release"] = str(release)[:120]
+        if environment:
+            properties["environment"] = str(environment)[:40]
+        if tags:
+            properties["tags"] = {str(key)[:40]: value for key, value in list(tags.items())[:20]}
+        return self._send_error(workspace_id, product_id, properties)
+
+    def check_in(self, product_id: str, monitor: str, status: str, check_in_id: Optional[str] = None,
+                 duration_ms: Optional[int] = None, monitor_config: Optional[dict[str, Any]] = None) -> dict:
+        """Check in a cron job: ``in_progress`` at start, then ``ok`` or ``error`` with the
+        same ``check_in_id`` (any ``chk_`` id you generate, so retries are safe), or one
+        ``ok``/``error``, which closes the newest open run. ``monitor_config`` (``{"schedule": {"type":
+        "crontab", "value": "0 * * * *"}}``) creates or updates the monitor."""
+        if status not in ("in_progress", "ok", "error"):
+            raise ValueError("status must be in_progress, ok or error")
+        body: dict[str, Any] = {"productId": product_id, "monitor": monitor, "status": status}
+        if check_in_id:
+            body["checkInId"] = check_in_id
+        if duration_ms is not None:
+            body["durationMs"] = int(duration_ms)
+        if monitor_config:
+            body["monitorConfig"] = monitor_config
+        return self._request("/check-ins", body)
+
+    def capture_exception(self, workspace_id: str, product_id: str, error: BaseException | str,
+                          fingerprint: Optional[str | Sequence[str]] = None,
+                          release: Optional[str] = None, environment: Optional[str] = None,
+                          tags: Optional[dict[str, str | int | float | bool]] = None,
+                          handled: bool = True, user_id: Optional[str | int] = None,
+                          trace_id: Optional[str] = None) -> dict:
+        """Report an exception. Apphelm groups it by type, message and top in-app frame, or by
+        ``fingerprint`` when given. The traceback is scrubbed of emails, keys and query strings.
+        ``release`` and ``environment`` show where the issue happens and let an issue resolved
+        in a release reopen only when a different release hits it.
+        ``user_id`` counts the person toward the issue's affected users; only its hash is sent.
+        ``trace_id`` (``transaction.trace_id``) links the issue to the trace it happened in."""
+        message = error.args[0] if isinstance(error, BaseException) and error.args else str(error)
+        properties: dict[str, Any] = {
+            "message": str(message)[:240], "name": type(error).__name__ if isinstance(error, BaseException) else "Error",
+        }
+        if isinstance(error, BaseException) and error.__traceback__ is not None:
+            properties["stack"] = _scrub_stack("".join(traceback.format_exception(type(error), error, error.__traceback__)))
+        if fingerprint is not None:
+            parts = [fingerprint] if isinstance(fingerprint, str) else list(fingerprint)
+            properties["fingerprint"] = [str(part)[:200] for part in parts][:10]
+        if release:
+            properties["release"] = str(release)[:120]
+        if environment:
+            properties["environment"] = str(environment)[:40]
+        if tags:
+            properties["tags"] = {str(key)[:40]: value for key, value in list(tags.items())[:20]}
+        if not handled:
+            properties["handled"] = False
+        if user_id is not None and str(user_id) != "":
+            # Counts the person toward the issue's affected users. Only the hash is sent,
+            # the same one the Node client and the server compute.
+            properties["user_hash"] = hashlib.sha256(f"apphelm-user:{str(user_id)[:200]}".encode("utf-8")).hexdigest()[:32]
+        if trace_id and re.fullmatch(r"[0-9a-f]{32}", trace_id):
+            properties["trace_id"] = trace_id
+        return self._send_error(workspace_id, product_id, properties)
+
+    def capture_unhandled(self, workspace_id: str, product_id: str, release: Optional[str] = None,
+                          environment: Optional[str] = None,
+                          tags: Optional[dict[str, str | int | float | bool]] = None) -> Callable[[], None]:
+        """Report uncaught exceptions, in the main thread (``sys.excepthook``) and in other
+        threads (``threading.excepthook``), as unhandled issues. The previous hooks still run
+        afterwards, so the traceback prints and the interpreter exits as it would have.
+        ``KeyboardInterrupt`` and ``SystemExit`` are not errors and are not reported. A failed
+        report never replaces the original exception. Returns a function that restores the
+        previous hooks."""
+        previous_sys = sys.excepthook
+        previous_thread = threading.excepthook
+
+        def report(error: BaseException) -> None:
+            try:
+                self.capture_exception(workspace_id, product_id, error, release=release, environment=environment, tags=tags, handled=False)
+            except Exception:  # noqa: BLE001 - the original exception matters more
+                pass
+
+        def sys_hook(exc_type, exc, tb):
+            if exc is not None and not issubclass(exc_type, (KeyboardInterrupt, SystemExit)):
+                report(exc)
+            previous_sys(exc_type, exc, tb)
+
+        def thread_hook(args):
+            if args.exc_value is not None and not issubclass(args.exc_type, (KeyboardInterrupt, SystemExit)):
+                report(args.exc_value)
+            previous_thread(args)
+
+        sys.excepthook = sys_hook
+        threading.excepthook = thread_hook
+
+        def restore() -> None:
+            if sys.excepthook is sys_hook:
+                sys.excepthook = previous_sys
+            if threading.excepthook is thread_hook:
+                threading.excepthook = previous_thread
+
+        return restore