sdk-garden-python 0.1.0__tar.gz

sdk_garden_python-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/

sdk_garden_python-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: sdk-garden-python
+Version: 0.1.0
+Summary: Lightweight SDK observability client for Python — stdlib only, non-blocking
+Project-URL: Homepage, https://sdkgarden.dev
+Project-URL: Repository, https://github.com/tjb/SDKGarden
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# sdk-garden-python
+*Lightweight SDK observability client for Python — stdlib only, non-blocking*
+
+Add SDK Garden telemetry to your Python SDK in minutes. Events are sent on a background daemon thread — your users never see a delay or an exception from the instrumentation layer.
+
+## Install
+
+```bash
+pip install sdk-garden-python
+```
+
+## Quick Start
+
+```python
+from sdk_garden import SdkGarden
+
+sg = SdkGarden(api_key="YOUR_API_KEY", sdk_name="my-sdk", sdk_version="1.0.0").start()
+
+@sg.track_method("process_payment")
+def process_payment(amount):
+    ...
+```
+
+Track arbitrary events:
+
+```python
+sg.track("feature_used", properties={"feature": "streaming"})
+```
+
+Track errors with automatic PII scrubbing:
+
+```python
+try:
+    process_payment(100)
+except Exception as e:
+    sg.track_error(e)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your SDK Garden API key (`sgk_...`) |
+| `sdk_name` | `str` | required | Name of your SDK (e.g. `"my-payments-sdk"`) |
+| `sdk_version` | `str` | required | Version of your SDK (e.g. `"1.2.3"`) |
+| `endpoint` | `str` | `https://ingest.sdkgarden.dev/track` | Ingest endpoint URL |
+| `debug` | `bool` | `False` | Print `[SDK Garden]` debug lines to stdout |
+| `disabled` | `bool` | `False` | Disable all tracking (no thread spawned, no network calls) |
+| `batch_size` | `int` | `10` | Maximum events per HTTP POST |
+| `flush_interval` | `float` | `5.0` | Seconds between flush cycles |
+| `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+
+## What gets sent
+
+Each event carries your SDK's name and version, an event type, a random session ID created per client instance, and a timestamp. Depending on the event:
+
+- **`sdk_initialized`** (sent by `start()`): Python implementation and version, and `time_to_init_ms`.
+- **`method_called` / `method_success`**: method name, duration, and the *number* of positional arguments.
+- **`sdk_error`**: error type and message (email addresses are redacted) plus the method and duration.
+
+Never sent: argument or return values, request or response bodies, stack traces, hostnames, environment variables or user identifiers. Nothing is sent when `disabled=True`.
+
+### Telling your users
+
+Copy this into your SDK's README or privacy docs so your users know what's collected (edit the names to match):
+
+> **Telemetry.** This SDK reports anonymous usage data to its maintainers through [SDK Garden](https://github.com/tjb/SDKGarden): the SDK version, runtime version, which SDK methods are called, how long they take, and error types. It never sends your data, request contents or personal information. To opt out, set `YOUR_SDK_TELEMETRY_DISABLED=1` *(wire this environment variable to `disabled=True` in your SDK)*.
+
+## Behaviour Guarantees
+
+**All network errors are caught and discarded. Your program will never see an exception from sdk-garden-python.**
+
+**Runs on a daemon thread — your program exits normally even if events are queued.** When the process exits the daemon thread is killed automatically; any unsent events in the buffer are dropped. This is intentional — sdk-garden-python prioritises zero impact on your SDK over delivery guarantees.
+
+**Pass `disabled=True` in test environments to suppress all network calls.** When disabled, `start()` returns immediately without spawning a thread, and `track()` / `track_method()` / `track_error()` are all no-ops.
+
+**HTTP requests use a 2-second timeout.** Slow or unreachable ingest endpoints are silently abandoned after 2 seconds.
+
+**Queue overflow is silent.** The internal queue holds a maximum of 100 events. If your SDK generates events faster than the flush thread can drain them, new events are discarded without raising an exception.
+
+## Notes
+
+- `start()` must be called before events are flushed. Calling `track()` before `start()` is safe — events are queued and will be flushed once `start()` is called.
+- `track_method()` returns a decorator. The decorated function behaves identically to the original; timing and error telemetry are captured transparently.
+- Error messages passed to `track_error()` are PII-scrubbed: email addresses matching the standard `user@example.com` pattern are replaced with `[REDACTED]` before the event is enqueued.
+
+## License
+
+MIT

sdk_garden_python-0.1.0/README.md

@@ -0,0 +1,89 @@
+# sdk-garden-python
+*Lightweight SDK observability client for Python — stdlib only, non-blocking*
+
+Add SDK Garden telemetry to your Python SDK in minutes. Events are sent on a background daemon thread — your users never see a delay or an exception from the instrumentation layer.
+
+## Install
+
+```bash
+pip install sdk-garden-python
+```
+
+## Quick Start
+
+```python
+from sdk_garden import SdkGarden
+
+sg = SdkGarden(api_key="YOUR_API_KEY", sdk_name="my-sdk", sdk_version="1.0.0").start()
+
+@sg.track_method("process_payment")
+def process_payment(amount):
+    ...
+```
+
+Track arbitrary events:
+
+```python
+sg.track("feature_used", properties={"feature": "streaming"})
+```
+
+Track errors with automatic PII scrubbing:
+
+```python
+try:
+    process_payment(100)
+except Exception as e:
+    sg.track_error(e)
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Your SDK Garden API key (`sgk_...`) |
+| `sdk_name` | `str` | required | Name of your SDK (e.g. `"my-payments-sdk"`) |
+| `sdk_version` | `str` | required | Version of your SDK (e.g. `"1.2.3"`) |
+| `endpoint` | `str` | `https://ingest.sdkgarden.dev/track` | Ingest endpoint URL |
+| `debug` | `bool` | `False` | Print `[SDK Garden]` debug lines to stdout |
+| `disabled` | `bool` | `False` | Disable all tracking (no thread spawned, no network calls) |
+| `batch_size` | `int` | `10` | Maximum events per HTTP POST |
+| `flush_interval` | `float` | `5.0` | Seconds between flush cycles |
+| `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+
+## What gets sent
+
+Each event carries your SDK's name and version, an event type, a random session ID created per client instance, and a timestamp. Depending on the event:
+
+- **`sdk_initialized`** (sent by `start()`): Python implementation and version, and `time_to_init_ms`.
+- **`method_called` / `method_success`**: method name, duration, and the *number* of positional arguments.
+- **`sdk_error`**: error type and message (email addresses are redacted) plus the method and duration.
+
+Never sent: argument or return values, request or response bodies, stack traces, hostnames, environment variables or user identifiers. Nothing is sent when `disabled=True`.
+
+### Telling your users
+
+Copy this into your SDK's README or privacy docs so your users know what's collected (edit the names to match):
+
+> **Telemetry.** This SDK reports anonymous usage data to its maintainers through [SDK Garden](https://github.com/tjb/SDKGarden): the SDK version, runtime version, which SDK methods are called, how long they take, and error types. It never sends your data, request contents or personal information. To opt out, set `YOUR_SDK_TELEMETRY_DISABLED=1` *(wire this environment variable to `disabled=True` in your SDK)*.
+
+## Behaviour Guarantees
+
+**All network errors are caught and discarded. Your program will never see an exception from sdk-garden-python.**
+
+**Runs on a daemon thread — your program exits normally even if events are queued.** When the process exits the daemon thread is killed automatically; any unsent events in the buffer are dropped. This is intentional — sdk-garden-python prioritises zero impact on your SDK over delivery guarantees.
+
+**Pass `disabled=True` in test environments to suppress all network calls.** When disabled, `start()` returns immediately without spawning a thread, and `track()` / `track_method()` / `track_error()` are all no-ops.
+
+**HTTP requests use a 2-second timeout.** Slow or unreachable ingest endpoints are silently abandoned after 2 seconds.
+
+**Queue overflow is silent.** The internal queue holds a maximum of 100 events. If your SDK generates events faster than the flush thread can drain them, new events are discarded without raising an exception.
+
+## Notes
+
+- `start()` must be called before events are flushed. Calling `track()` before `start()` is safe — events are queued and will be flushed once `start()` is called.
+- `track_method()` returns a decorator. The decorated function behaves identically to the original; timing and error telemetry are captured transparently.
+- Error messages passed to `track_error()` are PII-scrubbed: email addresses matching the standard `user@example.com` pattern are replaced with `[REDACTED]` before the event is enqueued.
+
+## License
+
+MIT

sdk_garden_python-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sdk-garden-python"
+version = "0.1.0"
+description = "Lightweight SDK observability client for Python — stdlib only, non-blocking"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+
+[project.urls]
+Homepage = "https://sdkgarden.dev"
+Repository = "https://github.com/tjb/SDKGarden"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sdk_garden"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sdk_garden_python-0.1.0/requirements-dev.txt

@@ -0,0 +1 @@
+pytest==9.0.3

sdk_garden_python-0.1.0/sdk_garden/__init__.py

@@ -0,0 +1,3 @@
+from sdk_garden.client import SdkGarden
+
+__all__ = ["SdkGarden"]

sdk_garden_python-0.1.0/sdk_garden/client.py

@@ -0,0 +1,287 @@
+"""
+sdk_garden.client — Lightweight SDK observability client for Python.
+
+Stdlib only, non-blocking, zero runtime dependencies.
+Events are queued on the caller's thread and flushed in batches by a daemon thread.
+All network errors are caught and discarded — no exception ever reaches the caller.
+"""
+
+import functools
+import json
+import platform
+import queue
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ---------------------------------------------------------------------------
+# Module-level constants
+# ---------------------------------------------------------------------------
+
+_DEFAULT_ENDPOINT = "https://ingest.sdkgarden.dev/track"
+
+#: Maximum number of events sent in one HTTP POST.
+_BATCH_SIZE = 10  # Claude's Discretion — per CONTEXT.md
+
+#: Seconds the daemon thread sleeps between flush cycles.
+_FLUSH_INTERVAL = 5.0  # seconds — Claude's Discretion
+
+#: HTTP request timeout in seconds. Locked by CLIENT-02.
+_HTTP_TIMEOUT = 2  # seconds — locked by CLIENT-02
+
+#: Email-address PII pattern ported verbatim from sdk-garden.js lines 174-177.
+#: When this module was imported: the default start of the host SDK's init.
+_MODULE_LOADED_AT = time.time()
+
+_PII_PATTERN = re.compile(
+    r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"
+)
+
+
+class SdkGarden:
+    """Non-blocking SDK observability client — stdlib only.
+
+    Instantiate and call `.start()` to begin flushing:
+
+        sg = SdkGarden(api_key="sgk_...", sdk_name="my-sdk", sdk_version="1.0.0").start()
+
+    ``start()`` sends the ``sdk_initialized`` event (runtime, Python version and
+    ``time_to_init_ms``) for you.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        sdk_name: str,
+        sdk_version: str,
+        endpoint: str = _DEFAULT_ENDPOINT,
+        debug: bool = False,
+        disabled: bool = False,
+        batch_size: int = _BATCH_SIZE,
+        flush_interval: float = _FLUSH_INTERVAL,
+        started_at: Optional[float] = None,
+    ) -> None:
+        """Create a client. Nothing is sent until ``start()``.
+
+        ``started_at`` is when your SDK began initializing, as ``time.time()``;
+        ``start()`` reports the difference as ``time_to_init_ms``. Defaults to
+        when sdk_garden was imported.
+        """
+        self._api_key = api_key
+        self._sdk_name = sdk_name
+        self._sdk_version = sdk_version
+        self._endpoint = endpoint
+        self._debug = debug
+        self._disabled = disabled
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+        self._started_at = started_at if started_at is not None else _MODULE_LOADED_AT
+
+        #: True once start() has sent sdk_initialized for this session.
+        self._init_sent = False
+
+        #: Thread-safe event queue. maxsize=100 locked by D-04/D-05.
+        self._queue: queue.Queue = queue.Queue(maxsize=100)
+
+        #: Per-instance session identifier (UUID4).
+        self._session_id: str = str(uuid.uuid4())
+
+        #: Daemon flush thread — None until start() is called.
+        self._thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> "SdkGarden":
+        """Spawn the daemon flush thread and return self for chaining.
+
+        When disabled=True, returns immediately without spawning a thread.
+        Idempotent — subsequent calls while the thread is alive are no-ops.
+        """
+        if self._disabled:
+            return self
+        if self._thread is not None and self._thread.is_alive():
+            return self
+        if not self._init_sent:
+            self.track(
+                "sdk_initialized",
+                {
+                    "environment": self._get_environment(),
+                    "time_to_init_ms": max(0, int((time.time() - self._started_at) * 1000)),
+                },
+            )
+            self._init_sent = True
+        self._thread = threading.Thread(target=self._flush_loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def track(
+        self,
+        event_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Enqueue a named event.
+
+        Silently discards if the queue is full (D-05) or disabled.
+        Never blocks the caller.
+        """
+        if self._disabled:
+            return
+        if event_name == "sdk_initialized" and self._init_sent:
+            # start() already reported it; a manual call (as older docs
+            # suggested) would double-count the session.
+            return
+        event = {
+            "event": event_name,
+            "sdk": {"name": self._sdk_name, "version": self._sdk_version},
+            "session_id": self._session_id,
+            "timestamp": int(time.time() * 1000),
+            "properties": properties or {},
+            "meta": {},
+        }
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            pass  # Silent discard — locked by D-05, never blocks caller
+
+    def track_method(self, method_name: str) -> Callable[[F], F]:
+        """Return a decorator that wraps a function with method-call telemetry.
+
+        Always enqueues a ``method_called`` event before the call.
+        On success: also enqueues a ``method_success`` event with ``duration_ms``.
+        On exception: enqueues an ``sdk_error`` event with PII-scrubbed message
+        and re-raises the original exception.
+
+        When disabled, the original function is returned unwrapped.
+        """
+        if self._disabled:
+            def _noop_decorator(fn: F) -> F:
+                return fn
+
+            return _noop_decorator  # type: ignore[return-value]
+
+        def decorator(fn: F) -> F:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                start = time.time()
+                self.track(
+                    "method_called",
+                    {"method": method_name, "args_count": len(args)},
+                )
+                try:
+                    result = fn(*args, **kwargs)
+                    duration_ms = int((time.time() - start) * 1000)
+                    self.track(
+                        "method_success",
+                        {
+                            "method": method_name,
+                            "duration_ms": duration_ms,
+                        },
+                    )
+                    return result
+                except Exception as exc:
+                    duration_ms = int((time.time() - start) * 1000)
+                    self.track_error(exc, {"method": method_name, "duration_ms": duration_ms})
+                    raise
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorator  # type: ignore[return-value]
+
+    def track_error(
+        self,
+        error: Exception,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Enqueue an ``sdk_error`` event with PII-scrubbed error message.
+
+        Silently discards if disabled.
+        """
+        if self._disabled:
+            return
+        props: Dict[str, Any] = {
+            "error_message": self._scrub_pii(str(error)),
+            "error_type": type(error).__name__,
+        }
+        if context:
+            props.update(context)
+        self.track("sdk_error", props)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _flush_loop(self) -> None:
+        """Daemon thread target — wakes every flush_interval and drains the queue."""
+        while True:
+            self._flush_batch()
+            time.sleep(self._flush_interval)
+
+    def _flush_batch(self) -> None:
+        """Drain up to batch_size events from the queue and POST them.
+
+        Silent on all network errors (Pitfall 5: broad except required because
+        socket.timeout is not a subclass of urllib.error.URLError).
+        """
+        events = []
+        try:
+            while len(events) < self._batch_size:
+                events.append(self._queue.get_nowait())
+        except queue.Empty:
+            pass
+
+        if not events:
+            return  # Nothing to flush — no HTTP call
+
+        try:
+            payload = json.dumps(
+                {
+                    "api_key": self._api_key,
+                    "events": events,
+                }
+            ).encode("utf-8")
+            req = urllib.request.Request(
+                self._endpoint,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT)
+        except Exception:
+            pass  # Silent failure — ALL exceptions swallowed (Pitfall 5)
+
+    def _scrub_pii(self, s: Any) -> Any:
+        """Replace email addresses in a string with '[REDACTED]'.
+
+        Non-string values are returned unchanged.
+        Ported verbatim from sdk-garden.js lines 174-177.
+        """
+        if not isinstance(s, str):
+            return s
+        return _PII_PATTERN.sub("[REDACTED]", s)
+
+    def _log(self, *args: Any) -> None:
+        """Print a debug message when debug=True.
+
+        NEVER pass self._api_key directly to this method.
+        """
+        if self._debug:
+            print("[SDK Garden]", *args)
+
+    def _get_environment(self) -> Dict[str, str]:
+        """Return runtime environment metadata for the sdk_initialized event."""
+        return {
+            "runtime": platform.python_implementation().lower(),
+            "runtime_version": platform.python_version(),
+        }
+
+    def _generate_session_id(self) -> str:
+        """Generate a random UUID4 session identifier."""
+        return str(uuid.uuid4())

sdk_garden_python-0.1.0/tests/test_client.py

@@ -0,0 +1,210 @@
+"""
+pytest unit tests for sdk-garden-python CLIENT-02 behaviors.
+
+All tests use endpoint='http://localhost:9999/track' — never hits the network.
+"""
+import queue
+import socket
+import threading
+import time
+from unittest.mock import patch, MagicMock, call
+
+import pytest
+
+from sdk_garden import SdkGarden
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def make_sg(**kwargs):
+    """Factory for a fresh SdkGarden instance pointing at a dummy endpoint."""
+    defaults = dict(
+        api_key="sgk_testkey",
+        sdk_name="test-sdk",
+        sdk_version="1.0.0",
+        endpoint="http://localhost:9999/track",
+    )
+    defaults.update(kwargs)
+    return SdkGarden(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# class TestInit
+# ---------------------------------------------------------------------------
+
+class TestInit:
+    def test_start_spawns_daemon_thread(self):
+        sg = make_sg()
+        sg.start()
+        assert sg._thread is not None
+        assert sg._thread.daemon is True
+        assert sg._thread.is_alive() is True
+
+    def test_disabled_start_does_not_spawn_thread(self):
+        sg = make_sg(disabled=True)
+        sg.start()
+        assert sg._thread is None
+
+    def test_session_id_is_set(self):
+        sg = make_sg()
+        assert isinstance(sg._session_id, str)
+        assert len(sg._session_id) > 0
+
+
+# ---------------------------------------------------------------------------
+# class TestTrack
+# ---------------------------------------------------------------------------
+
+class TestTrack:
+    def test_track_enqueues_event(self):
+        sg = make_sg()
+        before = sg._queue.qsize()
+        sg.track("sdk_initialized")
+        assert sg._queue.qsize() == before + 1
+
+    def test_track_event_shape(self):
+        sg = make_sg()
+        sg.track("sdk_initialized", {"key": "value"})
+        event = sg._queue.get_nowait()
+        assert "event" in event
+        assert "sdk" in event
+        assert "session_id" in event
+        assert "timestamp" in event
+        assert "properties" in event
+        assert "meta" in event
+        assert event["event"] == "sdk_initialized"
+        assert event["sdk"]["name"] == "test-sdk"
+        assert event["sdk"]["version"] == "1.0.0"
+
+    def test_track_drops_when_queue_full(self):
+        sg = make_sg()
+        # Fill the queue to maxsize=100
+        for _ in range(100):
+            sg._queue.put_nowait({"event": "dummy"})
+        # This must NOT raise and queue size must stay at 100
+        sg.track("sdk_initialized")
+        assert sg._queue.qsize() == 100
+
+    def test_track_disabled_noop(self):
+        sg = make_sg(disabled=True)
+        sg.track("sdk_initialized")
+        assert sg._queue.qsize() == 0
+
+
+# ---------------------------------------------------------------------------
+# class TestFlushBatch
+# ---------------------------------------------------------------------------
+
+class TestFlushBatch:
+    def test_flush_batch_posts_events(self):
+        sg = make_sg()
+        sg.track("sdk_initialized")
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = MagicMock(status=200)
+            sg._flush_batch()
+            assert mock_urlopen.called
+
+    def test_flush_batch_timeout_is_2_seconds(self):
+        sg = make_sg()
+        sg.track("sdk_initialized")
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = MagicMock(status=200)
+            sg._flush_batch()
+            # Verify the timeout keyword argument is 2
+            args, kwargs = mock_urlopen.call_args
+            assert kwargs.get("timeout") == 2
+
+    def test_flush_batch_silent_on_network_error(self):
+        sg = make_sg()
+        sg.track("sdk_initialized")
+        with patch("urllib.request.urlopen", side_effect=Exception("network down")):
+            # Must NOT raise
+            sg._flush_batch()
+
+    def test_flush_batch_silent_on_timeout_error(self):
+        sg = make_sg()
+        sg.track("sdk_initialized")
+        with patch("urllib.request.urlopen", side_effect=socket.timeout("timed out")):
+            # Must NOT raise
+            sg._flush_batch()
+
+    def test_flush_batch_noop_when_empty(self):
+        sg = make_sg()
+        with patch("urllib.request.urlopen") as mock_urlopen:
+            sg._flush_batch()
+            mock_urlopen.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# class TestPIIScrub
+# ---------------------------------------------------------------------------
+
+class TestPIIScrub:
+    def test_scrub_pii_in_error_message(self):
+        sg = make_sg()
+        error = Exception("Failed for user@example.com at login")
+        sg.track_error(error)
+        event = sg._queue.get_nowait()
+        error_msg = event["properties"]["error_message"]
+        assert "user@example.com" not in error_msg
+        assert "[REDACTED]" in error_msg
+
+    def test_scrub_pii_non_string_passthrough(self):
+        sg = make_sg()
+        # _scrub_pii should return non-strings unchanged
+        assert sg._scrub_pii(42) == 42
+        assert sg._scrub_pii(None) is None
+
+    def test_scrub_pii_removes_email(self):
+        sg = make_sg()
+        result = sg._scrub_pii("Contact admin@corp.io for support")
+        assert "admin@corp.io" not in result
+        assert "[REDACTED]" in result
+
+
+# ---------------------------------------------------------------------------
+# class TestStartupEvent
+# ---------------------------------------------------------------------------
+
+class TestStartupEvent:
+    @pytest.fixture(autouse=True)
+    def _no_flush_thread(self):
+        # Keep events in the queue so the test can inspect them.
+        with patch.object(SdkGarden, "_flush_loop", lambda self: None):
+            yield
+
+    def _drain(self, sg):
+        events = []
+        while not sg._queue.empty():
+            events.append(sg._queue.get_nowait())
+        return events
+
+    def test_start_sends_sdk_initialized_with_environment_and_timing(self):
+        sg = make_sg(started_at=time.time() - 0.25, flush_interval=3600)
+        sg.start()
+        events = self._drain(sg)
+        assert [e["event"] for e in events] == ["sdk_initialized"]
+        props = events[0]["properties"]
+        assert props["environment"]["runtime"] == "cpython"
+        assert props["environment"]["runtime_version"].count(".") == 2
+        assert 250 <= props["time_to_init_ms"] < 5000
+
+    def test_start_twice_and_manual_track_do_not_double_count(self):
+        sg = make_sg(flush_interval=3600)
+        sg.start()
+        sg.start()
+        sg.track("sdk_initialized")
+        events = self._drain(sg)
+        assert [e["event"] for e in events] == ["sdk_initialized"]
+
+    def test_time_to_init_is_never_negative(self):
+        sg = make_sg(started_at=time.time() + 60, flush_interval=3600)
+        sg.start()
+        assert self._drain(sg)[0]["properties"]["time_to_init_ms"] == 0
+
+    def test_disabled_start_sends_nothing(self):
+        sg = make_sg(disabled=True)
+        sg.start()
+        assert sg._queue.empty()