durable-sync 0.1.0__py3-none-any.whl

durable_sync/connectors/contentful/api.py

@@ -0,0 +1,285 @@
+"""Contentful API helpers — pure async HTTP + pure transforms. No Temporal, no
+config globals; everything Contentful-specific (space, tokens, locale) rides on a
+`ContentfulSpace` passed in.
+
+Two access modes, chosen by which token is set, both yielding the SAME flattened
+`(entry, authors)` shape so the normalizer is identical regardless of mode:
+
+- **CDA (preferred):** the read-only Delivery API. Needs just a delivery token, no
+  admin. Returns only *published* entries, flattened to the default locale, with
+  linked author entries resolved inline under `includes.Entry`.
+- **CMA (fallback, and the only way to see in-process drafts):** the Management
+  API + a self-serve PAT. Returns ALL entries (incl. drafts) with per-locale field
+  maps and NO link resolution — so we flatten locales, mark publish state, and
+  resolve authors against a one-time `person` index. The PAT is write-capable;
+  prefer CDA when you can.
+
+Docs:
+https://www.contentful.com/developers/docs/references/content-delivery-api/
+https://www.contentful.com/developers/docs/references/content-management-api/
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from durable_sync.core import DestinationHTTPError
+from durable_sync.http import request_with_retry
+
+CDA_BASE_URL = "https://cdn.contentful.com"
+CMA_BASE_URL = "https://api.contentful.com"
+PAGE_LIMIT = 100
+log = logging.getLogger("durable_sync.connectors.contentful")
+
+# --- Content-model seam -----------------------------------------------------
+# These field names depend on the Contentful content model, so they live in one
+# place. `person` typically exposes `name` but NO email, so author matching falls
+# back to NAME. `authorOverwriteText` (read in source.py) covers community authors
+# that have no `person` entry.
+_AUTHOR_LINK_FIELDS = ("authors", "author", "presenters", "createdBy")
+_AUTHOR_NAME_FIELDS = ("name", "fullName", "displayName")
+_AUTHOR_EMAIL_FIELDS = ("email", "emailAddress")
+
+
+@dataclass(frozen=True)
+class ContentfulSpace:
+    """Connection facts for one space/environment. `delivery_token` selects CDA
+    (preferred); else `cma_token` selects the CMA fallback."""
+    space_id: str
+    environment: str = "master"
+    default_locale: str = "en-US"
+    delivery_token: str = ""
+    cma_token: str = ""
+
+
+def _entries_url(base: str, space: ContentfulSpace) -> str:
+    return f"{base}/spaces/{space.space_id}/environments/{space.environment}/entries"
+
+
+async def iter_entries_page(
+    client: httpx.AsyncClient, space: ContentfulSpace, content_type: str, after_iso: str, *, skip: int = 0
+) -> tuple[list[tuple[dict[str, Any], list[dict[str, Any]]]], int | None]:
+    """ONE page of (entry, authors) for a content type, updated on/after `after_iso`.
+    Returns (pairs, next_skip) where next_skip is the offset for the next page or
+    None when exhausted — the cursor the spine threads through
+    `ContentfulSource.fetch_page`. Routes to the CMA fallback only without a CDA token."""
+    if space.delivery_token:
+        return await _cda_page(client, space, content_type, after_iso, skip)
+    if space.cma_token:
+        return await _cma_page(client, space, content_type, after_iso, skip)
+    raise RuntimeError(
+        "Contentful: set a delivery token (preferred) or a CMA token "
+        "(ContentfulConfig.delivery_token_env / cma_token_env)."
+    )
+
+
+async def iter_entries(
+    client: httpx.AsyncClient, space: ContentfulSpace, content_type: str, after_iso: str
+) -> list[tuple[dict[str, Any], list[dict[str, Any]]]]:
+    """All (entry, authors) for a content type — drains iter_entries_page. For
+    non-Temporal callers; the spine pages directly."""
+    out: list[tuple[dict, list[dict]]] = []
+    skip = 0
+    while True:
+        pairs, next_skip = await iter_entries_page(client, space, content_type, after_iso, skip=skip)
+        out.extend(pairs)
+        if next_skip is None:
+            return out
+        skip = next_skip
+
+
+def _next_skip(skip: int, n_items: int, total: int) -> int | None:
+    """Offset for the next page, or None when this page exhausted the result set."""
+    return skip + n_items if (n_items and skip + n_items < total) else None
+
+
+# --- CDA (Delivery API) -----------------------------------------------------
+
+async def _cda_page(client, space, content_type, after_iso, skip):
+    params: dict[str, Any] = {
+        "content_type": content_type,
+        # Window on UPDATED-at, not created-at: catches entries recently published
+        # (publishing bumps updatedAt, even for old entries) AND recently-edited
+        # drafts. Overlap is idempotent-safe.
+        "sys.updatedAt[gte]": after_iso,
+        "order": "-sys.updatedAt",
+        "limit": PAGE_LIMIT,
+        "skip": skip,
+        "include": 1,  # pull linked author entries into `includes`
+    }
+    data = await _get(client, CDA_BASE_URL, space, space.delivery_token, params)
+    items = data.get("items", [])
+    author_index = _index_includes(data)
+    pairs: list[tuple[dict, list[dict]]] = []
+    for entry in items:
+        entry["_published"] = True  # CDA only ever returns published entries
+        pairs.append((entry, _resolve_authors(entry, author_index)))
+    return pairs, _next_skip(skip, len(items), data.get("total", 0))
+
+
+def _index_includes(data: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """{sys.id: entry} for linked entries returned (already flat) in includes."""
+    includes = data.get("includes", {}).get("Entry", [])
+    return {e.get("sys", {}).get("id"): e for e in includes if e.get("sys", {}).get("id")}
+
+
+# --- CMA (Management API) fallback ------------------------------------------
+
+async def _cma_page(client, space, content_type, after_iso, skip):
+    """Like _cda_page, but the CMA returns drafts + per-locale fields + no link
+    resolution — so flatten locales, mark publish state, and resolve via a person
+    index. NOTE: the person index is (re)loaded per page since activities are
+    stateless; CDA (the preferred path) avoids this. We keep drafts: in-process
+    items are still worth indexing."""
+    person_index = await _load_person_index_cma(client, space)
+    params: dict[str, Any] = {
+        "content_type": content_type,
+        "sys.updatedAt[gte]": after_iso,
+        "order": "-sys.updatedAt",
+        "limit": PAGE_LIMIT,
+        "skip": skip,
+    }
+    data = await _get(client, CMA_BASE_URL, space, space.cma_token, params)
+    items = data.get("items", [])
+    pairs: list[tuple[dict, list[dict]]] = []
+    for raw in items:
+        entry = _flatten_entry(raw, space.default_locale)
+        entry["_published"] = _is_published(raw)
+        pairs.append((entry, _resolve_authors(entry, person_index)))
+    return pairs, _next_skip(skip, len(items), data.get("total", 0))
+
+
+async def _load_person_index_cma(client, space) -> dict[str, dict[str, Any]]:
+    """{person id: {"fields": <flattened>}} for every person (CMA has no includes)."""
+    index: dict[str, dict[str, Any]] = {}
+    skip = 0
+    while True:
+        data = await _get(client, CMA_BASE_URL, space, space.cma_token,
+                          {"content_type": "person", "limit": PAGE_LIMIT, "skip": skip})
+        items = data.get("items", [])
+        for raw in items:
+            pid = raw.get("sys", {}).get("id")
+            if pid:
+                index[pid] = _flatten_entry(raw, space.default_locale)
+        skip += len(items)
+        if not items or skip >= data.get("total", 0):
+            return index
+
+
+def _is_published(raw: dict[str, Any]) -> bool:
+    """A CMA entry is currently published iff it has a publishedVersion. Pure."""
+    return raw.get("sys", {}).get("publishedVersion") is not None
+
+
+def _flatten_entry(raw: dict[str, Any], locale: str) -> dict[str, Any]:
+    """Collapse CMA per-locale field maps ({"en-US": v}) to the default locale,
+    leaving the same flat shape the CDA returns. Pure (no IO)."""
+    fields = {k: _pick_locale(v, locale) for k, v in raw.get("fields", {}).items()}
+    return {"sys": raw.get("sys", {}), "fields": fields}
+
+
+def _pick_locale(value: Any, locale: str) -> Any:
+    """Pick `locale` from a CMA per-locale field map; fall back to the first locale
+    present. Non-dict values pass through. Pure."""
+    if isinstance(value, dict):
+        if locale in value:
+            return value[locale]
+        for v in value.values():  # single non-default locale
+            return v
+        return None
+    return value
+
+
+# --- Shared -----------------------------------------------------------------
+
+async def _get(client, base: str, space: ContentfulSpace, token: str, params: dict[str, Any]) -> dict[str, Any]:
+    r = await request_with_retry(
+        client, "GET", _entries_url(base, space),
+        headers={"Authorization": f"Bearer {token}"}, params=params,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def _resolve_authors(entry: dict[str, Any], author_index: dict[str, dict[str, Any]]) -> list[dict[str, Any]]:
+    """Resolve an entry's author link(s) to [{name, email}, ...]. Pure (dict only).
+
+    Handles a single link or an array of links. Unresolvable links are skipped.
+    `person` has no email, so email is typically "" and matching falls back to
+    name. Expects a FLAT entry (CDA native; CMA via _flatten_entry)."""
+    raw = next((entry.get("fields", {}).get(f) for f in _AUTHOR_LINK_FIELDS
+                if entry.get("fields", {}).get(f)), None)
+    links = raw if isinstance(raw, list) else [raw]
+
+    authors: list[dict[str, Any]] = []
+    for link in links:
+        if not isinstance(link, dict):
+            continue
+        person = author_index.get(link.get("sys", {}).get("id"), {})
+        pf = person.get("fields", {})
+        name = next((pf[f] for f in _AUTHOR_NAME_FIELDS if pf.get(f)), "")
+        email = next((pf[f] for f in _AUTHOR_EMAIL_FIELDS if pf.get(f)), "")
+        if name or email:
+            authors.append({"name": name, "email": email})
+    return authors
+
+
+# --- write side: CMA only (the Delivery API is read-only) -------------------
+# Verify against the CMA docs — writes are versioned (optimistic locking) and
+# locale-wrapped: https://www.contentful.com/developers/docs/references/content-management-api/
+
+def cma_entries_url(space: ContentfulSpace) -> str:
+    return f"{CMA_BASE_URL}/spaces/{space.space_id}/environments/{space.environment}/entries"
+
+
+async def _cma(client: httpx.AsyncClient, method: str, url: str, *, headers=None, json=None) -> dict[str, Any]:
+    """A CMA call; raise with status text so is_auth_error classifies a 401.
+    The client carries the Bearer + content-type headers (set in connect)."""
+    r = await request_with_retry(client, method, url, headers=headers, json=json)
+    if r.status_code >= 400:
+        raise DestinationHTTPError(
+            r.status_code, f"Contentful {method} {url.rsplit('/', 1)[-1]} -> {r.status_code}: {r.text[:600]}"
+        )
+    return r.json() if r.content else {}
+
+
+async def entry_version_or_none(
+    client: httpx.AsyncClient, space: ContentfulSpace, entry_id: str
+) -> int | None:
+    """Current sys.version of an entry, or None if it doesn't exist (404). Lets the
+    idempotent upsert decide create-vs-update at a client-chosen id."""
+    r = await request_with_retry(client, "GET", f"{cma_entries_url(space)}/{entry_id}")
+    if r.status_code == 404:
+        return None
+    if r.status_code >= 400:
+        raise DestinationHTTPError(
+            r.status_code, f"Contentful GET {entry_id} -> {r.status_code}: {r.text[:600]}"
+        )
+    return r.json().get("sys", {}).get("version", 0)
+
+
+async def upsert_entry(
+    client: httpx.AsyncClient, space: ContentfulSpace, entry_id: str,
+    content_type: str, fields: dict[str, Any], *, version: int | None,
+) -> int:
+    """Idempotent create-or-update at a CLIENT-CHOSEN id via PUT /entries/{id}.
+    `version is None` -> create (sends the content-type header); an int -> update
+    with the optimistic-lock header. Returns the new sys.version. Because the id is
+    deterministic (see encode.deterministic_entry_id), a retried create can't
+    duplicate — it updates the entry the first attempt already made."""
+    headers = (
+        {"X-Contentful-Content-Type": content_type} if version is None
+        else {"X-Contentful-Version": str(version)}
+    )
+    data = await _cma(client, "PUT", f"{cma_entries_url(space)}/{entry_id}",
+                      headers=headers, json={"fields": fields})
+    return data.get("sys", {}).get("version", (version or 0) + 1)
+
+
+async def publish_entry(client: httpx.AsyncClient, space: ContentfulSpace, entry_id: str, *, version: int) -> None:
+    """Publish an entry at `version` (else it stays a draft, CMA-only-visible)."""
+    await _cma(client, "PUT", f"{cma_entries_url(space)}/{entry_id}/published",
+               headers={"X-Contentful-Version": str(version)})

durable_sync/connectors/contentful/bootstrap.py

@@ -0,0 +1,102 @@
+"""One-time interactive OAuth bootstrap for Contentful's MCP server. Run once, as
+yourself, in a browser:
+
+    PYTHONPATH=. python -m durable_sync.connectors.contentful.bootstrap
+
+No CMA token, no org admin, no SSO workaround: this self-registers an OAuth client
+(RFC 7591) and authorizes as *you* through your org's SSO — so it gets the access
+a static personal token can't. Saves the refresh token + client_id locally (see
+store.py) so the headless path (prove.py, then OAuthTokenWorkflow) can mint access
+tokens unattended.
+
+(Near-identical to the Notion bootstrap — once we wire a second provider for real,
+this OAuth-CLI flow is worth generalizing into auth/oauth/.)
+"""
+from __future__ import annotations
+
+import http.server
+import threading
+import urllib.parse
+import webbrowser
+
+from durable_sync.connectors.contentful import oauth, store
+
+_PORT = 8788
+REDIRECT_URI = f"http://localhost:{_PORT}/callback"
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    result: dict[str, str] = {}
+
+    def do_GET(self) -> None:  # noqa: N802 (stdlib naming)
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = urllib.parse.parse_qs(parsed.query)
+        _CallbackHandler.result = {k: v[0] for k, v in params.items()}
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        self.wfile.write(
+            b"<html><body><h2>durable-sync: Contentful authorized.</h2>"
+            b"You can close this tab and return to the terminal.</body></html>"
+        )
+
+    def log_message(self, *args: object) -> None:  # silence default logging
+        pass
+
+
+def _wait_for_callback() -> dict[str, str]:
+    server = http.server.HTTPServer(("localhost", _PORT), _CallbackHandler)
+    thread = threading.Thread(target=server.handle_request)  # one request, then stop
+    thread.start()
+    thread.join()
+    server.server_close()
+    return _CallbackHandler.result
+
+
+def main() -> None:
+    print("Discovering Contentful MCP OAuth endpoints...")
+    endpoints = oauth.discover()
+
+    print("Registering an OAuth client (dynamic, no admin needed)...")
+    client = oauth.register_client(endpoints["registration_endpoint"], REDIRECT_URI)
+    client_id = client["client_id"]
+
+    verifier, challenge = oauth.gen_pkce()
+    state = oauth.new_state()
+    url = oauth.build_authorize_url(
+        endpoints["authorization_endpoint"], client_id, REDIRECT_URI, challenge, state
+    )
+
+    print(f"\nOpening your browser to authorize as yourself (via SSO):\n  {url}\n")
+    webbrowser.open(url)
+    print(f"Waiting for the redirect to {REDIRECT_URI} ...")
+    cb = _wait_for_callback()
+
+    if cb.get("state") != state:
+        raise SystemExit("State mismatch — aborting (possible CSRF).")
+    if "code" not in cb:
+        raise SystemExit(f"No authorization code in callback: {cb}")
+
+    print("Exchanging authorization code for tokens...")
+    tokens = oauth.exchange_code(
+        endpoints["token_endpoint"], client_id, cb["code"], REDIRECT_URI, verifier
+    )
+
+    store.save({
+        "client_id": client_id,
+        "token_endpoint": endpoints["token_endpoint"],
+        "refresh_token": tokens["refresh_token"],
+    })
+    print(
+        f"\nSaved credentials to {store.path()}.\n"
+        f"Next: list the Contentful MCP tools (and prove headless minting) with\n"
+        f"  PYTHONPATH=. python -m durable_sync.connectors.contentful.prove"
+    )
+
+
+if __name__ == "__main__":
+    main()

durable_sync/connectors/contentful/describe.py

@@ -0,0 +1,61 @@
+"""Dump Contentful MCP usage + the input schemas of the tools we'll build against,
+so the connector is written to the real shapes (not guessed).
+
+    PYTHONPATH=. python -m durable_sync.connectors.contentful.describe
+
+Prints get_initial_context (most MCP servers expect it first — it documents usage
+and your space/environment) and the inputSchema of the read/write/schema tools.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+
+from durable_sync.connectors.contentful import oauth, store
+from durable_sync.transport.mcp import open_session
+
+# The tools the source/destination/schema layers will use.
+_KEY_TOOLS = [
+    "search_entries", "get_entry", "resolve_entry_references",
+    "create_entry", "update_entry", "publish_entry",
+    "list_content_types", "get_content_type",
+]
+
+
+async def _describe(access_token: str) -> None:
+    async def token_provider() -> str:
+        return access_token
+    async with open_session(oauth.MCP_ENDPOINT, token_provider) as session:
+        print("=== get_initial_context ===")
+        try:
+            print(await session.call("get_initial_context", {}))
+        except Exception as e:  # noqa: BLE001 — discovery, surface whatever it says
+            print(f"(error calling get_initial_context: {e})")
+        print()
+
+        by_name = {t.name: t for t in await session.tools()}
+        for name in _KEY_TOOLS:
+            tool = by_name.get(name)
+            if tool is None:
+                print(f"=== {name}: NOT FOUND ===\n")
+                continue
+            print(f"=== {name} ===")
+            if tool.description:
+                print(tool.description.strip()[:400])
+            print(json.dumps(tool.inputSchema, indent=2))
+            print()
+
+
+def main() -> None:
+    creds = store.load()
+    if not creds:
+        raise SystemExit("No credentials — run connectors.contentful.bootstrap first.")
+    tokens = oauth.refresh_access_token(creds["token_endpoint"], creds["client_id"], creds["refresh_token"])
+    if tokens.get("refresh_token"):
+        creds["refresh_token"] = tokens["refresh_token"]
+        store.save(creds)
+    asyncio.run(_describe(tokens["access_token"]))
+
+
+if __name__ == "__main__":
+    main()

