from dataclasses import dataclass
from datetime import datetime

@dataclass
class BackfillResult:
    symbol: str
    """Trading symbol that was backfilled."""
    threshold_decimal_bps: int
    """Threshold used for bar construction."""
    bars_written: int
    """Number of new bars written to ClickHouse."""
    gap_seconds: float
    """Gap in seconds between latest cached bar and now (before backfill)."""
    latest_ts_before: int | None
    """Latest bar timestamp (ms) before backfill, None if no cached bars."""
    latest_ts_after: int | None
    """Latest bar timestamp (ms) after backfill."""
    duration_seconds: float = ...
    """Time taken for the backfill operation."""
    error: str | None = ...
    """Error message if backfill failed, None on success."""

@dataclass
class BackfillStatus:
    status: str
    """Status: 'none', 'pending', 'running', 'completed', 'failed'."""
    request_id: str | None = ...
    requested_at: datetime | None = ...
    started_at: datetime | None = ...
    completed_at: datetime | None = ...
    bars_written: int = ...
    gap_seconds: float = ...
    error: str | None = ...
    elapsed_seconds: float = ...
    watcher_likely_offline: bool = ...

def backfill_gap(
    symbol: str,
    threshold_decimal_bps: int = 250,
    *,
    include_microstructure: bool = True,
    verbose: bool = False,
    overlap_strategy: str = "skip",
) -> BackfillResult: ...
def backfill_all_gaps(
    *,
    include_microstructure: bool = True,
    verbose: bool = False,
) -> list[BackfillResult]: ...
def check_backfill_status(
    symbol: str,
    threshold_decimal_bps: int = 250,
) -> BackfillStatus: ...
