Cloud Storage Types

@dataclass(frozen=True)
class CloudStorageConnection:
    id: str                                          # Unique connection identifier
    provider: str                                    # Provider type (e.g. "google_drive")
    is_active: bool                                  # Whether the connection is active
    provider_email: Optional[str] = None             # Email associated with provider account
    provider_display_name: Optional[str] = None      # Display name from provider
    created_at: Optional[datetime] = None            # When the connection was created
    last_used_at: Optional[datetime] = None          # When last used

@dataclass(frozen=True)
class InitiateAuthResult:
    authorization_url: str      # URL to redirect user to for authorization
    state: str                  # State parameter for CSRF verification
    provider: str               # Provider type

@dataclass(frozen=True)
class CompleteAuthResult:
    connection: CloudStorageConnection    # The created or updated connection
    is_new: bool                          # Whether this is a new connection (vs reconnection)

@dataclass(frozen=True)
class ConnectionList:
    connections: list[CloudStorageConnection]    # List of connections
    total_count: int                             # Total number of connections

@dataclass(frozen=True)
class DisconnectResult:
    success: bool     # Whether the disconnection succeeded
    message: str      # Confirmation message

@dataclass(frozen=True)
class CloudFileInput:
    id: str                                  # Cloud provider file ID
    name: str                                # File name
    mime_type: Optional[str] = None          # MIME type of the file
    size_bytes: Optional[int] = None         # File size in bytes

    def to_dict(self) -> dict[str, Any]: ...   # Convert to API request dict

@dataclass(frozen=True)
class ImportResult:
    total_files: int                             # Number of files in the import
    is_async: bool                               # Whether import runs asynchronously
    message: str                                 # Status message
    image_ids: Optional[list[str]] = None        # Image IDs (for synchronous imports)
    job_id: Optional[str] = None                 # Job ID (for async imports)
    status: Optional[str] = None                 # Job status (for async imports)

@dataclass(frozen=True)
class ExportResult:
    is_async: bool                                   # Whether export runs asynchronously
    message: str                                     # Status message
    cloud_file_ids: Optional[list[str]] = None       # Cloud file IDs (for sync exports)
    job_id: Optional[str] = None                     # Job ID (for async exports)
    job_status: Optional[str] = None                 # Job status (for async exports)

@dataclass(frozen=True)
class CloudStorageJob:
    job_id: str                                 # Unique job identifier
    type: str                                   # "import" or "export"
    status: str                                 # pending | in_progress | completed | partial | failed | cancelled
    connection_id: str                          # Associated connection ID
    provider: str                               # Cloud storage provider
    total_files: int                            # Total number of files in the job
    completed_files: int                        # Number of files completed
    failed_files: int                           # Number of files that failed
    error: Optional[str] = None                 # Error message if job failed
    created_at: Optional[datetime] = None       # When the job was created
    updated_at: Optional[datetime] = None       # When the job was last updated
    completed_at: Optional[datetime] = None     # When the job completed

    # Properties
    @property
    def is_terminal(self) -> bool: ...          # completed, partial, failed, or cancelled
    @property
    def is_successful(self) -> bool: ...        # completed or partial
    @property
    def progress_percent(self) -> float: ...    # 0-100 based on (completed + failed) / total