devhelm 0.5.0__tar.gz → 0.6.0__tar.gz

{devhelm-0.5.0 → devhelm-0.6.0}/.github/workflows/spec-check.yml

@@ -20,19 +20,45 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: '3.13'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
 
       - name: Download latest OpenAPI spec from monorepo
         run: |
           gh api repos/devhelmhq/mono/contents/docs/openapi/monitoring-api.json \
             -H "Accept: application/vnd.github.raw+json" \
-            -o docs/openapi/monitoring-api.json
+            > docs/openapi/monitoring-api.json
         env:
           GH_TOKEN: ${{ secrets.MONOREPO_DISPATCH_TOKEN }}
 
+      # Sparse-checkout the shared OpenAPI preprocessor from mono.
+      # typegen.sh prefers $OPENAPI_TOOLS → local sibling → npx; without this
+      # step, CI falls through to `npx @devhelm/openapi-tools` which is
+      # intentionally unpublished (internal-only package).
+      - name: Checkout @devhelm/openapi-tools from mono
+        uses: actions/checkout@v4
+        with:
+          repository: devhelmhq/mono
+          token: ${{ secrets.MONOREPO_DISPATCH_TOKEN }}
+          path: .mono
+          sparse-checkout: packages/openapi-tools
+          sparse-checkout-cone-mode: false
+
+      - name: Build @devhelm/openapi-tools
+        working-directory: .mono/packages/openapi-tools
+        # mono uses pnpm workspaces; we only need this one package's deps here,
+        # so install standalone with npm (no lockfile in this subdir).
+        run: |
+          npm install --no-package-lock --no-audit --no-fund
+          npm run build
+
       - run: uv sync
       - run: uv run pytest -v
 
       - name: Regenerate types from spec
+        env:
+          OPENAPI_TOOLS: node ${{ github.workspace }}/.mono/packages/openapi-tools/dist/cli.js
         run: ./scripts/typegen.sh
 
       - name: Check for type changes

{devhelm-0.5.0 → devhelm-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devhelm
-Version: 0.5.0
+Version: 0.6.0
 Summary: DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more
 Project-URL: Homepage, https://github.com/devhelmhq/sdk-python
 Project-URL: Repository, https://github.com/devhelmhq/sdk-python.git

{devhelm-0.5.0 → devhelm-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devhelm"
-version = "0.5.0"
+version = "0.6.0"
 description = "DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more"
 authors = [{ name = "DevHelm", email = "hello@devhelm.io" }]
 license = "MIT"

{devhelm-0.5.0 → devhelm-0.6.0}/scripts/typegen.sh

@@ -55,7 +55,8 @@ uv run datamodel-codegen \
   --enum-field-as-literal one \
   --use-one-literal-as-default \
   --input-file-type openapi \
-  --formatters ruff-format
+  --formatters ruff-format \
+  --disable-timestamp
 
 # Why --enum-field-as-literal=one + --use-one-literal-as-default?
 #

{devhelm-0.5.0 → devhelm-0.6.0}/src/devhelm/_generated.py

@@ -1,6 +1,5 @@
 # generated by datamodel-codegen:
 #   filename:  .openapi-preprocessed.json
-#   timestamp: 2026-04-29T17:00:31+00:00
 
 from __future__ import annotations
 from typing import Annotated, Any, Literal

{devhelm-0.5.0 → devhelm-0.6.0}/src/devhelm/_http.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
 from typing import Any
 from urllib.parse import quote
 
@@ -17,6 +19,26 @@ from devhelm._errors import (
 DEFAULT_BASE_URL = "https://api.devhelm.io"
 DEFAULT_PAGE_SIZE = 200
 
+# Default surface identifier sent on every authenticated request. Wrappers
+# (e.g. the MCP server) override this at construction time so the API can
+# attribute usage to the right devtool. See ``DevhelmConfig.surface``.
+DEFAULT_SURFACE = "sdk-py"
+
+
+def _sdk_version() -> str:
+    """Resolve the installed package version once at import time.
+
+    Uses ``importlib.metadata`` instead of hardcoding so a single source of
+    truth (``pyproject.toml``) flows through to the wire telemetry header.
+    Falls back to ``"unknown"`` for editable / source-tree installs that
+    don't yet have a dist-info directory; the API treats that as "no version
+    reported" rather than rejecting the request.
+    """
+    try:
+        return _pkg_version("devhelm")
+    except PackageNotFoundError:
+        return "unknown"
+
 
 @dataclass(frozen=True)
 class DevhelmConfig:
@@ -27,6 +49,19 @@ class DevhelmConfig:
     org_id: str | None = None
     workspace_id: str | None = None
     timeout: float = 30.0
+    # Devtool surface identifier reported to the API for adoption and
+    # version-distribution telemetry. Defaults to ``"sdk-py"``; wrappers
+    # such as the MCP server pass ``"mcp"`` instead so their traffic is
+    # attributed correctly. See https://devhelm.io/telemetry for the full
+    # contract and opt-out semantics.
+    surface: str = DEFAULT_SURFACE
+    # Surface version. Defaults to the installed ``devhelm`` package
+    # version; wrappers should pass their own package version.
+    surface_version: str | None = None
+    # Surface-specific metadata forwarded as ``X-DevHelm-*`` headers (e.g.
+    # the MCP server attaches ``mcp_client``). Keys are normalised to
+    # lower-kebab-case and mapped onto ``X-DevHelm-<key>`` on the wire.
+    surface_metadata: dict[str, str] = field(default_factory=dict)
 
 
 def _resolve(value: str | None, env_key: str, label: str) -> str:
@@ -42,6 +77,30 @@ def _resolve_optional(value: str | None, env_key: str, default: str) -> str:
     return value or os.environ.get(env_key) or default
 
 
+def _telemetry_headers(config: DevhelmConfig) -> dict[str, str]:
+    """Build the ``X-DevHelm-Surface*`` headers for one client instance.
+
+    Returns an empty dict when ``DEVHELM_TELEMETRY=0`` so the API receives
+    no surface signal at all. The opt-out is intentionally a single env var
+    rather than a constructor flag — users opt out once for the whole
+    process, not per call site. See https://devhelm.io/telemetry.
+    """
+    if os.environ.get("DEVHELM_TELEMETRY", "").strip() == "0":
+        return {}
+    headers: dict[str, str] = {
+        "X-DevHelm-Surface": config.surface,
+        "X-DevHelm-Surface-Version": config.surface_version or _sdk_version(),
+        # Always identify the underlying SDK so the API can distinguish
+        # "raw SDK call" from "wrapper-on-top-of-SDK call" (the latter
+        # overrides ``Surface`` to e.g. ``mcp`` but the SDK fingerprint
+        # stays available for debugging client-version skew).
+        "X-DevHelm-Sdk-Name": "sdk-py",
+    }
+    for key, value in config.surface_metadata.items():
+        headers[f"X-DevHelm-{key}"] = value
+    return headers
+
+
 def build_client(config: DevhelmConfig) -> httpx.Client:
     """Create a configured httpx.Client with auth and tenant headers."""
     base_url = config.base_url.rstrip("/")
@@ -56,6 +115,7 @@ def build_client(config: DevhelmConfig) -> httpx.Client:
             "Content-Type": "application/json",
             "x-phelm-org-id": org_id,
             "x-phelm-workspace-id": workspace_id,
+            **_telemetry_headers(config),
         },
         timeout=config.timeout,
     )

{devhelm-0.5.0 → devhelm-0.6.0}/src/devhelm/client.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from devhelm._http import DevhelmConfig, build_client
+from devhelm._http import DEFAULT_SURFACE, DevhelmConfig, build_client
 from devhelm.resources.alert_channels import AlertChannels
 from devhelm.resources.api_keys import ApiKeys
 from devhelm.resources.dependencies import Dependencies
@@ -62,13 +62,24 @@ class Devhelm:
         org_id: str | None = None,
         workspace_id: str | None = None,
         timeout: float = 30.0,
+        surface: str | None = None,
+        surface_version: str | None = None,
+        surface_metadata: dict[str, str] | None = None,
     ) -> None:
