apphelm 0.5.0__tar.gz

apphelm-0.5.0/.gitignore

@@ -0,0 +1,5 @@
+# Build outputs of `python -m build` and test runs.
+dist/
+build/
+*.egg-info/
+__pycache__/

apphelm-0.5.0/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-0.5.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,88 @@
+# 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/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

apphelm-0.5.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apphelm"
+dynamic = ["version"]
+description = "Official Python server SDK for Apphelm: events, identify, fail-closed feature flags, errors and tracing."
+readme = "README.md"
+requires-python = ">=3.10"
+# Same terms as the npm package (@sansavision/apphelm, "UNLICENSED" with LICENSE): proprietary,
+# use under an Apphelm service agreement. The owner decides the published terms; see docs/SDK-RELEASING.md.
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "SansaVision", email = "support@sansavision.com" }]
+keywords = ["apphelm", "analytics", "feature-flags", "error-monitoring", "tracing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Monitoring",
+]
+# Stdlib only: no runtime dependencies.
+dependencies = []
+
+# No Source link: the monorepo (Sansa-Organisation/apphelm) is private, so it would 404 for users.
+[project.urls]
+Homepage = "https://apphelm.dev"
+Documentation = "https://apphelm.dev/docs"
+
+[tool.hatch.version]
+path = "apphelm.py"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["apphelm.py"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["apphelm.py", "test_apphelm.py", "README.md", "LICENSE", "pyproject.toml"]

apphelm-0.5.0/test_apphelm.py

@@ -0,0 +1,395 @@
+"""Stdlib-only tests for the Apphelm Python client. Run: python3 test_apphelm.py"""
+
+import io
+import json
+import unittest
+import urllib.error
+from unittest.mock import patch
+
+from apphelm import Apphelm, ApphelmError
+
+
+class FakeResponse:
+    def __init__(self, body: dict, raw: bytes | None = None, status: int = 200):
+        self._body = raw if raw is not None else json.dumps(body).encode("utf-8")
+        self.status = status
+
+    def read(self) -> bytes:
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+
+def http_error(code: int, body: dict) -> urllib.error.HTTPError:
+    return urllib.error.HTTPError("https://apphelm.dev/api/v1/flags/evaluate", code, "error", {}, io.BytesIO(json.dumps(body).encode("utf-8")))
+
+
+class ClientTest(unittest.TestCase):
+    def test_requires_api_key(self):
+        with self.assertRaises(TypeError):
+            Apphelm("")
+
+    def test_evaluate_flags_parses_evaluations(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["url"] = request.full_url
+            seen["auth"] = request.get_header("Authorization")
+            return FakeResponse({"object": "flag_evaluations", "data": [{"key": "new-checkout", "enabled": True, "variant": "on", "payload": True, "reason": "enabled"}], "failClosed": True})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            rows = client.evaluate_flags("prd_1", "user-1")
+        self.assertEqual(seen["url"], "https://apphelm.dev/api/v1/flags/evaluate")
+        self.assertEqual(seen["auth"], "Bearer ahl_live_test")
+        self.assertTrue(rows[0].enabled)
+
+    def test_is_enabled_fails_closed_on_api_error(self):
+        client = Apphelm("ahl_live_test")
+
+        def fake_urlopen(request, timeout=None):
+            raise http_error(503, {"error": {"code": "unavailable", "message": "down"}})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertFalse(client.is_enabled("new-checkout", "user-1", "prd_1"))
+
+    def test_is_enabled_fails_closed_when_apphelm_is_unreachable(self):
+        # A network failure used to escape as urllib.error.URLError, defeating the
+        # fail-closed guarantee and breaking the caller's request instead.
+        client = Apphelm("ahl_live_test")
+
+        def fake_urlopen(request, timeout=None):
+            raise urllib.error.URLError("dns failure")
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertFalse(client.is_enabled("new-checkout", "user-1", "prd_1"))
+
+    def test_is_enabled_fails_closed_on_timeout(self):
+        client = Apphelm("ahl_live_test")
+
+        def fake_urlopen(request, timeout=None):
+            raise TimeoutError("timed out")
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertFalse(client.is_enabled("new-checkout", "user-1", "prd_1"))
+
+    def test_is_enabled_fails_closed_on_non_json_response(self):
+        client = Apphelm("ahl_live_test")
+
+        def fake_urlopen(request, timeout=None):
+            return FakeResponse({}, raw=b"<html>proxy error</html>")
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertFalse(client.is_enabled("new-checkout", "user-1", "prd_1"))
+
+    def test_identify_requires_trait_provenance(self):
+        # The API rejects a trait without a matching source, so the client refuses to send
+        # a request that cannot succeed.
+        client = Apphelm("ahl_live_test")
+        with self.assertRaises(ValueError) as caught:
+            client.identify("org_1", "prd_1", "usr_1", traits={"plan": "builder"})
+        self.assertIn("plan", str(caught.exception))
+
+        with self.assertRaises(ValueError):
+            client.identify("org_1", "prd_1", "usr_1", trait_sources={"plan": {"sourceType": "auth"}})
+
+    def test_identify_sends_traits_with_provenance(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        source = {"sourceType": "auth", "sourceId": "session", "verification": "integration_verified"}
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.identify("org_1", "prd_1", "usr_1", traits={"plan": "builder"}, trait_sources={"plan": source})
+        self.assertEqual(seen["body"]["properties"]["traits"], {"plan": "builder"})
+        self.assertEqual(seen["body"]["properties"]["traitSources"], {"plan": source})
+
+    def test_identify_without_traits_still_works(self):
+        client = Apphelm("ahl_live_test")
+
+        def fake_urlopen(request, timeout=None):
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertTrue(client.identify("org_1", "prd_1", "usr_1")["accepted"])
+
+    def test_capture_sends_the_person_as_distinct_id(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["url"] = request.full_url
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.capture("org_1", "prd_1", " usr_42 ", "subscription_paid", {"plan": "builder"})
+        self.assertEqual(seen["url"], "https://apphelm.dev/api/v1/events")
+        self.assertEqual(seen["body"]["eventName"], "subscription_paid")
+        self.assertEqual(seen["body"]["properties"], {"plan": "builder", "distinct_id": "usr_42"})
+
+    def test_ingest_sends_an_event_id_so_retries_are_stored_once(self):
+        client = Apphelm("ahl_live_test")
+        bodies = []
+
+        def fake_urlopen(request, timeout=None):
+            bodies.append(json.loads(request.data.decode("utf-8")))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.ingest("org_1", "prd_1", "server_event")
+            client.ingest("org_1", "prd_1", "server_event", event_id="caller-chosen-1")
+        self.assertRegex(bodies[0]["eventId"], r"^[0-9a-f]{32}$")
+        self.assertEqual(bodies[1]["eventId"], "caller-chosen-1")
+
+    def test_capture_refuses_an_empty_distinct_id(self):
+        with self.assertRaises(ValueError):
+            Apphelm("ahl_live_test").capture("org_1", "prd_1", "  ", "subscription_paid")
+
+    def test_get_feature_flag_records_one_exposure_for_an_experiment_flag(self):
+        client = Apphelm("ahl_live_test")
+        exposures = []
+
+        def fake_urlopen(request, timeout=None):
+            body = json.loads(request.data.decode("utf-8"))
+            if request.full_url.endswith("/flags/evaluate"):
+                experiment = body["flagKey"] == "new-checkout"
+                return FakeResponse({"object": "flag_evaluations", "failClosed": True, "data": [{"key": body["flagKey"], "enabled": True, "variant": "test" if experiment else "on", "payload": None, "reason": "variant", **({"experiment": True} if experiment else {})}]})
+            if body["eventName"] == "apphelm.flag_evaluated":
+                exposures.append(body)
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertEqual(client.get_feature_flag("org_1", "prd_1", "new-checkout", "usr_1"), "test")
+            self.assertEqual(client.get_feature_flag("org_1", "prd_1", "new-checkout", "usr_1"), "test")
+            self.assertEqual(client.get_feature_flag("org_1", "prd_1", "dark-mode", "usr_1"), "on")
+        self.assertEqual(len(exposures), 1)
+        self.assertEqual(exposures[0]["workspaceId"], "org_1")
+        self.assertEqual(exposures[0]["properties"], {"flag_key": "new-checkout", "variant": "test", "distinct_id": "usr_1"})
+
+    def test_get_feature_flag_fails_closed_without_recording(self):
+        client = Apphelm("ahl_live_test")
+        calls = []
+
+        def fake_urlopen(request, timeout=None):
+            calls.append(request.full_url)
+            raise http_error(503, {"error": {"code": "unavailable", "message": "down"}})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            self.assertIs(client.get_feature_flag("org_1", "prd_1", "new-checkout", "usr_1"), False)
+        self.assertEqual(len(calls), 1)
+
+    def test_capture_exception_posts_scrubbed_message(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.capture_exception("org_1", "prd_1", ValueError("boom"))
+        self.assertEqual(seen["body"]["eventName"], "$exception")
+        self.assertEqual(seen["body"]["properties"]["message"], "boom")
+
+    def test_capture_exception_sends_scrubbed_traceback_and_fingerprint(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        try:
+            raise ValueError("failed for someone@example.com")
+        except ValueError as error:
+            with patch("urllib.request.urlopen", fake_urlopen):
+                client.capture_exception("org_1", "prd_1", error, fingerprint=["billing", "timeout"], release="3.1.0", environment="production", tags={"region": "eu"})
+        properties = seen["body"]["properties"]
+        self.assertEqual(properties["fingerprint"], ["billing", "timeout"])
+        self.assertIn('File "', properties["stack"])
+        self.assertIn("test_capture_exception_sends_scrubbed_traceback_and_fingerprint", properties["stack"])
+        self.assertNotIn("someone@example.com", properties["stack"])
+        self.assertEqual(properties["release"], "3.1.0")
+        self.assertEqual(properties["environment"], "production")
+        self.assertEqual(properties["tags"], {"region": "eu"})
+
+    def test_capture_unhandled_reports_then_runs_previous_hooks_and_restores_them(self):
+        import sys
+        import threading
+        client = Apphelm("ahl_live_test")
+        sent = []
+        chained = []
+
+        def fake_urlopen(request, timeout=None):
+            sent.append(json.loads(request.data.decode("utf-8")))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        original_sys, original_thread = sys.excepthook, threading.excepthook
+        sys.excepthook = lambda *args: chained.append("sys")
+        threading.excepthook = lambda args: chained.append("thread")
+        try:
+            restore = client.capture_unhandled("org_1", "prd_1", release="3.1.0", environment="production")
+            with patch("urllib.request.urlopen", fake_urlopen):
+                try:
+                    raise RuntimeError("crashed")
+                except RuntimeError as error:
+                    sys.excepthook(type(error), error, error.__traceback__)
+                sys.excepthook(KeyboardInterrupt, KeyboardInterrupt(), None)
+                worker = threading.Thread(target=lambda: (_ for _ in ()).throw(ValueError("in a thread")))
+                worker.start()
+                worker.join()
+            self.assertEqual([body["properties"]["message"] for body in sent], ["crashed", "in a thread"])
+            self.assertEqual({body["properties"]["handled"] for body in sent}, {False})
+            self.assertEqual(sent[0]["properties"]["release"], "3.1.0")
+            self.assertIn("crashed", sent[0]["properties"]["stack"])
+            # The previous hooks still run, including for the interrupt that was not reported.
+            self.assertEqual(chained, ["sys", "sys", "thread"])
+            restore()
+            self.assertEqual(chained, ["sys", "sys", "thread"])
+            sys.excepthook(RuntimeError, RuntimeError("after restore"), None)
+            self.assertEqual(len(sent), 2)
+        finally:
+            sys.excepthook, threading.excepthook = original_sys, original_thread
+
+    def test_capture_unhandled_survives_a_failed_report(self):
+        import sys
+        client = Apphelm("ahl_live_test")
+        chained = []
+
+        def failing_urlopen(request, timeout=None):
+            raise urllib.error.URLError("offline")
+
+        original_sys = sys.excepthook
+        sys.excepthook = lambda *args: chained.append(args[1])
+        try:
+            restore = client.capture_unhandled("org_1", "prd_1")
+            error = RuntimeError("crashed")
+            with patch("urllib.request.urlopen", failing_urlopen):
+                sys.excepthook(RuntimeError, error, None)
+            self.assertEqual(chained, [error])
+            restore()
+        finally:
+            sys.excepthook = original_sys
+
+    def test_capture_message_sends_level_and_no_stack(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.capture_message("org_1", "prd_1", "Payment provider fell back to retry", level="warning", release="3.1.0")
+        properties = seen["body"]["properties"]
+        self.assertEqual(seen["body"]["eventName"], "$exception")
+        self.assertEqual(properties["name"], "Message")
+        self.assertEqual(properties["level"], "warning")
+        self.assertEqual(properties["release"], "3.1.0")
+        self.assertNotIn("stack", properties)
+        with self.assertRaises(ValueError):
+            client.capture_message("org_1", "prd_1", "x", level="loud")
+
+    def test_transaction_sends_spans_and_continues_an_incoming_trace(self):
+        client = Apphelm("ahl_live_test", traces_sample_rate=0.0)
+        sent = []
+
+        def fake_urlopen(request, timeout=None):
+            sent.append(json.loads(request.data.decode("utf-8")))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        incoming = "00-" + "a" * 32 + "-" + "b" * 16 + "-01"
+        with patch("urllib.request.urlopen", fake_urlopen):
+            with client.start_transaction("org_1", "prd_1", "GET /orders/1841", traceparent=incoming, release="3.1.0") as transaction:
+                with transaction.start_span("db.query", "select order"):
+                    pass
+                self.assertEqual(transaction.traceparent(), f"00-{'a' * 32}-{transaction.span_id}-01")
+            # Sampled out locally (rate 0, no incoming trace): nothing is sent.
+            with client.start_transaction("org_1", "prd_1", "job") as unsampled:
+                self.assertFalse(unsampled.sampled)
+            try:
+                with client.start_transaction("org_1", "prd_1", "failing", traceparent=incoming):
+                    raise RuntimeError("boom")
+            except RuntimeError:
+                pass
+        self.assertEqual(len(sent), 2)
+        properties = sent[0]["properties"]
+        self.assertEqual(sent[0]["eventName"], "$transaction")
+        self.assertEqual(properties["trace_id"], "a" * 32)
+        self.assertEqual(properties["parent_span_id"], "b" * 16)
+        self.assertEqual(properties["status"], "ok")
+        self.assertEqual(properties["release"], "3.1.0")
+        spans = json.loads(properties["spans"])
+        self.assertEqual([(span["op"], span["description"], span["parent_span_id"]) for span in spans], [("db.query", "select order", properties["span_id"])])
+        self.assertEqual(sent[1]["properties"]["status"], "error")
+
+    def test_transaction_send_failure_never_raises_and_exceptions_link_to_traces(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def failing_urlopen(request, timeout=None):
+            raise http_error(503, {"error": {"code": "unavailable", "message": "down"}})
+
+        with patch("urllib.request.urlopen", failing_urlopen):
+            self.assertIsNone(client.start_transaction("org_1", "prd_1", "job").finish())
+
+        def fake_urlopen(request, timeout=None):
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.capture_exception("org_1", "prd_1", ValueError("x"), trace_id="c" * 32)
+            self.assertEqual(seen["body"]["properties"]["trace_id"], "c" * 32)
+            client.capture_exception("org_1", "prd_1", ValueError("x"), trace_id="not-a-trace")
+            self.assertNotIn("trace_id", seen["body"]["properties"])
+
+    def test_before_send_can_change_or_drop_errors_and_fails_closed(self):
+        sent = []
+
+        def fake_urlopen(request, timeout=None):
+            sent.append(json.loads(request.data.decode("utf-8")))
+            return FakeResponse({"accepted": True, "eventId": "evt_1"})
+
+        def hook(properties):
+            if "drop me" in properties["message"]:
+                return None
+            if "explode" in properties["message"]:
+                raise RuntimeError("hook bug")
+            return {**properties, "message": properties["message"].replace("Acme", "[customer]")}
+
+        client = Apphelm("ahl_live_test", before_send=hook)
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.capture_exception("org_1", "prd_1", ValueError("Acme checkout failed"))
+            self.assertEqual(client.capture_exception("org_1", "prd_1", ValueError("drop me")), {"accepted": False, "dropped": True})
+            self.assertEqual(client.capture_message("org_1", "prd_1", "explode"), {"accepted": False, "dropped": True})
+            client.capture_message("org_1", "prd_1", "Acme is slow", level="warning")
+            client.ingest("org_1", "prd_1", "purchase_completed", {"note": "drop me"})
+        self.assertEqual([body["properties"].get("message") for body in sent], ["[customer] checkout failed", "[customer] is slow", None])
+
+    def test_check_in_posts_monitor_status_and_config(self):
+        client = Apphelm("ahl_live_test")
+        seen = {}
+
+        def fake_urlopen(request, timeout=None):
+            seen["url"] = request.full_url
+            seen["body"] = json.loads(request.data.decode("utf-8"))
+            return FakeResponse({"object": "check_in", "data": {"id": "chk_1", "monitorId": "mon_1", "status": "ok"}})
+
+        with patch("urllib.request.urlopen", fake_urlopen):
+            client.check_in("prd_1", "billing", "ok", duration_ms=1200, monitor_config={"schedule": {"type": "crontab", "value": "0 * * * *"}})
+        self.assertTrue(seen["url"].endswith("/api/v1/check-ins"))
+        self.assertEqual(seen["body"], {"productId": "prd_1", "monitor": "billing", "status": "ok", "durationMs": 1200, "monitorConfig": {"schedule": {"type": "crontab", "value": "0 * * * *"}}})
+        with self.assertRaises(ValueError):
+            client.check_in("prd_1", "billing", "done")
+
+
+if __name__ == "__main__":
+    unittest.main()