pingloom 0.1.0__tar.gz

pingloom-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+.local/
+node_modules/
+.venv/
+.next/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+test-results/
+playwright-report/
+.playwright-mcp/
+.playwright-cli/
+output/
+Codex UI UX Pro Max/
+.superpowers/
+.env*
+!.env.example
+!.env.uat.example
+apps/mobile/android/
+apps/mobile/ios/
+apps/mobile/.expo/
+apps/mobile/expo-env.d.ts
+apps/mobile/firebase/*.json
+apps/mobile/firebase/*.plist
+apps/mobile/firebase/uat/*.json
+apps/mobile/firebase/uat/*.plist
+.local/maestro/
+
+# local screenshots for videos (see media/README.md)
+media/
+.next-e2e/
+
+# deployment
+infra/docker/.env
+infra/docker/secrets/*
+!infra/docker/secrets/.gitkeep
+.deploy/
+backups/
+
+# Claude Code agent worktrees
+.claude/worktrees/
+.vercel

pingloom-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.5
+Name: pingloom
+Version: 0.1.0
+Summary: Python client for the PingLoom notification API (server-side only).
+Project-URL: Homepage, https://pingloom.dev
+Author: Srish Rachamalla
+License: MIT
+Keywords: alerts,notifications,on-call,pingloom,push,webhook
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pingloom (Python)
+
+Python client for the [PingLoom](https://pingloom.dev) notification API. Standard library only, Python 3.9+.
+
+Server-side only: the API key (`pl_live_...` or `pl_test_...`) must never go into browser or mobile code.
+
+```bash
+pip install pingloom
+export PINGLOOM_API_KEY=pl_test_...
+```
+
+```python
+from pingloom import PingLoom
+
+pl = PingLoom()  # reads PINGLOOM_API_KEY; talks to https://api.pingloom.dev (override with PINGLOOM_BASE_URL)
+event_id = pl.send(
+    "Backup finished", body="42 GB in 3 min", channel="ops", priority="high", idempotency_key="backup-2026-10-30"
+)
+print(pl.status(event_id)["status"])  # provider_accepted means FCM accepted it, not that a phone got it
+```
+
+`send(title, body=None, channel=None, priority=None, data=None, action_url=None, idempotency_key=None)` returns the event ID. `status(event_id)` needs the `events:read` scope.
+
+## Errors and retries
+
+Every API error is a typed exception carrying `status`, `code`, `message`, `request_id` and `details`:
+
+| Exception | When |
+| --- | --- |
+| `InvalidRequestError` | 400, 413, 415, 422 |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 (`IDEMPOTENCY_CONFLICT`, `PROJECT_ARCHIVED`) |
+| `RateLimitError` | 429 `RATE_LIMITED`, after retries |
+| `QuotaExceededError` | 429 `QUOTA_EXCEEDED`, never retried |
+| `ServerError` | 5xx, after retries |
+| `NetworkError` | no response, after retries |
+| `ConfigurationError` | missing key or base URL |
+
+`429 RATE_LIMITED`, `5xx` and network errors are retried (default 3 times) with exponential backoff, or `Retry-After` when sent. Retries reuse the same `Idempotency-Key`, so they cannot create duplicates. When you do not pass `idempotency_key`, a random one is generated per call. Pass your own, derived from the business event, to make repeated calls of your own safe too.
+
+The key is never logged: `repr(client)` and error text show `pl_live_****abcd`.
+
+## Develop
+
+```bash
+pip install pytest
+python -m pytest
+```

pingloom-0.1.0/README.md

@@ -0,0 +1,50 @@
+# pingloom (Python)
+
+Python client for the [PingLoom](https://pingloom.dev) notification API. Standard library only, Python 3.9+.
+
+Server-side only: the API key (`pl_live_...` or `pl_test_...`) must never go into browser or mobile code.
+
+```bash
+pip install pingloom
+export PINGLOOM_API_KEY=pl_test_...
+```
+
+```python
+from pingloom import PingLoom
+
+pl = PingLoom()  # reads PINGLOOM_API_KEY; talks to https://api.pingloom.dev (override with PINGLOOM_BASE_URL)
+event_id = pl.send(
+    "Backup finished", body="42 GB in 3 min", channel="ops", priority="high", idempotency_key="backup-2026-10-30"
+)
+print(pl.status(event_id)["status"])  # provider_accepted means FCM accepted it, not that a phone got it
+```
+
+`send(title, body=None, channel=None, priority=None, data=None, action_url=None, idempotency_key=None)` returns the event ID. `status(event_id)` needs the `events:read` scope.
+
+## Errors and retries
+
+Every API error is a typed exception carrying `status`, `code`, `message`, `request_id` and `details`:
+
+| Exception | When |
+| --- | --- |
+| `InvalidRequestError` | 400, 413, 415, 422 |
+| `AuthenticationError` | 401 |
+| `PermissionDeniedError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 (`IDEMPOTENCY_CONFLICT`, `PROJECT_ARCHIVED`) |
+| `RateLimitError` | 429 `RATE_LIMITED`, after retries |
+| `QuotaExceededError` | 429 `QUOTA_EXCEEDED`, never retried |
+| `ServerError` | 5xx, after retries |
+| `NetworkError` | no response, after retries |
+| `ConfigurationError` | missing key or base URL |
+
+`429 RATE_LIMITED`, `5xx` and network errors are retried (default 3 times) with exponential backoff, or `Retry-After` when sent. Retries reuse the same `Idempotency-Key`, so they cannot create duplicates. When you do not pass `idempotency_key`, a random one is generated per call. Pass your own, derived from the business event, to make repeated calls of your own safe too.
+
+The key is never logged: `repr(client)` and error text show `pl_live_****abcd`.
+
+## Develop
+
+```bash
+pip install pytest
+python -m pytest
+```

pingloom-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pingloom"
+version = "0.1.0"
+description = "Python client for the PingLoom notification API (server-side only)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Srish Rachamalla" }]
+keywords = ["pingloom", "notifications", "push", "alerts", "on-call", "webhook"]
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://pingloom.dev"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pingloom"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"

pingloom-0.1.0/ruff.toml

@@ -0,0 +1,6 @@
+# Standalone config: the SDK supports Python 3.9, so the repo-wide py312 rules (X | None) do not apply here.
+line-length = 120
+target-version = "py39"
+
+[lint]
+select = ["E", "F", "I", "B"]

pingloom-0.1.0/src/pingloom/__init__.py

@@ -0,0 +1,33 @@
+"""PingLoom Python client."""
+
+from ._version import __version__
+from .client import PingLoom
+from .errors import (
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    InvalidRequestError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    PingLoomError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = [
+    "__version__",
+    "PingLoom",
+    "PingLoomError",
+    "ConfigurationError",
+    "NetworkError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ServerError",
+]

pingloom-0.1.0/src/pingloom/_mask.py

@@ -0,0 +1,25 @@
+"""Key masking. The API key must never appear in logs, errors or reprs."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+_KEY_RE = re.compile(r"pl_(?:live|test)_[A-Za-z0-9_\-]{4,}")
+
+
+def mask_key(key: Optional[str]) -> str:
+    """Return `pl_live_****abcd` for a key, or `****` when it does not look like one."""
+    if not key:
+        return "(no key)"
+    m = re.match(r"^(pl_(?:live|test)_)", key)
+    if m and len(key) >= len(m.group(1)) + 8:
+        return f"{m.group(1)}****{key[-4:]}"
+    return "****"
+
+
+def scrub(text: str, key: Optional[str] = None) -> str:
+    """Mask the known key and anything shaped like a PingLoom key inside free text."""
+    if key:
+        text = text.replace(key, mask_key(key))
+    return _KEY_RE.sub(lambda m: mask_key(m.group(0)), text)

pingloom-0.1.0/src/pingloom/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pingloom-0.1.0/src/pingloom/client.py

@@ -0,0 +1,171 @@
+"""PingLoom client. Standard library only (urllib)."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from ._mask import mask_key, scrub
+from ._version import __version__
+from .errors import ConfigurationError, NetworkError, PingLoomError, error_for
+
+# TODO(T07/T08): add heartbeat() and decision helpers here once those endpoints are merged.
+
+_RETRY_CAP_SECONDS = 30.0
+
+
+DEFAULT_BASE_URL = "https://api.pingloom.dev"
+
+class PingLoom:
+    """Server-side client. Never use it in browser or mobile code: the key must stay on your server.
+
+    `api_key` defaults to $PINGLOOM_API_KEY and `base_url` to $PINGLOOM_BASE_URL, else the hosted API.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        backoff: float = 0.5,
+        _sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._api_key = api_key or os.environ.get("PINGLOOM_API_KEY") or ""
+        url = base_url or os.environ.get("PINGLOOM_BASE_URL") or DEFAULT_BASE_URL
+        if not self._api_key:
+            raise ConfigurationError("No API key. Pass api_key or set PINGLOOM_API_KEY.")
+        self.base_url = url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self.backoff = backoff
+        self._sleep = _sleep
+
+    def __repr__(self) -> str:
+        return f"PingLoom(api_key={mask_key(self._api_key)!r}, base_url={self.base_url!r})"
+
+    # -- public API ---------------------------------------------------------------------------
+
+    def send(
+        self,
+        title: str,
+        body: Optional[str] = None,
+        channel: Optional[str] = None,
+        priority: Optional[str] = None,
+        data: Optional[Mapping[str, Any]] = None,
+        action_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> str:
+        """Send a notification and return the event ID.
+
+        Without `idempotency_key` a random one is generated per call so that automatic retries cannot create
+        duplicates. Derive your own key from the business event (for example "order-1042-paid") when you also
+        want repeated calls of your own to be safe.
+        """
+        payload: Dict[str, Any] = {"title": title}
+        for name, value in (
+            ("body", body),
+            ("channel", channel),
+            ("priority", priority),
+            ("data", dict(data) if data is not None else None),
+            ("action_url", action_url),
+        ):
+            if value is not None:
+                payload[name] = value
+        key = idempotency_key or uuid.uuid4().hex
+        result = self._request("POST", "/v1/notifications", payload, {"Idempotency-Key": key})
+        return str(result["event_id"])
+
+    def status(self, event_id: str) -> Dict[str, Any]:
+        """Read an event back. The key needs the events:read scope."""
+        if not event_id or "/" in event_id:
+            raise ValueError("event_id must be a non-empty event ID")
+        return self._request("GET", f"/v1/notifications/{urllib.parse.quote(event_id, safe='')}", None, {})
+
+    # -- internals ----------------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, payload: Optional[dict], extra: Dict[str, str]) -> Dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"pingloom-python/{__version__}",
+            **extra,
+        }
+        raw = None
+        if payload is not None:
+            raw = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            outcome = self._once(method, path, raw, headers)
+            if not isinstance(outcome, PingLoomError):
+                return outcome
+            if attempt >= self.max_retries or not _retryable(outcome):
+                raise outcome
+            self._sleep(self._delay(attempt, outcome))
+            attempt += 1
+
+    def _once(self, method: str, path: str, raw: Optional[bytes], headers: Dict[str, str]) -> Any:
+        req = urllib.request.Request(self.base_url + path, data=raw, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:  # noqa: S310 - the scheme is the caller's
+                return _parse(res.read())
+        except urllib.error.HTTPError as e:
+            return self._http_error(e)
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as e:
+            return NetworkError(scrub(f"Could not reach PingLoom: {getattr(e, 'reason', e)}", self._api_key))
+
+    def _http_error(self, e: urllib.error.HTTPError) -> PingLoomError:
+        body = _parse(e.read(), strict=False)
+        env = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), dict) else {}
+        code = str(env.get("code") or "UNKNOWN")
+        message = scrub(str(env.get("message") or e.reason or f"HTTP {e.code}"), self._api_key)
+        retry_after = _float(e.headers.get("Retry-After")) if e.headers else None
+        cls = error_for(e.code, code)
+        return cls(
+            message,
+            status=e.code,
+            code=code,
+            request_id=env.get("request_id"),
+            details=env.get("details") if isinstance(env.get("details"), list) else None,
+            retry_after=retry_after,
+        )
+
+    def _delay(self, attempt: int, error: PingLoomError) -> float:
+        if error.retry_after is not None:
+            return min(max(error.retry_after, 0.0), _RETRY_CAP_SECONDS)
+        return min(self.backoff * (2**attempt) * (0.5 + random.random() / 2), _RETRY_CAP_SECONDS)
+
+
+def _retryable(error: PingLoomError) -> bool:
+    if error.status == 0:
+        return not isinstance(error, ConfigurationError)  # network error
+    if error.status == 429:
+        return error.code != "QUOTA_EXCEEDED"
+    return error.status >= 500
+
+
+def _parse(raw: bytes, strict: bool = True) -> Any:
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        if strict:
+            raise PingLoomError("PingLoom returned a response that is not JSON.", code="BAD_RESPONSE") from None
+        return {}
+
+
+def _float(v: Optional[str]) -> Optional[float]:
+    try:
+        return float(v) if v is not None else None
+    except ValueError:
+        return None

pingloom-0.1.0/src/pingloom/errors.py

@@ -0,0 +1,93 @@
+"""Typed exceptions mapped from the PingLoom error envelope {"error": {"code", "message", "request_id"}}."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+
+class PingLoomError(Exception):
+    """Base class. `status` is 0 for errors that never reached the API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "UNKNOWN",
+        request_id: Optional[str] = None,
+        details: Optional[List[Any]] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.details = details or []
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code != "UNKNOWN":
+            parts.append(f"[{self.code}]")
+        if self.request_id:
+            parts.append(f"(request {self.request_id})")
+        return " ".join(parts)
+
+
+class ConfigurationError(PingLoomError):
+    """Missing API key or base URL. Raised before any request is made."""
+
+
+class NetworkError(PingLoomError):
+    """The request could not reach the API (DNS, connection, timeout)."""
+
+
+class InvalidRequestError(PingLoomError):
+    """400, 413, 415 or 422: fix the request. See `details`."""
+
+
+class AuthenticationError(PingLoomError):
+    """401: the key is missing, unknown, revoked or expired."""
+
+
+class PermissionDeniedError(PingLoomError):
+    """403: the key lacks the needed scope."""
+
+
+class NotFoundError(PingLoomError):
+    """404."""
+
+
+class ConflictError(PingLoomError):
+    """409: IDEMPOTENCY_CONFLICT (same key, different body) or PROJECT_ARCHIVED. Do not retry."""
+
+
+class RateLimitError(PingLoomError):
+    """429 RATE_LIMITED. Retried automatically; raised after the retries run out."""
+
+
+class QuotaExceededError(PingLoomError):
+    """429 QUOTA_EXCEEDED: the monthly quota is used. Never retried."""
+
+
+class ServerError(PingLoomError):
+    """5xx. Retried with the same idempotency key; raised after the retries run out."""
+
+
+def error_for(status: int, code: str) -> type:
+    if status == 429:
+        return QuotaExceededError if code == "QUOTA_EXCEEDED" else RateLimitError
+    if status == 401:
+        return AuthenticationError
+    if status == 403:
+        return PermissionDeniedError
+    if status == 404:
+        return NotFoundError
+    if status == 409:
+        return ConflictError
+    if status >= 500:
+        return ServerError
+    if 400 <= status < 500:
+        return InvalidRequestError
+    return PingLoomError

pingloom-0.1.0/tests/test_client.py

@@ -0,0 +1,226 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from pingloom import (
+    AuthenticationError,
+    ConfigurationError,
+    ConflictError,
+    InvalidRequestError,
+    NetworkError,
+    PermissionDeniedError,
+    PingLoom,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+from pingloom._mask import mask_key
+
+KEY = "pl_test_abcdefghijklmnop1234"
+
+
+class Fake:
+    """A tiny HTTP server that replays queued (status, headers, body) responses and records requests."""
+
+    def __init__(self):
+        self.responses = []
+        self.requests = []
+        fake = self
+
+        class H(BaseHTTPRequestHandler):
+            def _handle(self):
+                n = int(self.headers.get("Content-Length") or 0)
+                body = self.rfile.read(n).decode() if n else ""
+                fake.requests.append(
+                    {"method": self.command, "path": self.path, "headers": dict(self.headers), "body": body}
+                )
+                status, headers, payload = fake.responses.pop(0) if fake.responses else (200, {}, {})
+                raw = payload if isinstance(payload, bytes) else json.dumps(payload).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(raw)))
+                for k, v in headers.items():
+                    self.send_header(k, v)
+                self.end_headers()
+                self.wfile.write(raw)
+
+            do_GET = do_POST = _handle
+
+            def log_message(self, *a):
+                pass
+
+        self.server = HTTPServer(("127.0.0.1", 0), H)
+        self.url = f"http://127.0.0.1:{self.server.server_port}"
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    def close(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+
+@pytest.fixture
+def fake():
+    f = Fake()
+    yield f
+    f.close()
+
+
+def make(fake, **kw):
+    sleeps = []
+    c = PingLoom(KEY, fake.url, _sleep=sleeps.append, **kw)
+    c.sleeps = sleeps
+    return c
+
+
+def err(status, code, message="m", **extra):
+    return (status, extra.pop("headers", {}), {"error": {"code": code, "message": message, "request_id": "req_1"}})
+
+
+ACCEPTED = {"event_id": "01EVENT", "status": "accepted", "created_at": "x", "status_url": "/v1/notifications/01EVENT"}
+
+
+def test_env_config(monkeypatch, fake):
+    monkeypatch.setenv("PINGLOOM_API_KEY", KEY)
+    monkeypatch.setenv("PINGLOOM_BASE_URL", fake.url + "/")
+    c = PingLoom()
+    assert c.base_url == fake.url
+
+
+def test_missing_config_raises(monkeypatch):
+    monkeypatch.delenv("PINGLOOM_API_KEY", raising=False)
+    monkeypatch.delenv("PINGLOOM_BASE_URL", raising=False)
+    with pytest.raises(ConfigurationError):
+        PingLoom(base_url="http://x")
+    assert PingLoom(api_key=KEY).base_url == "https://api.pingloom.dev"
+
+
+def test_send_returns_event_id_and_sends_fields(fake):
+    fake.responses.append((202, {}, ACCEPTED))
+    c = make(fake)
+    eid = c.send(
+        "Hi", body="b", channel="ops", priority="high", data={"a": 1}, action_url="https://x.y", idempotency_key="k1"
+    )
+    assert eid == "01EVENT"
+    r = fake.requests[0]
+    assert r["method"] == "POST" and r["path"] == "/v1/notifications"
+    assert r["headers"]["Authorization"] == f"Bearer {KEY}"
+    assert r["headers"]["Idempotency-Key"] == "k1"
+    assert json.loads(r["body"]) == {
+        "title": "Hi",
+        "body": "b",
+        "channel": "ops",
+        "priority": "high",
+        "data": {"a": 1},
+        "action_url": "https://x.y",
+    }
+
+
+def test_send_omits_unset_fields_and_generates_key(fake):
+    fake.responses.append((202, {}, ACCEPTED))
+    make(fake).send("Only title")
+    r = fake.requests[0]
+    assert json.loads(r["body"]) == {"title": "Only title"}
+    assert len(r["headers"]["Idempotency-Key"]) >= 16
+
+
+def test_status(fake):
+    fake.responses.append((200, {}, {"event_id": "01EVENT", "status": "provider_accepted"}))
+    out = make(fake).status("01EVENT")
+    assert out["status"] == "provider_accepted"
+    assert fake.requests[0]["method"] == "GET" and fake.requests[0]["path"] == "/v1/notifications/01EVENT"
+
+
+def test_retries_5xx_with_same_idempotency_key(fake):
+    fake.responses += [err(503, "INTERNAL_ERROR"), err(500, "INTERNAL_ERROR"), (202, {}, ACCEPTED)]
+    c = make(fake)
+    assert c.send("x") == "01EVENT"
+    keys = {r["headers"]["Idempotency-Key"] for r in fake.requests}
+    assert len(fake.requests) == 3 and len(keys) == 1
+    assert len(c.sleeps) == 2
+
+
+def test_rate_limit_honours_retry_after(fake):
+    fake.responses += [err(429, "RATE_LIMITED", headers={"Retry-After": "2"}), (202, {}, ACCEPTED)]
+    c = make(fake)
+    c.send("x")
+    assert c.sleeps == [2.0]
+
+
+def test_gives_up_after_max_retries(fake):
+    fake.responses += [err(500, "INTERNAL_ERROR")] * 5
+    c = make(fake, max_retries=2)
+    with pytest.raises(ServerError) as e:
+        c.send("x")
+    assert len(fake.requests) == 3
+    assert e.value.status == 500 and e.value.request_id == "req_1"
+
+
+def test_quota_is_not_retried(fake):
+    fake.responses += [err(429, "QUOTA_EXCEEDED")]
+    with pytest.raises(QuotaExceededError):
+        make(fake).send("x")
+    assert len(fake.requests) == 1
+
+
+@pytest.mark.parametrize(
+    "status,code,cls",
+    [
+        (401, "INVALID_API_KEY", AuthenticationError),
+        (403, "INSUFFICIENT_SCOPE", PermissionDeniedError),
+        (409, "IDEMPOTENCY_CONFLICT", ConflictError),
+        (422, "VALIDATION_ERROR", InvalidRequestError),
+        (413, "PAYLOAD_TOO_LARGE", InvalidRequestError),
+        (429, "RATE_LIMITED", RateLimitError),
+    ],
+)
+def test_error_mapping(fake, status, code, cls):
+    fake.responses += [err(status, code)] * 5
+    with pytest.raises(cls) as e:
+        make(fake, max_retries=0).send("x")
+    assert e.value.code == code and e.value.status == status
+    if status != 429:
+        assert len(fake.requests) == 1
+
+
+def test_validation_details_kept(fake):
+    fake.responses.append(
+        (
+            422,
+            {},
+            {
+                "error": {
+                    "code": "VALIDATION_ERROR",
+                    "message": "bad",
+                    "request_id": "r",
+                    "details": [{"field": "title"}],
+                }
+            },
+        )
+    )
+    with pytest.raises(InvalidRequestError) as e:
+        make(fake).send("")
+    assert e.value.details == [{"field": "title"}]
+
+
+def test_network_error_retried_then_raised():
+    sleeps = []
+    c = PingLoom(KEY, "http://127.0.0.1:1", max_retries=2, _sleep=sleeps.append, timeout=1)
+    with pytest.raises(NetworkError):
+        c.send("x")
+    assert len(sleeps) == 2
+
+
+def test_key_never_in_error_text_or_repr(fake):
+    fake.responses.append(err(401, "INVALID_API_KEY", message=f"bad key {KEY}"))
+    c = make(fake)
+    with pytest.raises(AuthenticationError) as e:
+        c.send("x")
+    assert KEY not in str(e.value) and KEY not in repr(c)
+    assert "pl_test_****1234" in str(e.value)
+
+
+def test_mask_key():
+    assert mask_key("pl_live_abcdefghijklmnop9876") == "pl_live_****9876"
+    assert mask_key("short") == "****"