+        # ``surface`` / ``surface_version`` / ``surface_metadata`` are passthroughs
+        # for wrappers (e.g. the MCP server) that want their traffic attributed
+        # to a different devtool surface than the default ``sdk-py``. End users
+        # of the SDK should leave these unset. See
+        # https://devhelm.io/telemetry for the wire contract and opt-out.
         config = DevhelmConfig(
             token=token,
             base_url=base_url,
             org_id=org_id,
             workspace_id=workspace_id,
             timeout=timeout,
+            surface=surface if surface is not None else DEFAULT_SURFACE,
+            surface_version=surface_version,
+            surface_metadata=surface_metadata if surface_metadata is not None else {},
         )
         client = build_client(config)
 

{devhelm-0.5.0 → devhelm-0.6.0}/tests/test_http.py

@@ -64,6 +64,62 @@ class TestBuildClient:
         client.close()
 
 
+# ---------- Surface telemetry headers ----------
+
+
+class TestSurfaceTelemetry:
+    """The SDK reports its identity to the API on every authenticated request
+    so the GTM rollup can attribute usage. See https://devhelm.io/telemetry."""
+
+    def test_default_headers_announce_sdk_py(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("DEVHELM_TELEMETRY", raising=False)
+        client = build_client(DevhelmConfig(token="t"))
+        assert client.headers["x-devhelm-surface"] == "sdk-py"
+        # version comes from importlib.metadata; its exact value is the
+        # SDK release, but it must always be a non-empty string.
+        assert client.headers["x-devhelm-surface-version"]
+        assert client.headers["x-devhelm-sdk-name"] == "sdk-py"
+        client.close()
+
+    def test_wrapper_can_override_surface(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("DEVHELM_TELEMETRY", raising=False)
+        client = build_client(
+            DevhelmConfig(
+                token="t",
+                surface="mcp",
+                surface_version="0.5.0",
+                surface_metadata={"Mcp-Client": "cursor"},
+            )
+        )
+        assert client.headers["x-devhelm-surface"] == "mcp"
+        assert client.headers["x-devhelm-surface-version"] == "0.5.0"
+        # SDK identity is preserved alongside the wrapper surface.
+        assert client.headers["x-devhelm-sdk-name"] == "sdk-py"
+        assert client.headers["x-devhelm-mcp-client"] == "cursor"
+        client.close()
+
+    def test_env_opt_out_drops_all_surface_headers(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("DEVHELM_TELEMETRY", "0")
+        client = build_client(
+            DevhelmConfig(token="t", surface="mcp", surface_metadata={"X": "y"})
+        )
+        # Surface, version, sdk-name, and any extras must all be absent.
+        assert "x-devhelm-surface" not in client.headers
+        assert "x-devhelm-surface-version" not in client.headers
+        assert "x-devhelm-sdk-name" not in client.headers
+        assert "x-devhelm-x" not in client.headers
+        # Auth + tenant headers must still be there — opt-out is for
+        # telemetry only, not for legitimate routing headers.
+        assert client.headers["x-phelm-org-id"] == "1"
+        client.close()
+
+
 # ---------- Pydantic validation helpers ----------
 
 

{devhelm-0.5.0 → devhelm-0.6.0}/uv.lock

@@ -315,7 +315,7 @@ wheels = [
 
 [[package]]
 name = "devhelm"
-version = "0.5.0"
+version = "0.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },