"""
Abstract storage interface for clawID asset records.

Implement this class to connect any database — SQL, NoSQL, cloud, or custom.
"""

from abc import ABC, abstractmethod


class ClawIDStore(ABC):
    """
    Minimal interface any storage backend must implement.

    Each record maps a clawid UUID → metadata dict.
    The metadata typically contains: uid, platform, ts, asset_id, and
    any other fields the embedding platform chose to include.
    """

    @abstractmethod
    def save(self, clawid: str, metadata: dict) -> None:
        """Insert or replace the record for clawid."""

    @abstractmethod
    def get(self, clawid: str) -> dict | None:
        """Return the metadata for clawid, or None if not found."""

    @abstractmethod
    def delete(self, clawid: str) -> bool:
        """Delete the record. Returns True if it existed."""

    # ── default implementations (override for efficiency) ────────────────────

    def exists(self, clawid: str) -> bool:
        return self.get(clawid) is not None

    def update(self, clawid: str, extra: dict) -> bool:
        """Merge extra fields into an existing record. Returns False if not found."""
        existing = self.get(clawid)
        if existing is None:
            return False
        self.save(clawid, {**existing, **extra})
        return True

    def close(self) -> None:
        """Release resources. Called automatically on context manager exit."""

    def __enter__(self):
        return self

    def __exit__(self, *_):
        self.close()
