memydev-base-sdk 0.1.0__py3-none-any.whl

memybase/_collection.py

@@ -0,0 +1,411 @@
+"""
+@fileoverview Async Collection handle — selector→handle pattern for data-plane operations.
+@module memybase._collection
+@description Implements the data-plane operations (list, create, get, update, softDelete, restore,
+             hardDelete, versions, audit, bulk) plus listAll auto-pagination and the full read surface
+             (fields projection, expand populate, search FTS, after cursor, count opt-out, includeDeleted).
+             Supports both multi-db (/p/{project}/d/{database}/e/{slug}) and legacy
+             (/projects/{project}/entities/{slug}).
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Callable, Optional
+from urllib.parse import quote
+
+# Shared/pure modules use ABSOLUTE imports so the generated memybase/_sync/_collection.py twin resolves
+# the single parent module (there is no _sync/_errors etc.); sibling modules with a twin (_transport)
+# stay RELATIVE so they follow into _sync/. See scripts/gen_sync.py.
+from memybase._errors import ReservedFieldError
+from memybase._filter import FilterBuilder, serialize_filter
+from memybase._mapping import guard_reserved_fields
+from memybase._mapping import omit_none as _omit_none
+from ._transport import Transport
+
+__all__ = ["Collection"]
+
+
+def _mutation_headers(
+    expected_version: Optional[int] = None,
+    idempotency_key: Optional[str] = None,
+) -> Optional[dict[str, str]]:
+    headers: dict[str, str] = {}
+    if expected_version is not None:
+        headers["If-Match"] = str(expected_version)
+    if idempotency_key is not None:
+        headers["Idempotency-Key"] = idempotency_key
+    return headers or None
+
+
+class Collection:
+    """Async handle for one entity collection on a specific project/database."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        slug: str,
+        *,
+        project: str,
+        database: Optional[str] = None,
+    ) -> None:
+        self._transport = transport
+        self._slug = slug
+        self._project = project
+        self._database = database
+
+        if database:
+            self._base = f"/api/v1/p/{quote(project, safe='')}/d/{quote(database, safe='')}/e/{quote(slug, safe='')}"
+        else:
+            self._base = f"/api/v1/projects/{quote(project, safe='')}/entities/{quote(slug, safe='')}"
+
+    def _list_params(
+        self,
+        *,
+        page: Optional[int],
+        page_size: Optional[int],
+        sort: Optional[str],
+        filter: Optional[list[dict[str, Any]] | FilterBuilder],
+        include_deleted: bool,
+        fields: Optional[list[str]],
+        expand: Optional[list[str]],
+        search: Optional[str],
+        after: Optional[str],
+        count: Optional[bool],
+    ) -> dict[str, str]:
+        """Serialize list/read query params exactly as the server's parseListQuery expects (rest/router.ts).
+
+        page/pageSize are emitted ONLY when supplied so a no-arg list() lets the server apply its DEFAULT
+        (25) — matching JS. Advanced options (fields/expand/search/after cursor/count) round-trip the full
+        read surface: projection, relation populate, full-text search, keyset pagination, count opt-out.
+        """
+        params: dict[str, str] = {}
+        if page is not None:
+            params["page"] = str(page)
+        if page_size is not None:
+            params["pageSize"] = str(page_size)
+        if sort:
+            params["sort"] = sort
+        if filter is not None:
+            conditions = filter.build() if isinstance(filter, FilterBuilder) else filter
+            if conditions:
+                params["filter"] = serialize_filter(conditions)
+        if include_deleted:
+            params["includeDeleted"] = "true"
+        if fields:
+            params["fields"] = ",".join(fields)
+        if expand:
+            params["expand"] = ",".join(expand)
+        if search:
+            params["search"] = search
+        if after:
+            params["after"] = after
+        if count is not None:
+            params["count"] = "true" if count else "false"
+        return params
+
+    async def list(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filter: Optional[list[dict[str, Any]] | FilterBuilder] = None,
+        include_deleted: bool = False,
+        fields: Optional[list[str]] = None,
+        expand: Optional[list[str]] = None,
+        search: Optional[str] = None,
+        after: Optional[str] = None,
+        count: Optional[bool] = None,
+    ) -> dict[str, Any]:
+        """Fetch a page → {items, page, pageSize, total?, hasMore, nextCursor?}."""
+        params = self._list_params(
+            page=page, page_size=page_size, sort=sort, filter=filter,
+            include_deleted=include_deleted, fields=fields, expand=expand,
+            search=search, after=after, count=count,
+        )
+        return await self._transport.request("GET", self._base, params=params)
+
+    async def query(
+        self,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        sort: Optional[str] = None,
+        filter: Optional[list[dict[str, Any]] | FilterBuilder] = None,
+        include_deleted: bool = False,
+        fields: Optional[list[str]] = None,
+        expand: Optional[list[str]] = None,
+        search: Optional[str] = None,
+        after: Optional[str] = None,
+        count: Optional[bool] = None,
+    ) -> dict[str, Any]:
+        """RFC 10008 QUERY list request with a JSON body.
+
+        It is safe and idempotent like ``list()``, but keeps rich query content out of the URI.
+        The server applies the identical scope, field-ABAC, query-safety, and pagination contract.
+        """
+        body: dict[str, Any] = {}
+        if page is not None:
+            body["page"] = page
+        if page_size is not None:
+            body["pageSize"] = page_size
+        if sort:
+            body["sort"] = sort
+        if filter is not None:
+            conditions = filter.build() if isinstance(filter, FilterBuilder) else filter
+            if conditions:
+                body["filter"] = conditions
+        if include_deleted:
+            body["includeDeleted"] = True
+        if fields:
+            body["fields"] = fields
+        if expand:
+            body["expand"] = expand
+        if search:
+            body["search"] = search
+        if after:
+            body["after"] = after
+        if count is not None:
+            body["count"] = count
+        return await self._transport.request("QUERY", self._base, json_body=body)
+
+    async def list_all(
+        self,
+        *,
+        page_size: int = 100,
+        sort: Optional[str] = None,
+        filter: Optional[list[dict[str, Any]] | FilterBuilder] = None,
+        include_deleted: bool = False,
+        fields: Optional[list[str]] = None,
+        expand: Optional[list[str]] = None,
+        search: Optional[str] = None,
+        max_pages: int = 1000,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Auto-paginate through all records, yielding each item.
+
+        ``max_pages`` bounds the walk; if it is exhausted while the server still reports ``hasMore=True``
+        a RuntimeError is raised rather than SILENTLY truncating (an ETL/export footgun). Raise the bound
+        (or set it very high) to walk larger collections.
+        """
+        page = 1
+        while True:
+            result = await self.list(
+                page=page, page_size=page_size, sort=sort, filter=filter,
+                include_deleted=include_deleted, fields=fields, expand=expand, search=search,
+            )
+            for item in result.get("items", []):
+                yield item
+            if not result.get("hasMore", False):
+                return
+            if page >= max_pages:
+                raise RuntimeError(
+                    f"list_all exhausted max_pages={max_pages} while the server still reports "
+                    f"hasMore=True — increase max_pages to page deeper (truncation is never silent)."
+                )
+            page += 1
+
+    async def get(
+        self,
+        record_id: str,
+        *,
+        fields: Optional[list[str]] = None,
+        expand: Optional[list[str]] = None,
+    ) -> dict[str, Any]:
+        """GET one record by id. Optional `fields` (projection) + `expand` (relation populate) mirror the
+        server getById query params (rest/router.ts)."""
+        path = f"{self._base}/{quote(record_id, safe='')}"
+        params: dict[str, str] = {}
+        if fields:
+            params["fields"] = ",".join(fields)
+        if expand:
+            params["expand"] = ",".join(expand)
+        return await self._transport.request("GET", path, params=params or None)
+
+    async def create(
+        self,
+        body: dict[str, Any],
+        *,
+        omit_none: bool = True,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """POST a new record (201).
+
+        By default None-valued keys are stripped (``omit_none=True``): the server injects defaults, so a
+        null on create is never a meaningful clear. Pass ``omit_none=False`` to send the body verbatim —
+        for a consumer that stores explicit nulls on create (e.g. a fixed-shape record whose optional
+        fields must round-trip as null rather than be absent).
+        """
+        # Guard the ORIGINAL body BEFORE stripping None so {"version": None} raises ReservedFieldError
+        # instead of being silently omitted to a no-op (rank 24).
+        guard_reserved_fields(body)
+        payload = _omit_none(body) if omit_none else dict(body)
+        return await self._transport.request(
+            "POST", self._base, json_body=payload, headers=_mutation_headers(idempotency_key=idempotency_key)
+        )
+
+    async def update(
+        self,
+        record_id: str,
+        body: dict[str, Any],
+        *,
+        expected_version: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """PATCH a record.
+
+        Sends the body AS-IS (no None-stripping): the server treats a PATCH ``null`` as a first-class
+        sentinel — a non-nullable optional field null → ``$unset`` (clear), a nullable field null →
+        ``$set: null``. Stripping None (as create() does) would make field-clear unreachable and resolve
+        200 while the field silently stays set. ``expected_version`` sends If-Match and stale writes fail
+        with 409. ``idempotency_key`` enables durable safe retry/replay. Reserved keys are still rejected.
+        """
+        guard_reserved_fields(body)
+        path = f"{self._base}/{quote(record_id, safe='')}"
+        return await self._transport.request(
+            "PATCH", path, json_body=body, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    async def bulk(self, operations: list[dict[str, Any]], *, idempotency_key: Optional[str] = None) -> dict[str, Any]:
+        """Atomic per-entity bulk write → POST {base}/_bulk.
+
+        ``operations`` is an ordered list of ``{op, id?, data?, reason?}`` (op ∈ create|update|delete),
+        all targeting THIS collection's entity, applied all-or-nothing in one placement transaction (the
+        first failing op aborts the batch, its error naming the op index). See MemyBase.batch for the
+        cross-entity variant.
+        """
+        return await self._transport.request(
+            "POST", f"{self._base}/_bulk", json_body={"operations": operations},
+            headers=_mutation_headers(idempotency_key=idempotency_key),
+        )
+
+    async def soft_delete(
+        self,
+        record_id: str,
+        *,
+        reason: Optional[str] = None,
+        expected_version: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> None:
+        """DELETE (soft, 204)."""
+        path = f"{self._base}/{quote(record_id, safe='')}"
+        params: Optional[dict[str, str]] = None
+        if reason:
+            params = {"reason": reason}
+        await self._transport.request(
+            "DELETE", path, params=params, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    async def restore(
+        self,
+        record_id: str,
+        *,
+        expected_version: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """POST /{id}/restore — un-delete a soft-deleted record."""
+        path = f"{self._base}/{quote(record_id, safe='')}/restore"
+        return await self._transport.request(
+            "POST", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    async def hard_delete(
+        self,
+        record_id: str,
+        *,
+        expected_version: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> None:
+        """DELETE /{id}/hard — permanent removal (requires elevated key)."""
+        path = f"{self._base}/{quote(record_id, safe='')}/hard"
+        await self._transport.request(
+            "DELETE", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    async def versions(
+        self,
+        record_id: str,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """GET /{id}/versions — immutable version snapshots. page/pageSize sent only when supplied
+        (the server applies its own default cap), mirroring JS."""
+        path = f"{self._base}/{quote(record_id, safe='')}/versions"
+        params: dict[str, str] = {}
+        if page is not None:
+            params["page"] = str(page)
+        if page_size is not None:
+            params["pageSize"] = str(page_size)
+        return await self._transport.request("GET", path, params=params)
+
+    async def version(self, record_id: str, version: int) -> dict[str, Any]:
+        """GET /{id}/versions/{version} — one immutable version snapshot."""
+        path = f"{self._base}/{quote(record_id, safe='')}/versions/{version}"
+        return await self._transport.request("GET", path)
+
+    async def preview_version_restore(self, record_id: str, version: int) -> dict[str, Any]:
+        """GET /{id}/versions/{version}/restore-preview — dry-run a historical-content restore."""
+        path = f"{self._base}/{quote(record_id, safe='')}/versions/{version}/restore-preview"
+        return await self._transport.request("GET", path)
+
+    async def restore_version(
+        self,
+        record_id: str,
+        version: int,
+        *,
+        expected_version: Optional[int] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """POST /{id}/versions/{version}/restore — restore historical content as a new version."""
+        path = f"{self._base}/{quote(record_id, safe='')}/versions/{version}/restore"
+        return await self._transport.request(
+            "POST", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    async def audit(
+        self,
+        record_id: str,
+        *,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """GET /{id}/audit — before/after/diff audit trail. page/pageSize sent only when supplied."""
+        path = f"{self._base}/{quote(record_id, safe='')}/audit"
+        params: dict[str, str] = {}
+        if page is not None:
+            params["page"] = str(page)
+        if page_size is not None:
+            params["pageSize"] = str(page_size)
+        return await self._transport.request("GET", path, params=params)
+
+    # <sync:exclude>  realtime is async-only — the sync SDK does not expose subscribe (SSE is inherently
+    # async); test_sync_parity.py documents this asymmetry and gen_sync.py strips this block from _sync/.
+    async def subscribe(
+        self,
+        on_event: Callable[[Any], None],
+        *,
+        on_resync: Optional[Callable[[str], None]] = None,
+        last_event_id: Optional[str] = None,
+        signal: Optional["asyncio.Event"] = None,
+    ) -> "Subscription":
+        """Subscribe to realtime change events for THIS entity via SSE.
+
+        Returns immediately with a live Subscription (``await subscription.close()`` stops it). The
+        callback fires for ready/change/heartbeat/resync StreamEvents; the ticket is scoped to this
+        collection's slug (opts.entity). See memybase._realtime for event shapes.
+        """
+        from ._realtime import RealtimeClient, SubscribeOptions
+
+        return await RealtimeClient(self._transport).subscribe(
+            self._project,
+            self._database,
+            on_event,
+            SubscribeOptions(
+                entity=self._slug,
+                on_resync=on_resync,
+                last_event_id=last_event_id,
+                signal=signal,
+            ),
+        )
+    # </sync:exclude>

memybase/_errors.py

@@ -0,0 +1,232 @@
+"""
+@fileoverview SDK error hierarchy — typed exceptions decoded from the MemyBase wire format.
+@module memybase._errors
+@description Maps the server's {error:{code,message,details?}} envelope into a typed exception
+             hierarchy. Every error carries code, status, message, and optional details/body.
+             Mirrors the JS SDK's MemyBaseError hierarchy and MemySwarm's errors.py taxonomy.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+__all__ = [
+    "MemyBaseError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "RateLimitedError",
+    "ServiceUnavailableError",
+    "QuotaExceededError",
+    "SchemaError",
+    "QueryTimeoutError",
+    "NetworkError",
+    "TimeoutError",
+    "ReservedFieldError",
+    "decode_error",
+]
+
+
+class MemyBaseError(Exception):
+    """Base for all MemyBase SDK errors."""
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        code: str = "internal",
+        status: int = 0,
+        details: Optional[dict[str, Any]] = None,
+        body: Any = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        self.code = code
+        self.status = status
+        self.details = details
+        self.body = body
+        self.retry_after = retry_after
+        super().__init__(message or f"HTTP {status}")
+
+    @property
+    def retryable(self) -> bool | None:
+        """Wire ``details.retryable`` when the server sent a boolean."""
+        value = (self.details or {}).get("retryable")
+        return value if isinstance(value, bool) else None
+
+
+class ValidationError(MemyBaseError):
+    """422 — field validation failed."""
+
+    @property
+    def issues(self) -> list[dict[str, Any]]:
+        return (self.details or {}).get("issues", [])
+
+    def __init__(self, message: str = "Validation failed", **kw: Any) -> None:
+        kw.setdefault("code", "validation_failed")
+        kw.setdefault("status", 422)
+        super().__init__(message, **kw)
+
+
+class NotFoundError(MemyBaseError):
+    """404 — resource not found."""
+
+    def __init__(self, message: str = "Not found", **kw: Any) -> None:
+        kw.setdefault("code", "not_found")
+        kw.setdefault("status", 404)
+        super().__init__(message, **kw)
+
+
+class ConflictError(MemyBaseError):
+    """409 — conflict (OCC race, duplicate, or relationship violation)."""
+
+    def __init__(self, message: str = "Conflict", **kw: Any) -> None:
+        kw.setdefault("code", "conflict")
+        kw.setdefault("status", 409)
+        super().__init__(message, **kw)
+
+
+class UnauthorizedError(MemyBaseError):
+    """401 — authentication required."""
+
+    def __init__(self, message: str = "Unauthorized", **kw: Any) -> None:
+        kw.setdefault("code", "unauthorized")
+        kw.setdefault("status", 401)
+        super().__init__(message, **kw)
+
+
+class ForbiddenError(MemyBaseError):
+    """403 — forbidden."""
+
+    def __init__(self, message: str = "Forbidden", **kw: Any) -> None:
+        kw.setdefault("code", "forbidden")
+        kw.setdefault("status", 403)
+        super().__init__(message, **kw)
+
+
+class RateLimitedError(MemyBaseError):
+    """429 — rate limited; honor retry_after."""
+
+    def __init__(self, message: str = "Rate limited", *, retry_after: Optional[float] = None, **kw: Any) -> None:
+        kw.setdefault("code", "rate_limited")
+        kw.setdefault("status", 429)
+        kw.setdefault("retry_after", retry_after or 1)
+        super().__init__(message, **kw)
+
+
+class ServiceUnavailableError(MemyBaseError):
+    """503 — service unavailable or placement error; retryable."""
+
+    def __init__(self, message: str = "Service unavailable", *, retry_after: Optional[float] = None, **kw: Any) -> None:
+        kw.setdefault("code", "service_unavailable")
+        kw.setdefault("status", 503)
+        kw.setdefault("retry_after", retry_after or 1)
+        super().__init__(message, **kw)
+
+
+class QuotaExceededError(MemyBaseError):
+    """402 — plan quota exceeded."""
+
+    def __init__(self, message: str = "Quota exceeded", **kw: Any) -> None:
+        kw.setdefault("code", "quota_exceeded")
+        kw.setdefault("status", 402)
+        super().__init__(message, **kw)
+
+
+class SchemaError(MemyBaseError):
+    """400 — schema error or unsafe query."""
+
+    def __init__(self, message: str = "Schema error", **kw: Any) -> None:
+        kw.setdefault("code", "schema_error")
+        kw.setdefault("status", 400)
+        super().__init__(message, **kw)
+
+
+class QueryTimeoutError(MemyBaseError):
+    """408 — query timeout."""
+
+    def __init__(self, message: str = "Query timeout", **kw: Any) -> None:
+        kw.setdefault("code", "query_timeout")
+        kw.setdefault("status", 408)
+        super().__init__(message, **kw)
+
+
+class NetworkError(MemyBaseError):
+    """Network-level failure (DNS, connection refused, etc.)."""
+
+    def __init__(self, message: str = "Network error") -> None:
+        super().__init__(message, code="network_error", status=0)
+
+
+class TimeoutError(MemyBaseError):
+    """Request timed out."""
+
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message, code="timeout", status=0)
+
+
+class ReservedFieldError(ValueError):
+    """Raised when a write body contains engine-reserved keys."""
+
+    def __init__(self, fields: list[str]) -> None:
+        self.fields = sorted(fields)
+        super().__init__(
+            f"Body contains reserved system field(s): {', '.join(self.fields)}. "
+            "Remove them — the server rejects the entire request with 422."
+        )
+
+
+_BY_CODE: dict[str, type[MemyBaseError]] = {
+    "validation_failed": ValidationError,
+    "not_found": NotFoundError,
+    "conflict": ConflictError,
+    "relationship_violation": ConflictError,
+    "unauthorized": UnauthorizedError,
+    "forbidden": ForbiddenError,
+    "tenant_isolation_violation": ForbiddenError,
+    "schema_error": SchemaError,
+    "unsafe_query": SchemaError,
+    "query_timeout": QueryTimeoutError,
+    "quota_exceeded": QuotaExceededError,
+    "not_implemented": MemyBaseError,
+}
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None
+
+
+def decode_error(
+    status: int,
+    body: Any = None,
+    retry_after_header: Optional[str] = None,
+) -> MemyBaseError:
+    """Build the right MemyBaseError for a non-2xx response."""
+    code: Optional[str] = None
+    message: Optional[str] = None
+    details: Optional[dict[str, Any]] = None
+
+    if isinstance(body, dict):
+        err = body.get("error", body)
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message")
+            details = err.get("details")
+
+    eff_code = code or "internal"
+    eff_msg = message or f"HTTP {status}"
+    retry_after = _parse_retry_after(retry_after_header)
+
+    if eff_code == "rate_limited":
+        return RateLimitedError(eff_msg, retry_after=retry_after, details=details, body=body)
+    if eff_code in ("service_unavailable", "placement_error"):
+        return ServiceUnavailableError(eff_msg, retry_after=retry_after, details=details, body=body)
+
+    cls = _BY_CODE.get(eff_code, MemyBaseError)
+    return cls(eff_msg, code=eff_code, status=status, details=details, body=body)