Developer Metadata Tagger

from dataclasses import dataclass
from typing import Iterable, Literal, Optional

LocationType = Literal["spreadsheet", "sheet"]

@dataclass
class MetadataEntry:
    key: str
    value: str
    location_type: LocationType
    sheet_title: Optional[str] = None  # required when location_type == "sheet"

@dataclass
class MetadataRecord(MetadataEntry):
    metadata_id: int

def register_metadata(spreadsheet_id: str, entries: Iterable[MetadataEntry]) -> list[MetadataRecord]:
    """Create or replace metadata entries per key/location and return saved records with metadata ids."""

def list_metadata(spreadsheet_id: str, *, key_prefix: Optional[str] = None, location: Optional[str] = None, sheet_title: Optional[str] = None) -> list[MetadataRecord]:
    """Return existing metadata filtered by optional key prefix and location/sheet filters, sorted by key then sheet title."""

def update_metadata(spreadsheet_id: str, key: str, new_value: str, *, location: Optional[str] = None, sheet_title: Optional[str] = None) -> list[MetadataRecord]:
    """Update value for metadata entries matching key and optional location filter; return updated records."""

def remove_metadata(spreadsheet_id: str, key: str, *, location: Optional[str] = None, sheet_title: Optional[str] = None) -> int:
    """Remove metadata entries matching key and filters, returning count removed."""