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

memybase/__init__.py

@@ -0,0 +1,88 @@
+"""
+@fileoverview Official MemyBase Python SDK — async-first with sync wrapper.
+@module memybase
+@description Public entrypoint. Async: `memybase.MemyBase`. Sync: `memybase.sync.MemyBase`.
+@created 2026-07-04
+"""
+from ._client import MemyBase, SDK_VERSION
+from ._collection import Collection
+from ._errors import (
+    MemyBaseError,
+    ConflictError,
+    ForbiddenError,
+    NetworkError,
+    NotFoundError,
+    QuotaExceededError,
+    QueryTimeoutError,
+    RateLimitedError,
+    ReservedFieldError,
+    SchemaError,
+    ServiceUnavailableError,
+    TimeoutError,
+    UnauthorizedError,
+    ValidationError,
+    decode_error,
+)
+from ._filter import FilterBuilder, OPERATORS, serialize_filter
+from ._graphql import GraphQLClient
+from ._helpers import with_conflict_retry
+from ._mapping import (
+    CUSTOMER_WRITABLE_RESERVED_FIELDS,
+    RESERVED_FIELDS,
+    SCHEMA_RESERVED_FIELDS,
+    guard_reserved_fields,
+    omit_none,
+)
+from ._realtime import RealtimeClient, StreamEvent, SubscribeOptions, Subscription
+from ._self import SelfService
+from ._transport import RetryConfig
+from ._types import (
+    ExpandMeta,
+    ExpandRelationMeta,
+    SchemaActivationJobState,
+    SchemaActivationJobSummary,
+)
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "MemyBase",
+    "Collection",
+    "FilterBuilder",
+    "GraphQLClient",
+    "SelfService",
+    "RealtimeClient",
+    "StreamEvent",
+    "SubscribeOptions",
+    "Subscription",
+    "RetryConfig",
+    "MemyBaseError",
+    "ConflictError",
+    "ForbiddenError",
+    "NetworkError",
+    "NotFoundError",
+    "QuotaExceededError",
+    "QueryTimeoutError",
+    "RateLimitedError",
+    "ReservedFieldError",
+    "SchemaError",
+    "ServiceUnavailableError",
+    "TimeoutError",
+    "UnauthorizedError",
+    "ValidationError",
+    "decode_error",
+    "with_conflict_retry",
+    "guard_reserved_fields",
+    "omit_none",
+    "OPERATORS",
+    "RESERVED_FIELDS",
+    "SCHEMA_RESERVED_FIELDS",
+    "CUSTOMER_WRITABLE_RESERVED_FIELDS",
+    "serialize_filter",
+    "SDK_VERSION",
+    "__version__",
+    "ExpandMeta",
+    "ExpandRelationMeta",
+    "SchemaActivationJobState",
+    "SchemaActivationJobSummary",
+]

memybase/_client.py