durable_sync/connectors/contentful/destination.py

@@ -0,0 +1,145 @@
+"""ContentfulDestination — create/update Contentful entries from neutral Records.
+
+The write half of the Contentful connector (e.g. cross-posting from Notion).
+Writes go through the **CMA** (the Delivery API is read-only), which means:
+  * a CMA token (write-capable),
+  * locale-wrapped field values ({field: {locale: value}}),
+  * versioned updates (fetch sys.version, send it as the optimistic-lock header),
+  * an explicit publish step (else entries stay drafts).
+
+Idempotency: the entry id is a DETERMINISTIC function of the source primary_key
+(`deterministic_entry_id`), and creates go through `PUT /entries/{id}` (Contentful
+lets you choose the id). So a create that's retried after a crash re-derives the
+same id and UPDATES that entry rather than duplicating it — at-least-once safe
+without trusting the LinkStore to have been written. The injected `LinkStore` is
+still used for query_existing_ids (to route known rows straight to update), but it
+is now just an optimization: even an empty/lost store can't cause duplicates.
+
+NOTE: the CMA shape here follows the docs but has not been run against a live
+space — verify field-locale wrapping, the PUT-with-id create, versioning, and
+publish before relying on it. The pure encoding + id derivation are unit-tested;
+the HTTP request sequence is unit-tested against a fake client but not live.
+
+Requires the `contentful` extra.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import os
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+import httpx
+
+from durable_sync.core import Record, auth_error_in_chain
+from durable_sync.linkstore import LinkStore
+from durable_sync.connectors.contentful import api
+from durable_sync.connectors.contentful.api import ContentfulSpace
+from durable_sync.connectors.contentful.encode import deterministic_entry_id, encode_fields
+
+_CMA_CONTENT_TYPE = "application/vnd.contentful.management.v1+json"
+
+
+class ContentfulDestination:
+    name = "contentful"
+
+    def __init__(
+        self,
+        *,
+        space_id: str,
+        content_type: str,                       # the content-type id to create entries as
+        field_map: dict[str, str],               # neutral property name -> CMA field id
+        link_store: LinkStore,                   # REQUIRED — correspondence lives outside Contentful
+        cma_token_env: str = "CONTENTFUL_CMA_TOKEN",
+        environment: str = "master",
+        default_locale: str = "en-US",
+        create_only_properties: set[str] | None = None,
+        publish: bool = False,                   # publish on write, or leave as draft
+        pacing_seconds: float = 0.0,
+    ):
+        self.space_id = space_id
+        self.content_type = content_type
+        self.field_map = field_map
+        self.link_store = link_store
+        self.cma_token_env = cma_token_env
+        self.environment = environment
+        self.default_locale = default_locale
+        self.create_only_properties = create_only_properties or set()
+        self.publish = publish
+        self.pacing_seconds = pacing_seconds
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.space_id and os.environ.get(self.cma_token_env))
+
+    @property
+    def config_hint(self) -> str:
+        return f"Contentful space id / {self.cma_token_env} unset"
+
+    def _space(self) -> ContentfulSpace:
+        return ContentfulSpace(
+            space_id=self.space_id, environment=self.environment,
+            default_locale=self.default_locale,
+            cma_token=os.environ.get(self.cma_token_env, ""),
+        )
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator["_ContentfulSession"]:
+        headers = {
+            "Authorization": f"Bearer {os.environ.get(self.cma_token_env, '')}",
+            "Content-Type": _CMA_CONTENT_TYPE,
+        }
+        async with httpx.AsyncClient(headers=headers, timeout=30) as client:
+            yield _ContentfulSession(client, self)
+
+    @staticmethod
+    def is_auth_error(err: BaseException) -> bool:
+        return auth_error_in_chain(err)
+
+
+class _ContentfulSession:
+    def __init__(self, client: httpx.AsyncClient, dest: ContentfulDestination):
+        self._client = client
+        self._d = dest
+        self._space = dest._space()
+
+    async def query_existing_ids(self) -> dict[str, str]:
+        return await self._d.link_store.get_all()
+
+    async def create(self, record: Record, synced_at: dt.datetime) -> bool:
+        # Idempotent: the entry id is a pure function of primary_key, so a retried
+        # create (after a crash) re-derives the SAME id and updates the entry the
+        # first attempt made instead of duplicating it. We still record the link so
+        # query_existing_ids routes future syncs straight to update().
+        entry_id = deterministic_entry_id(record.primary_key)
+        await self._upsert(entry_id, record, creating=True)
+        await self._d.link_store.put(record.primary_key, entry_id)
+        await self._pace()
+        return True
+
+    async def update(self, existing_id: str, record: Record, synced_at: dt.datetime) -> bool:
+        await self._upsert(existing_id, record, creating=False)
+        await self._pace()
+        return True
+
+    async def _upsert(self, entry_id: str, record: Record, *, creating: bool) -> None:
+        fields = _encode_fields(self._d, record, creating=creating)
+        version = await api.entry_version_or_none(self._client, self._space, entry_id)
+        new_version = await api.upsert_entry(
+            self._client, self._space, entry_id, self._d.content_type, fields, version=version
+        )
+        if self._d.publish:
+            await api.publish_entry(self._client, self._space, entry_id, version=new_version)
+
+    async def _pace(self) -> None:
+        if self._d.pacing_seconds > 0:
+            await asyncio.sleep(self._d.pacing_seconds)
+
+
+def _encode_fields(dest: ContentfulDestination, record: Record, *, creating: bool = True) -> dict[str, Any]:
+    """Neutral Record -> CMA `fields`. Thin wrapper over the shared encoder."""
+    return encode_fields(
+        record, field_map=dest.field_map, default_locale=dest.default_locale,
+        create_only_properties=dest.create_only_properties, creating=creating,
+    )

durable_sync/connectors/contentful/encode.py

@@ -0,0 +1,49 @@
+"""Neutral Record -> Contentful CMA `fields` ({field id: {locale: value}}).
+
+Shared by both the REST destination and the MCP destination — the wire shape is
+identical (the MCP create_entry/update_entry tools take the same locale-wrapped
+fields object), so the encoding lives here once. Pure (no IO).
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from durable_sync.core import Record
+
+
+def deterministic_entry_id(primary_key: str) -> str:
+    """A stable Contentful entry id derived purely from the source primary_key.
+
+    Contentful lets you CREATE at a client-chosen id (PUT /entries/{id}), and entry
+    ids are [A-Za-z0-9_-]{1,64}. A sha256 hex digest (64 chars, charset-safe) fits
+    exactly and is collision-free in practice — so the same Record always maps to
+    the same entry, which makes create idempotent: a retry after a crashed create
+    re-derives the SAME id and updates that entry instead of making a duplicate
+    (and an empty/lost LinkStore can no longer cause duplicates either)."""
+    return hashlib.sha256(primary_key.encode("utf-8")).hexdigest()  # 64 hex chars
+
+
+def encode_fields(
+    record: Record,
+    *,
+    field_map: dict[str, str],
+    default_locale: str,
+    create_only_properties: frozenset[str] | set[str] = frozenset(),
+    creating: bool = True,
+) -> dict[str, Any]:
+    """Map each property through `field_map` (neutral name -> CMA field id),
+    locale-wrapping the value. Unmapped properties and Nones are dropped (Contentful
+    has a fixed content model); on update, create-only properties are skipped so
+    human edits in Contentful survive."""
+    out: dict[str, Any] = {}
+    for prop, value in record.properties.items():
+        if value is None:
+            continue
+        if not creating and prop in create_only_properties:
+            continue
+        field_id = field_map.get(prop)
+        if not field_id:
+            continue
+        out[field_id] = {default_locale: value}
+    return out