Coverage for /home/runner/work/bijux-cli/bijux-cli/src/bijux_cli/contracts/telemetry.py: 100%

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the fire-and-forget telemetry service. 

5 

6This module specifies the `TelemetryProtocol`, a formal interface that any 

7service responsible for collecting and managing "fire-and-forget" telemetry 

8or analytics events must implement. 

9""" 

10 

11from __future__ import annotations 

12 

13from collections.abc import Coroutine 

14from typing import Any, Protocol, runtime_checkable 

15 

16 

17@runtime_checkable 

18class TelemetryProtocol(Protocol): 

19 """Defines the contract for fire-and-forget analytics collection. 

20 

21 This interface specifies the methods for recording telemetry events and 

22 managing the lifecycle of the telemetry service. 

23 """ 

24 

25 def event( 

26 self, name: str, payload: dict[str, Any] 

27 ) -> None | Coroutine[Any, Any, None]: 

28 """Records a telemetry event. 

29 

30 Args: 

31 name (str): The name of the event (e.g., "COMMAND_START"). 

32 payload (dict[str, Any]): A dictionary of key-value pairs 

33 containing the event data. 

34 

35 Returns: 

36 Either None (sync) or an awaitable resolving to None (async). 

37 """ 

38 ... 

39 

40 def flush(self) -> None: 

41 """Flushes any buffered telemetry events to their destination.""" 

42 ... 

43 

44 def enable(self) -> None: 

45 """Enables the collection of telemetry data.""" 

46 ...