deepctl-telemetry 0.0.2__py3-none-any.whl

deepctl_telemetry/__init__.py

@@ -0,0 +1,13 @@
+"""Opt-out phone-home telemetry for deepctl."""
+
+from .client import init_telemetry, is_enabled
+from .notice import install_help_notice, render_notice
+
+__all__ = [
+    "init_telemetry",
+    "install_help_notice",
+    "is_enabled",
+    "render_notice",
+]
+
+__version__ = "0.0.2"  # x-release-please-version

deepctl_telemetry/client.py

@@ -0,0 +1,109 @@
+"""Sentry-backed telemetry client with strict opt-out."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from deepctl_core import Config
+    from sentry_sdk.types import Event, Hint
+
+
+SENTRY_DSN = (
+    "https://d7a2aabbf772218e3bbe89266999af70"
+    "@o206115.ingest.us.sentry.io/4510993603362816"
+)
+
+DSN_ENV_VAR = "DEEPCTL_TELEMETRY_DSN"
+DISABLE_ENV_VAR = "DEEPCTL_TELEMETRY_DISABLED"
+
+_initialized = False
+
+
+def is_enabled(config: Config) -> bool:
+    """Whether telemetry should phone home for this invocation.
+
+    Resolution order: env override (DEEPCTL_TELEMETRY_DISABLED=1 wins),
+    then the user's config (`telemetry.enabled`, default `True`).
+    """
+    if os.environ.get(DISABLE_ENV_VAR, "").lower() in {"1", "true", "yes"}:
+        return False
+    return bool(config.get("telemetry.enabled", True))
+
+
+def init_telemetry(config: Config) -> bool:
+    """Initialize the Sentry SDK if telemetry is enabled.
+
+    Idempotent — safe to call multiple times. Returns whether init ran.
+    """
+    global _initialized
+    if _initialized:
+        return True
+    if not is_enabled(config):
+        return False
+
+    dsn = os.environ.get(DSN_ENV_VAR) or SENTRY_DSN
+
+    try:
+        import sentry_sdk
+    except ImportError:
+        return False
+
+    try:
+        cli_version = _read_cli_version()
+    except Exception:
+        cli_version = "unknown"
+
+    sentry_sdk.init(
+        dsn=dsn,
+        release=f"deepctl@{cli_version}",
+        environment="production",
+        send_default_pii=False,
+        traces_sample_rate=0.0,
+        profiles_sample_rate=0.0,
+        max_breadcrumbs=20,
+        before_send=_scrub_event,
+    )
+
+    sentry_sdk.set_tag("cli.os", platform.system().lower())
+    sentry_sdk.set_tag("cli.arch", platform.machine().lower())
+    sentry_sdk.set_tag(
+        "cli.python",
+        f"{sys.version_info.major}.{sys.version_info.minor}",
+    )
+    sentry_sdk.set_tag("cli.version", cli_version)
+
+    _initialized = True
+    return True
+
+
+def _read_cli_version() -> str:
+    import importlib.metadata
+
+    return importlib.metadata.version("deepctl")
+
+
+def _scrub_event(event: Event, _hint: Hint) -> Event | None:
+    """Drop request bodies, headers, and any user-identifying data.
+
+    Sentry SDK already filters most PII via send_default_pii=False, but
+    Auth tokens, project IDs, and file paths can still leak through
+    breadcrumbs and exception messages. This is a defense-in-depth scrub.
+    """
+    request: dict[str, Any] = event.get("request") or {}
+    if "headers" in request:
+        request["headers"] = {}
+    if "cookies" in request:
+        request["cookies"] = {}
+    if "data" in request:
+        request["data"] = "[Filtered]"
+
+    user: dict[str, Any] = event.get("user") or {}
+    user.pop("email", None)
+    user.pop("ip_address", None)
+    user.pop("username", None)
+
+    return event

deepctl_telemetry/notice.py

@@ -0,0 +1,48 @@
+"""Subtle telemetry notice appended to `--help` output."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from deepctl_core import Config
+
+
+NOTICE_ON = (
+    "Telemetry is on (anonymous error reports). "
+    "Disable: dg config set telemetry.enabled false"
+)
+NOTICE_OFF = "Telemetry is off."
+
+_installed = False
+
+
+def render_notice(config: Config) -> str:
+    """Return the dim one-line notice for the current telemetry state."""
+    from .client import is_enabled
+
+    text = NOTICE_ON if is_enabled(config) else NOTICE_OFF
+    return click.style(text, dim=True)
+
+
+def install_help_notice(config: Config) -> None:
+    """Monkey-patch Click so every `--help` ends with the telemetry notice.
+
+    Click formats help via `Command.get_help(ctx)`. We wrap that method
+    once at startup so every command (including subcommands and plugin
+    commands) picks up the footer without needing per-command wiring.
+    """
+    global _installed
+    if _installed:
+        return
+
+    original_get_help = click.Command.get_help
+    notice = render_notice(config)
+
+    def get_help_with_notice(self: click.Command, ctx: click.Context) -> str:
+        return original_get_help(self, ctx) + "\n\n" + notice
+
+    click.Command.get_help = get_help_with_notice  # type: ignore[method-assign]
+    _installed = True

deepctl_telemetry-0.0.2.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: deepctl-telemetry
+Version: 0.0.2
+Summary: Opt-out phone-home telemetry for deepctl
+Author-email: Deepgram <devrel@deepgram.com>
+Maintainer-email: Deepgram <devrel@deepgram.com>
+License-Expression: MIT
+Keywords: deepgram,cli,telemetry,sentry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: deepctl-core>=0.1.10
+Requires-Dist: sentry-sdk>=2.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+
+# deepctl-telemetry
+
+> Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
+
+Opt-out phone-home telemetry for deepctl
+
+This package provides internal APIs for deepctl and its command packages. It is not intended for direct use.
+
+## Installation
+
+This package is included with deepctl and does not need to be installed separately.
+
+### Install deepctl
+
+```bash
+# Install with pip
+pip install deepctl
+
+# Or install with uv
+uv tool install deepctl
+
+# Or install with pipx
+pipx install deepctl
+
+# Or run without installing
+uvx deepctl --help
+pipx run deepctl --help
+```
+
+## Dependencies
+
+- `sentry-sdk>=2.0.0`
+- `click>=8.0.0`
+- `rich>=13.0.0`
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

deepctl_telemetry-0.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+deepctl_telemetry/__init__.py,sha256=l5Zba-BzAA11XF35xbnf1mgbYrzKXoGRHy9BNL7Zogc,305
+deepctl_telemetry/client.py,sha256=VNwJISePtQTQ4igNgc2rMg7zZcay44HIurGZxpUbW08,2930
+deepctl_telemetry/notice.py,sha256=SdpDV-a0jNRZkitnKOlfN0-whJAzwMeXgGz9iimr7gY,1357
+deepctl_telemetry-0.0.2.dist-info/METADATA,sha256=A_sHNVzJROSK6ucTut3YO4WyAH-YHZC2lAgjsSEF3Gw,1462
+deepctl_telemetry-0.0.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+deepctl_telemetry-0.0.2.dist-info/top_level.txt,sha256=II7mx3AjWibH9PFEoWhcsXgeacQZPazJ_iNkAXnfSBw,18
+deepctl_telemetry-0.0.2.dist-info/RECORD,,

deepctl_telemetry-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepctl_telemetry-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepctl_telemetry