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

memybase/_sync/_client.py

@@ -0,0 +1,219 @@
+# GENERATED by scripts/gen_sync.py from memybase/_client.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@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,
+        )
+
+    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 self._transport.request(
+            "POST", path, json_body={"operations": operations}, headers=_idempotency_headers(idempotency_key)
+        )
+
+    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 self._transport.request(
+            "POST", f"{self._data_prefix(project, database)}/ai-proposals/prepare", json_body=input
+        )
+
+    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 self._transport.request("GET", path)
+
+    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 self._transport.request("POST", path, json_body=body)
+
+    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 self._transport.request("POST", path, json_body=body)
+
+    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 self._transport.request("GET", f"{self._data_prefix(project, database)}/admin/schema")
+
+    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 self._transport.request("GET", path)
+
+    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 self._transport.request("GET", f"{self._data_prefix(project, database)}/openapi.json")
+
+    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 self._transport.health(timeout)
+
+    @property
+    def self_(self) -> SelfService:
+        """Authenticated customer management (/api/self/*)."""
+        return self._self
+
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "MemyBase":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

memybase/_sync/_collection.py

@@ -0,0 +1,383 @@
+# GENERATED by scripts/gen_sync.py from memybase/_collection.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@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, Iterator, 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
+
+    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 self._transport.request("GET", self._base, params=params)
+
+    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 self._transport.request("QUERY", self._base, json_body=body)
+
+    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,
+    ) -> Iterator[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 = 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
+
+    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 self._transport.request("GET", path, params=params or None)
+
+    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 self._transport.request(
+            "POST", self._base, json_body=payload, headers=_mutation_headers(idempotency_key=idempotency_key)
+        )
+
+    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 self._transport.request(
+            "PATCH", path, json_body=body, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    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 self._transport.request(
+            "POST", f"{self._base}/_bulk", json_body={"operations": operations},
+            headers=_mutation_headers(idempotency_key=idempotency_key),
+        )
+
+    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}
+        self._transport.request(
+            "DELETE", path, params=params, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    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 self._transport.request(
+            "POST", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    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"
+        self._transport.request(
+            "DELETE", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    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 self._transport.request("GET", path, params=params)
+
+    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 self._transport.request("GET", path)
+
+    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 self._transport.request("GET", path)
+
+    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 self._transport.request(
+            "POST", path, headers=_mutation_headers(expected_version, idempotency_key)
+        )
+
+    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 self._transport.request("GET", path, params=params)
+

memybase/_sync/_graphql.py

@@ -0,0 +1,51 @@
+# GENERATED by scripts/gen_sync.py from memybase/_graphql.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview GraphQL read-only client for per-project generated schemas.
+@module memybase._graphql
+@description Sends GraphQL queries against the per-project /api/v1 graphql endpoint and reads the
+             generated schema.sdl artifact as text. Read-only (no mutations/subscriptions). API keys
+             work. Mirrors the JS SDK's GraphQLClient.
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote
+
+from ._transport import Transport
+
+__all__ = ["GraphQLClient"]
+
+
+class GraphQLClient:
+    """Async GraphQL client for a specific project (optional database)."""
+
+    def __init__(
+        self,
+        transport: Transport,
+        *,
+        project: str,
+        database: Optional[str] = None,
+    ) -> None:
+        self._transport = transport
+        if database:
+            self._path = f"/api/v1/p/{quote(project, safe='')}/d/{quote(database, safe='')}/graphql"
+        else:
+            self._path = f"/api/v1/projects/{quote(project, safe='')}/graphql"
+
+    def query(self, document: str, variables: Optional[dict[str, Any]] = None) -> Any:
+        """Execute a GraphQL query and return the response body ({data, errors?})."""
+        body: dict[str, Any] = {"query": document}
+        if variables:
+            body["variables"] = variables
+        return self._transport.request("POST", self._path, json_body=body)
+
+    def schema_sdl(self) -> str:
+        """GET {graphql_path}/schema.sdl as application/graphql text."""
+        return self._transport.request(
+            "GET",
+            f"{self._path}/schema.sdl",
+            headers={"Accept": "application/graphql"},
+            text=True,
+        )

memybase/_sync/_helpers.py

@@ -0,0 +1,37 @@
+# GENERATED by scripts/gen_sync.py from memybase/_helpers.py — DO NOT EDIT.
+# Regenerate: python sdk/py/scripts/gen_sync.py   (CI gate: gen_sync.py --check).
+"""
+@fileoverview Conflict retry helper for expected-version race conditions.
+@module memybase._helpers
+@description MemyBase writes accept expected_version / If-Match preconditions; this helper retries on
+             ConflictError with linear backoff, mirroring the JS SDK's withConflictRetry().
+@created 2026-07-04
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Awaitable, Callable, TypeVar
+
+from memybase._errors import ConflictError  # absolute: shared module, no _sync twin (see gen_sync.py)
+
+__all__ = ["with_conflict_retry"]
+
+T = TypeVar("T")
+
+
+def with_conflict_retry(
+    fn: Callable[[], T],
+    *,
+    retries: int = 3,
+    delay: float = 0.2,
+) -> T:
+    """Retry fn() on ConflictError up to `retries` times with linear backoff."""
+    last_error: ConflictError | None = None
+    for attempt in range(retries + 1):
+        try:
+            return fn()
+        except ConflictError as e:
+            last_error = e
+            if attempt < retries:
+                time.sleep(delay * (attempt + 1))
+    raise last_error  # type: ignore[misc]