feat: Add foundation TypedDicts for method return types

Replace dict[str, ...] return types with specific TypedDicts:

**New Types Added:**
- NotificationFlags: _check_notifications return type
- DisplayTimes: _format_display_times return type
- ExtractedTokens: extract_tokens return type
- ExtractedMetadata: _extract_metadata return type

**Key Improvements:**
- Eliminates vague dict[str, Any] patterns
- Provides explicit field typing for return values
- Enhances IDE intellisense and type safety
- Foundation for remaining method typing work

**Type Safety Fixes:**
- Updated SessionBlock.limit_messages to use FormattedLimitInfo
- Fixed import paths for JSONSerializable and BlockData
- Maintained 100% mypy compliance

All tests maintain compatibility. Ready for aggregate and display logic TypedDict improvements.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: PabloLION

src/claude_monitor/core/data_processors.py

@@ -7,7 +7,7 @@
 from datetime import datetime
 from typing import cast
 
-from claude_monitor.types import ClaudeJSONEntry, JSONSerializable
+from claude_monitor.types import ClaudeJSONEntry, JSONSerializable, ExtractedTokens
 from claude_monitor.utils.time_utils import TimezoneHandler
 
 
@@ -69,7 +69,7 @@ class TokenExtractor:
     """Unified token extraction utilities."""
 
     @staticmethod