@@ -0,0 +1,233 @@
+"""
+@fileoverview Top-level MemyBase async client.
+@module memybase._client
+@description Entry point: MemyBase(base_url, api_key=...) → .collection("slug", project=...) →
+             CRUD. Exposes customer management via .self, and GraphQL via .graphql().
+             Includes key-gated discovery helpers for descriptors and OpenAPI.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+from urllib.parse import quote
+
+from ._collection import Collection
+from ._graphql import GraphQLClient
+from ._self import SelfService
+from ._transport import Transport, RetryConfig
+
+__all__ = ["MemyBase"]
+
+SDK_VERSION = "0.1.0"
+
+
+def _idempotency_headers(idempotency_key: Optional[str] = None) -> Optional[dict[str, str]]:
+    return {"Idempotency-Key": idempotency_key} if idempotency_key is not None else None
+
+
+class MemyBase:
+    """Async MemyBase client.
+
+    Usage::
+
+        async with MemyBase("https://memybase.example.com", api_key="pbk_...") as mb:
+            customers = mb.collection("customers", project="crm", database="analytics")
+            page = await customers.list(page_size=10)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        user_token: Optional[str] = None,
+        cookie: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: float = 30.0,
+        max_retries: Optional[int] = None,
+        retry: Optional[RetryConfig] = None,
+        transport: Optional[Any] = None,
+    ) -> None:
+        self._transport = Transport(
+            base_url,
+            api_key=api_key,
+            token=token,
+            user_token=user_token,
+            cookie=cookie,
+            headers=headers,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry=retry,
+            transport=transport,
+        )
+        self._self = SelfService(self._transport)
+
+    @staticmethod
+    def _data_prefix(project: str, database: Optional[str]) -> str:
+        """The data-plane path prefix for a project/database — multi-db (/p/{p}/d/{db}) or legacy
+        (/projects/{p}). The `_batch`, `admin/schema`, and `openapi.json` routes hang off it."""
+        if database:
+            return f"/api/v1/p/{quote(project, safe='')}/d/{quote(database, safe='')}"
+        return f"/api/v1/projects/{quote(project, safe='')}"
+
+    def collection(
+        self,
+        slug: str,
+        *,
+        project: str,
+        database: Optional[str] = None,
+    ) -> Collection:
+        """Get a handle for a data-plane entity collection."""
+        return Collection(
+            self._transport,
+            slug,
+            project=project,
+            database=database,
+        )
+
+    def graphql(
+        self,
+        *,
+        project: str,
+        database: Optional[str] = None,
+    ) -> GraphQLClient:
+        """Get a GraphQL client for a specific project."""
+        return GraphQLClient(
+            self._transport,
+            project=project,
+            database=database,
+        )
+
+    async def batch(
+        self,
+        project: str,
+        database: Optional[str],
+        operations: list[dict[str, Any]],
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Cross-entity atomic batch write → POST {prefix}/_batch.
+
+        ``operations`` is an ordered list of ``{op, entity, id?, data?, reason?}`` (each op names its own
+        entity), applied all-or-nothing in ONE placement transaction; the first failing op aborts the
+        batch (its error naming the op index). Use ``collection.bulk`` for the single-entity variant.
+        """
+        path = f"{self._data_prefix(project, database)}/_batch"
+        return await self._transport.request(
+            "POST", path, json_body={"operations": operations}, headers=_idempotency_headers(idempotency_key)
+        )
+
+    async def prepare_ai_proposal(
+        self,
+        project: str,
+        database: Optional[str],
+        input: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Prepare a project/database-scoped AI mutation for approval.
+
+        Non-AI credentials return ``{"status": "not_applicable"}``; AI credentials return the durable
+        approval-required proposal envelope and never execute the mutation here.
+        """
+        return await self._transport.request(
+            "POST", f"{self._data_prefix(project, database)}/ai-proposals/prepare", json_body=input
+        )
+
+    async def get_ai_proposal(self, project: str, database: Optional[str], proposal_id: str) -> dict[str, Any]:
+        """Read one proposal scoped by the addressed project and database."""
+        path = f"{self._data_prefix(project, database)}/ai-proposals/{quote(proposal_id, safe='')}"
+        return await self._transport.request("GET", path)
+
+    async def approve_ai_proposal(
+        self,
+        project: str,
+        database: Optional[str],
+        proposal_id: str,
+        *,
+        reason: Optional[str] = None,
+        policy_decision_reason: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Approve and execute once; the server enforces non-AI approval policy."""
+        body = {
+            key: value
+            for key, value in {
+                "reason": reason,
+                "policyDecisionReason": policy_decision_reason,
+            }.items()
+            if value is not None
+        }
+        path = f"{self._data_prefix(project, database)}/ai-proposals/{quote(proposal_id, safe='')}/approve"
+        return await self._transport.request("POST", path, json_body=body)
+
+    async def reject_ai_proposal(
+        self,
+        project: str,
+        database: Optional[str],
+        proposal_id: str,
+        *,
+        reason: Optional[str] = None,
+        policy_decision_reason: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Reject a pending proposal; the server enforces non-AI approval policy."""
+        body = {
+            key: value
+            for key, value in {
+                "reason": reason,
+                "policyDecisionReason": policy_decision_reason,
+            }.items()
+            if value is not None
+        }
+        path = f"{self._data_prefix(project, database)}/ai-proposals/{quote(proposal_id, safe='')}/reject"
+        return await self._transport.request("POST", path, json_body=body)
+
+    async def describe(self, project: str, database: Optional[str] = None) -> dict[str, Any]:
+        """GET {prefix}/admin/schema — the key-gated data-plane app descriptor (entities/fields metadata,
+        structure only). Lets a key-only consumer introspect the database it holds a key for."""
+        return await self._transport.request("GET", f"{self._data_prefix(project, database)}/admin/schema")
+
+    async def describe_entity(self, project: str, database: Optional[str], slug: str) -> dict[str, Any]:
+        """GET {prefix}/admin/entities/{slug} — the key-gated descriptor for one entity."""
+        path = f"{self._data_prefix(project, database)}/admin/entities/{quote(slug, safe='')}"
+        return await self._transport.request("GET", path)
+
+    async def openapi(self, project: str, database: Optional[str] = None) -> dict[str, Any]:
+        """GET {prefix}/openapi.json — the key-gated data-plane OpenAPI 3.1 contract generated from
+        the active compiled schema."""
+        return await self._transport.request("GET", f"{self._data_prefix(project, database)}/openapi.json")
+
+    async def health(self, timeout: Optional[float] = None) -> bool:
+        """Unauthenticated liveness probe → GET /api/health (process-up; no Mongo, schema, or key required).
+        True on a 2xx, False on any non-OK / network error / timeout — a cheap, schema-independent
+        reachability signal for readiness gates, safe to call BEFORE a schema is provisioned."""
+        return await self._transport.health(timeout)
+
+    @property
+    def self_(self) -> SelfService:
+        """Authenticated customer management (/api/self/*)."""
+        return self._self
+
+    # <sync:exclude>  realtime is async-only — see Collection.subscribe / memybase._realtime.
+    # test_sync_parity.py documents this asymmetry and gen_sync.py strips this block from _sync/.
+    async def stream(
+        self,
+        project: str,
+        database: Optional[str],
+        on_event: Callable[[Any], None],
+        opts: Optional["SubscribeOptions"] = None,
+    ) -> "Subscription":
+        """Open a realtime SSE subscription for a project/database (all entities unless opts.entity is
+        set). Returns a live Subscription; ``await subscription.close()`` stops it. Mirrors JS
+        MemyBase.stream()."""
+        from ._realtime import RealtimeClient
+
+        return await RealtimeClient(self._transport).subscribe(project, database, on_event, opts)
+    # </sync:exclude>
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "MemyBase":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()