-    def extract_tokens(data: ClaudeJSONEntry) -> dict[str, int]:
+    def extract_tokens(data: ClaudeJSONEntry) -> ExtractedTokens:
         """Extract token counts from data in standardized format.
 
         Args:
@@ -118,7 +118,12 @@ def safe_get_int(value: JSONSerializable | None) -> int:
                 logger.debug(
                     "TokenExtractor: System/user messages have no token usage"
                 )
-                return tokens
+                return {
+                    "input_tokens": 0,
+                    "output_tokens": 0,
+                    "cache_creation_tokens": 0,
+                    "cache_read_tokens": 0,
+                }
             elif entry_type == "assistant":
                 # Assistant messages have token usage - proceed with extraction
                 pass
@@ -247,7 +252,12 @@ def safe_get_int(value: JSONSerializable | None) -> int:
         if tokens["total_tokens"] == 0:
             logger.debug("TokenExtractor: No tokens found in any source")
 
-        return tokens
+        return {
+            "input_tokens": tokens["input_tokens"],
+            "output_tokens": tokens["output_tokens"], 
+            "cache_creation_tokens": tokens["cache_creation_tokens"],
+            "cache_read_tokens": tokens["cache_read_tokens"],
+        }
 
 
 class DataConverter:

src/claude_monitor/core/models.py

@@ -8,6 +8,8 @@
 from datetime import datetime
 from enum import Enum
 
+from claude_monitor.types import FormattedLimitInfo
+
 
 class CostMode(Enum):
     """Cost calculation modes for token usage analysis."""
@@ -86,7 +88,7 @@ class SessionBlock:
     models: list[str] = field(default_factory=list[str])
     sent_messages_count: int = 0
     cost_usd: float = 0.0
-    limit_messages: list[dict[str, str]] = field(default_factory=list[dict[str, str]])
+    limit_messages: list[FormattedLimitInfo] = field(default_factory=list[FormattedLimitInfo])
     projection_data: dict[str, int | float] | None = None
     burn_rate_snapshot: BurnRate | None = None
 

src/claude_monitor/core/p90_calculator.py

@@ -5,7 +5,7 @@
 from statistics import quantiles
 from collections.abc import Callable
 
-from claude_monitor.core.models import BlockData
+from claude_monitor.types import BlockData
 
 
 @dataclass(frozen=True)

src/claude_monitor/data/reader.py

@@ -14,7 +14,7 @@
     TimestampProcessor,
     TokenExtractor,
 )
-from claude_monitor.types import ClaudeJSONEntry, SystemEntry, UserEntry, AssistantEntry, JSONSerializable, EntryData
+from claude_monitor.types import ClaudeJSONEntry, SystemEntry, UserEntry, AssistantEntry, JSONSerializable, EntryData, ExtractedMetadata
 from claude_monitor.core.models import CostMode, UsageEntry
 from claude_monitor.core.pricing import PricingCalculator
 from claude_monitor.error_handling import report_file_error
@@ -393,7 +393,7 @@ def _extract_model(self, data: dict[str, JSONSerializable]) -> str:
             return DataConverter.extract_model_name(parsed_data, default="unknown")
         return "unknown"
 
-    def _extract_metadata(self, data: dict[str, JSONSerializable]) -> dict[str, str]:
+    def _extract_metadata(self, data: dict[str, JSONSerializable]) -> ExtractedMetadata:
         """Extract metadata (for test compatibility)."""
         message = data.get("message", {})
 

src/claude_monitor/types/__init__.py

@@ -42,6 +42,8 @@
     "ModelStatsDict",
     "ProgressBarStyleConfig",
     "ThresholdConfig",
+    "NotificationFlags",
+    "DisplayTimes",
 
     # Config types
     "LastUsedParamsDict",
@@ -67,4 +69,6 @@
     "ProjectionData",
     "LimitInfo",
     "MonitoringData",
+    "ExtractedTokens",
+    "ExtractedMetadata",
 ]

src/claude_monitor/types/common.py

@@ -50,4 +50,20 @@ class ProjectionData(TypedDict):
 
     projected_total_tokens: int
     projected_total_cost: float
-    remaining_minutes: float
+    remaining_minutes: float
+
+
+class ExtractedTokens(TypedDict):
+    """Extracted token counts from Claude message data."""
+
+    input_tokens: int
+    output_tokens: int
+    cache_creation_tokens: int
+    cache_read_tokens: int
+
+
+class ExtractedMetadata(TypedDict):
+    """Extracted metadata from Claude message entries."""
+
+    message_id: str
+    request_id: str

src/claude_monitor/types/display.py

@@ -93,4 +93,20 @@ class ThresholdConfig(TypedDict):
 
     low: float
     medium: float
-    high: float
+    high: float
+
+
+class NotificationFlags(TypedDict):
+    """Notification flags for display controller."""
+
+    show_switch_notification: bool
+    show_exceed_notification: bool
+    show_cost_will_exceed: bool
+
+
+class DisplayTimes(TypedDict):
+    """Formatted display times for UI."""
+
+    predicted_end_str: str
+    reset_time_str: str
+    current_time_str: str

src/claude_monitor/ui/display_controller.py

@@ -12,7 +12,7 @@
 import pytz
 from rich.console import Console, Group, RenderableType
 
-from claude_monitor.types import JSONSerializable, TimeData, CostPredictions, ExtractedSessionData, ProcessedDisplayData, BlockDict, AnalysisResult, BlockData
+from claude_monitor.types import JSONSerializable, TimeData, CostPredictions, ExtractedSessionData, ProcessedDisplayData, BlockDict, AnalysisResult, BlockData, NotificationFlags, DisplayTimes
 from rich.live import Live
 from rich.text import Text
 
@@ -107,7 +107,7 @@ def _check_notifications(
         cost_limit: float,
         predicted_end_time: datetime,
         reset_time: datetime,
-    ) -> dict[str, bool]:
+    ) -> NotificationFlags:
         """Check and update notification states."""
         notifications = {}
 
@@ -150,15 +150,15 @@ def _check_notifications(
                 and self.notification_manager.is_notification_active("cost_will_exceed")
             )
 
-        return notifications
+        return cast(NotificationFlags, notifications)
 
     def _format_display_times(
         self,
         args: argparse.Namespace,
         current_time: datetime,
         predicted_end_time: datetime,
         reset_time: datetime,
-    ) -> dict[str, str]:
+    ) -> DisplayTimes:
         """Format times for display."""
         tz_handler = TimezoneHandler(default_tz="Europe/Warsaw")
         timezone_to_use = (

src/claude_monitor/ui/progress_bars.py

@@ -8,7 +8,7 @@
 from abc import ABC, abstractmethod
 from typing import Final, Protocol, TypedDict
 
-from claude_monitor.core.models import JSONSerializable
+from claude_monitor.types import JSONSerializable
 from claude_monitor.utils.time_utils import percentage
 
 

src/tests/test_display_controller.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from claude_monitor.core.models import JSONSerializable
+from claude_monitor.types import JSONSerializable
 from claude_monitor.ui.display_controller import (
     DisplayController,
     LiveDisplayManager,