durable-sync 0.1.0__py3-none-any.whl

durable_sync/connectors/contentful/introspect.py

@@ -0,0 +1,69 @@
+"""List a Contentful space's content types + fields, so you can fill in the
+destination's content_type / field_map (and the smoke's CONTENTFUL_SMOKE_* vars).
+
+Uses whichever token is set: a Management (CMA) token (api.contentful.com) or a
+read-only Delivery (CDA) token (cdn.contentful.com) — both expose the content
+model. Prints each content type's id and its title field (Contentful's
+`displayField`) in copy-paste-ready form, plus every field and type.
+
+    CONTENTFUL_SPACE_ID=... CONTENTFUL_CMA_TOKEN=... \
+        PYTHONPATH=. python -m durable_sync.connectors.contentful.introspect
+
+Requires the `contentful` extra.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import httpx
+
+from durable_sync.env import load_env
+
+CDA_BASE = "https://cdn.contentful.com"
+CMA_BASE = "https://api.contentful.com"
+
+
+def _describe(field: dict) -> str:
+    ftype = field.get("type", "?")
+    if ftype == "Array":
+        items = field.get("items", {})
+        ftype = f"Array<{items.get('linkType') or items.get('type') or '?'}>"
+    elif ftype == "Link":
+        ftype = f"Link<{field.get('linkType', '?')}>"
+    return ftype
+
+
+def main() -> None:
+    load_env()
+    space = os.environ.get("CONTENTFUL_SPACE_ID")
+    env = os.environ.get("CONTENTFUL_ENVIRONMENT", "master")
+    cma = os.environ.get("CONTENTFUL_CMA_TOKEN")
+    cda = os.environ.get("CONTENTFUL_DELIVERY_TOKEN")
+    if not space or not (cma or cda):
+        sys.exit("Set CONTENTFUL_SPACE_ID and CONTENTFUL_CMA_TOKEN (or CONTENTFUL_DELIVERY_TOKEN).")
+
+    base, token = (CMA_BASE, cma) if cma else (CDA_BASE, cda)
+    url = f"{base}/spaces/{space}/environments/{env}/content_types"
+    r = httpx.get(url, headers={"Authorization": f"Bearer {token}"}, params={"limit": 1000}, timeout=30)
+    if r.status_code >= 400:
+        sys.exit(f"Contentful {r.status_code}: {r.text[:400]}")
+
+    items = r.json().get("items", [])
+    print(f"# {len(items)} content type(s) in space {space} (env {env}) via "
+          f"{'CMA' if cma else 'CDA'}\n")
+    for ct in sorted(items, key=lambda c: c.get("sys", {}).get("id", "")):
+        ct_id = ct.get("sys", {}).get("id", "?")
+        display = ct.get("displayField") or "?"   # the field used as the entry title
+        print(f"## {ct.get('name', '?')}")
+        print(f"CONTENTFUL_SMOKE_CONTENT_TYPE={ct_id}")
+        print(f"CONTENTFUL_SMOKE_TITLE_FIELD={display}")
+        for field in ct.get("fields", []):
+            fid = field.get("id", "?")
+            mark = "  <- title" if fid == display else ""
+            print(f"    {fid} : {_describe(field)}{mark}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

durable_sync/connectors/contentful/mcp.py

@@ -0,0 +1,95 @@
+"""Contentful over its hosted MCP server (mcp.contentful.com) — the no-admin / SSO
+path, when a static CMA token is blocked and the MCP-OAuth token doesn't work
+against the REST API.
+
+Contentful's MCP is AGENT-oriented: tools take clean JSON but return LLM-formatted
+pseudo-XML (with prose prefixes, arrays as repeated elements). So:
+  * WRITES are reliable — inputs are clean JSON (fields = {fieldId:{locale:value}},
+    same shape as the REST encoder), and we only scrape two scalars from responses:
+    the new entry's sys.id (create) and sys.version (for the optimistic-lock update).
+  * READS over MCP are fragile (multi-entry XML) — prefer the REST source when you
+    have CMA access; this module is the write path.
+
+Pairs the generic MCP transport (durable_sync.transport.mcp) with the OAuth binding
+(connectors.contentful.oauth). get_initial_context is called once on open (the
+server requires it first).
+"""
+from __future__ import annotations
+
+import re
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+from durable_sync.transport.mcp import TokenProvider, open_session as _open_session
+from durable_sync.connectors.contentful import oauth
+
+
+class ContentfulMcp:
+    """Write-oriented wrapper over an open Contentful-MCP session."""
+
+    def __init__(self, session, space_id: str, environment: str):
+        self._s = session
+        self.space_id = space_id
+        self.environment = environment
+
+    def _base(self) -> dict[str, str]:
+        return {"spaceId": self.space_id, "environmentId": self.environment}
+
+    async def call_raw(self, tool: str, args: dict[str, Any]) -> str:
+        """Escape hatch for discovery/smokes: call a tool, return the raw text."""
+        return await self._s.call(tool, {**self._base(), **args})
+
+    async def create_entry(self, content_type: str, fields: dict[str, Any]) -> str | None:
+        """Create an entry; return its new sys.id (None if it couldn't be scraped)."""
+        raw = await self._s.call(
+            "create_entry", {**self._base(), "contentTypeId": content_type, "fields": fields}
+        )
+        return entry_id(raw)
+
+    async def entry_version(self, entry_id_: str) -> int | None:
+        """sys.version of an entry (required for the optimistic-lock update)."""
+        raw = await self._s.call("get_entry", {**self._base(), "entryId": entry_id_})
+        return entry_version_of(raw)
+
+    async def update_entry(self, entry_id_: str, fields: dict[str, Any], version: int) -> None:
+        await self._s.call(
+            "update_entry",
+            {**self._base(), "entryId": entry_id_, "version": version, "fields": fields},
+        )
+
+    async def publish_entry(self, entry_id_: str) -> None:
+        await self._s.call("publish_entry", {**self._base(), "entryId": [entry_id_]})
+
+
+@asynccontextmanager
+async def open_contentful(
+    space_id: str, environment: str, token_provider: TokenProvider
+) -> AsyncIterator[ContentfulMcp]:
+    """Open a Contentful-MCP session (calls get_initial_context first, as required)."""
+    async with _open_session(oauth.MCP_ENDPOINT, token_provider) as session:
+        cf = ContentfulMcp(session, space_id, environment)
+        await session.call("get_initial_context", {})
+        yield cf
+
+
+# --- response scraping ------------------------------------------------------
+# Contentful's MCP returns prose-prefixed pseudo-XML, and it is NOT reliably
+# parseable: it contains invalid tags (e.g. `<fieldStatus><*>…`) and unescaped
+# content, so an XML parser chokes. We don't need the whole document — only two
+# scalars — so we scrape them with anchored regexes:
+#   * the entry id from the sys URN (…/entries/<id>), which is unambiguous (the
+#     bare <id> elements are dangerous — space/environment/contentType ids appear
+#     first), with a post-</space> fallback for any URN-less response;
+#   * the version from the lone <version> tag (distinct from <publishedVersion>).
+
+def entry_id(raw: str) -> str | None:
+    m = re.search(r"/entries/([A-Za-z0-9_-]+)", raw)          # from the sys URN
+    if m:
+        return m.group(1)
+    m = re.search(r"</space>\s*<id>\s*([A-Za-z0-9_-]+)\s*</id>", raw)  # sys order: space, then id
+    return m.group(1) if m else None
+
+
+def entry_version_of(raw: str) -> int | None:
+    m = re.search(r"<version>\s*(\d+)\s*</version>", raw)     # not <publishedVersion>
+    return int(m.group(1)) if m else None

durable_sync/connectors/contentful/mcp_destination.py

@@ -0,0 +1,137 @@
+"""ContentfulMcpDestination — write entries to Contentful over its MCP server.
+
+The no-admin / SSO-blocked path: where a static CMA token can't reach the space,
+OAuth-as-an-individual through the MCP server can. Create + idempotent update are
+live-verified; `publish` is optional and TOLERANT — the Contentful MCP app
+installation has its own per-tool permission layer (separate from OAuth scopes),
+so `publish_entry` may be disallowed by a space admin. We create/update the entry
+regardless and only skip publishing with a warning when it's gated.
+
+Idempotency uses a LinkStore (primary_key -> entry id), like the REST destination
+and Luma — Contentful field ids don't match neutral property names. Reuses the
+shared `encode_fields` for the wire shape. `token_provider` yields the OAuth access
+token (e.g. a query to the workflow-owned token; the smoke passes one directly).
+
+Requires the `contentful` extra.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import logging
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from durable_sync.core import Record, auth_error_in_chain
+from durable_sync.linkstore import LinkStore
+from durable_sync.transport.mcp import TokenProvider
+from durable_sync.connectors.contentful.encode import encode_fields
+from durable_sync.connectors.contentful.mcp import ContentfulMcp, open_contentful
+from durable_sync.connectors.contentful.token import current_access_token
+
+log = logging.getLogger("durable_sync.connectors.contentful.mcp_destination")
+
+
+class ContentfulMcpDestination:
+    name = "contentful"
+
+    def __init__(
+        self,
+        *,
+        space_id: str,
+        content_type: str,
+        field_map: dict[str, str],
+        link_store: LinkStore,
+        token_provider: TokenProvider | None = None,
+        environment: str = "master",
+        default_locale: str = "en-US",
+        create_only_properties: set[str] | None = None,
+        publish: bool = False,
+    ):
+        self.space_id = space_id
+        self.content_type = content_type
+        self.field_map = field_map
+        self.link_store = link_store
+        self.environment = environment
+        self.default_locale = default_locale
+        self.create_only_properties = create_only_properties or set()
+        self.publish = publish
+        # Default: query the workflow that owns the Contentful OAuth token (started
+        # via connectors.contentful.start), so a worker runs unattended.
+        self._token_provider = token_provider or current_access_token
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.space_id and self.content_type)
+
+    @property
+    def config_hint(self) -> str:
+        return "Contentful space id / content type unset"
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator["_McpSession"]:
+        async with open_contentful(self.space_id, self.environment, self._token_provider) as cf:
+            yield _McpSession(cf, self)
+
+    @staticmethod
+    def is_auth_error(err: BaseException) -> bool:
+        return auth_error_in_chain(err)
+
+    # The worker registers these so the Contentful token-owner workflow runs
+    # alongside the sync (same OAuth-as-a-workflow toolkit as Notion).
+    def aux_workflows(self) -> list:
+        from durable_sync.auth.oauth.workflow import OAuthTokenWorkflow
+        return [OAuthTokenWorkflow]
+
+    def aux_activities(self) -> list:
+        from durable_sync.auth.oauth.refresh import refresh_oauth_token
+        return [refresh_oauth_token]
+
+
+class _McpSession:
+    def __init__(self, cf: ContentfulMcp, dest: ContentfulMcpDestination):
+        self._cf = cf
+        self._d = dest
+
+    async def query_existing_ids(self) -> dict[str, str]:
+        return await self._d.link_store.get_all()
+
+    def _fields(self, record: Record, *, creating: bool):
+        return encode_fields(
+            record, field_map=self._d.field_map, default_locale=self._d.default_locale,
+            create_only_properties=self._d.create_only_properties, creating=creating,
+        )
+
+    async def create(self, record: Record, synced_at: dt.datetime) -> bool:
+        entry_id = await self._cf.create_entry(self.content_type, self._fields(record, creating=True))
+        if not entry_id:
+            raise RuntimeError("Contentful MCP create_entry: could not determine the new entry id")
+        await self._d.link_store.put(record.primary_key, entry_id)
+        await self._maybe_publish(entry_id)
+        return True
+
+    async def update(self, existing_id: str, record: Record, synced_at: dt.datetime) -> bool:
+        version = await self._cf.entry_version(existing_id)
+        if version is None:
+            raise RuntimeError(f"Contentful MCP: could not read version for entry {existing_id}")
+        await self._cf.update_entry(existing_id, self._fields(record, creating=False), version)
+        await self._maybe_publish(existing_id)
+        return True
+
+    @property
+    def content_type(self) -> str:
+        return self._d.content_type
+
+    async def _maybe_publish(self, entry_id: str) -> None:
+        """Publish if asked — but tolerate the MCP app's per-tool permission gate:
+        the entry is already created/updated, so a forbidden publish_entry leaves a
+        draft + a warning rather than failing the whole sync."""
+        if not self._d.publish:
+            return
+        try:
+            await self._cf.publish_entry(entry_id)
+        except RuntimeError as e:
+            if "publish_entry" in str(e) or "permission" in str(e).lower():
+                log.warning("Contentful publish_entry not permitted for %s (MCP app config) — left as draft: %s",
+                            entry_id, e)
+                return
+            raise

durable_sync/connectors/contentful/oauth.py

@@ -0,0 +1,27 @@
+"""Contentful binding of the generic OAuth client (durable_sync.auth.oauth).
+
+Same flow as Notion — OAuth 2.1 + PKCE + dynamic client registration — just
+pinned to Contentful's hosted MCP server. Confirmed via discover(): Contentful
+exposes /authorize, /token, and /register (DCR), so no admin / no pre-registered
+app is needed; you authorize as yourself (through your org's SSO, which is what
+makes a static CFPAT unnecessary here).
+"""
+from __future__ import annotations
+
+from durable_sync.auth.oauth.flow import (  # noqa: F401  (re-exported for callers)
+    build_authorize_url,
+    exchange_code,
+    gen_pkce,
+    new_state,
+    refresh_access_token,
+    register_client,
+)
+from durable_sync.auth.oauth import flow as _generic
+
+MCP_BASE = "https://mcp.contentful.com"
+MCP_ENDPOINT = f"{MCP_BASE}/mcp"  # Streamable HTTP transport
+
+
+def discover() -> dict[str, str]:
+    """Discover Contentful's OAuth endpoints (generic flow, Contentful base URL)."""
+    return _generic.discover(MCP_BASE)

durable_sync/connectors/contentful/prove.py

@@ -0,0 +1,51 @@
+"""Headless proof + tool discovery for Contentful's MCP server. NO browser.
+
+Loads the saved refresh token, mints a fresh access token, opens the MCP session,
+and lists the tools Contentful exposes — which is exactly what we need to build the
+MCP source/destination (their tool names + schemas, instead of guessing).
+
+    PYTHONPATH=. python -m durable_sync.connectors.contentful.prove
+
+If this lists tools, the no-admin OAuth path works headlessly — the Temporal auth
+workflow can mint tokens unattended, same as Notion.
+"""
+from __future__ import annotations
+
+import asyncio
+
+from durable_sync.connectors.contentful import oauth, store
+from durable_sync.transport.mcp import open_session
+
+
+async def _list_tools(access_token: str) -> list[str]:
+    async def token_provider() -> str:
+        return access_token
+    async with open_session(oauth.MCP_ENDPOINT, token_provider) as session:
+        return await session.tool_names()
+
+
+def main() -> None:
+    creds = store.load()
+    if not creds:
+        raise SystemExit(
+            f"No credentials at {store.path()}. Run the bootstrap first:\n"
+            f"  PYTHONPATH=. python -m durable_sync.connectors.contentful.bootstrap"
+        )
+
+    print("Refreshing access token (headless, no browser)...")
+    tokens = oauth.refresh_access_token(creds["token_endpoint"], creds["client_id"], creds["refresh_token"])
+    # Persist a rotated refresh token now (providers rotate on every use).
+    if tokens.get("refresh_token"):
+        creds["refresh_token"] = tokens["refresh_token"]
+        store.save(creds)
+    print(f"  Got access token (expires in {tokens.get('expires_in')}s).\n")
+
+    names = asyncio.run(_list_tools(tokens["access_token"]))
+    print(f"SUCCESS — authenticated headlessly. Contentful MCP exposes {len(names)} tool(s):")
+    for name in names:
+        print(f"  - {name}")
+    print("\nHeadless auth proven — paste this tool list and we'll build the connector against it.")
+
+
+if __name__ == "__main__":
+    main()

durable_sync/connectors/contentful/source.py

@@ -0,0 +1,192 @@
+"""ContentfulSource — entries of chosen content types -> Records, with an
+enrichment hook.
+
+Contentful is usually shared across teams, so a Source here is scoped by CONTENT
+TYPE: `content_types` maps each content-type id you care about to the "Type" label
+it should carry (e.g. {"blogPost": "Blog"}). One entity workflow per content type.
+Whether a *shared* type's entries are kept (e.g. only when an author matches your
+own directory) is app policy — do it in your `enrich`/transform hook, which gets
+the resolved authors via `ContentfulEntryContext`.
+
+Auth: prefer a read-only Delivery (CDA) token; a self-serve Management (CMA) PAT
+is the fallback (and the only mode that sees drafts). Each is read from the env
+var named in `ContentfulConfig`. Requires the `contentful` extra.
+"""
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Union
+
+import httpx
+from temporalio import activity
+
+from durable_sync.core import Record, SourceSpec
+from durable_sync.connectors import content
+from durable_sync.connectors.contentful import api
+from durable_sync.connectors.contentful.api import ContentfulSpace
+
+log = logging.getLogger("durable_sync.connectors.contentful")
+
+EnrichHook = Callable[[Record, "ContentfulEntryContext"], Union[Record, Awaitable[Record]]]
+
+
+@dataclass
+class ContentfulConfig:
+    """Everything Contentful-specific a deployment supplies. `content_types` maps
+    content-type id -> the "Type" label its entries carry (and is the allowlist of
+    what gets fetched). `url_prefixes` maps content-type id -> a public URL prefix
+    the entry slug is appended to."""
+    space_id: str
+    content_types: dict[str, str]                                   # {ct_id: type_label}
+    url_prefixes: dict[str, str] = field(default_factory=dict)      # {ct_id: url_prefix}
+    environment: str = "master"
+    default_locale: str = "en-US"
+    delivery_token_env: str = "CONTENTFUL_DELIVERY_TOKEN"           # CDA, preferred
+    cma_token_env: str = "CONTENTFUL_CMA_TOKEN"                     # CMA PAT, fallback
+    lookback_days: int = 21
+    interval_minutes: int = 360
+    title_property: str = "Name"
+
+
+@dataclass
+class ContentfulEntryContext:
+    """Handed to the enrich hook: the raw (flattened) entry, its resolved authors
+    ({name, email}), the content type, and the live client."""
+    raw_entry: dict
+    authors: list[dict]
+    content_type: str
+    client: httpx.AsyncClient
+
+
+def _heartbeat(detail: str) -> None:
+    if activity.in_activity():
+        activity.heartbeat(detail)
+
+
+class ContentfulSource:
+    name = "contentful"
+
+    def __init__(self, config: ContentfulConfig, *, enrich: EnrichHook | None = None):
+        self._config = config
+        self._enrich = enrich
+
+    def specs(self) -> list[SourceSpec]:
+        # One spec (=> one entity workflow) per content type, so each type syncs +
+        # retries independently.
+        cfg = self._config
+        return [
+            SourceSpec(key=f"type:{ct_id}", interval_minutes=cfg.interval_minutes,
+                       params={"content_type": ct_id, "item_type": label})
+            for ct_id, label in cfg.content_types.items()
+        ]
+
+    def _space(self) -> ContentfulSpace:
+        cfg = self._config
+        return ContentfulSpace(
+            space_id=cfg.space_id,
+            environment=cfg.environment,
+            default_locale=cfg.default_locale,
+            delivery_token=os.environ.get(cfg.delivery_token_env, ""),
+            cma_token=os.environ.get(cfg.cma_token_env, ""),
+        )
+
+    async def fetch_page(
+        self, spec: SourceSpec, only_items: list[str] | None, cursor: str | None
+    ) -> tuple[list[Record], str | None]:
+        """ONE page of entries + next cursor (None on the last page). The cursor
+        carries the frozen window start + the CDA/CMA `skip` offset. A targeted
+        (`only_items`) refresh filters each page to the named ids but still walks
+        the window (Contentful has no cheap by-id batch here), as before."""
+        cfg = self._config
+        content_type = spec.params["content_type"]
+        item_type = spec.params.get("item_type") or cfg.content_types.get(content_type, content_type)
+        space = self._space()
+        targeted = set(only_items or [])
+
+        if cursor is None:
+            after_iso = (datetime.now(timezone.utc) - timedelta(days=cfg.lookback_days)).isoformat()
+            skip = 0
+        else:
+            c = content.unpack_cursor(cursor)
+            after_iso, skip = c["after"], c["skip"]
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            pairs, next_skip = await api.iter_entries_page(
+                client, space, content_type, after_iso, skip=skip)
+            out: list[Record] = []
+            for entry, authors in pairs:
+                source_id = entry.get("sys", {}).get("id", "")
+                if targeted and source_id not in targeted:
+                    continue
+                if not _has_title(entry):
+                    continue  # empty-shell draft, no title yet -> not a real item
+                record = self._to_record(entry, item_type, authors)
+                if self._enrich is not None:
+                    ctx = ContentfulEntryContext(raw_entry=entry, authors=authors,
+                                                 content_type=content_type, client=client)
+                    result = self._enrich(record, ctx)
+                    record = await result if inspect.isawaitable(result) else result
+                out.append(record)
+                _heartbeat(source_id)
+
+        next_cursor = content.pack_cursor(after=after_iso, skip=next_skip) if next_skip is not None else None
+        log.info("Fetched %d Contentful %s entries for %s (skip=%s)", len(out), content_type, spec.key, skip)
+        return out, next_cursor
+
+    async def fetch(self, spec: SourceSpec, only_items: list[str] | None = None) -> list[Record]:
+        """Whole window as one list — drains fetch_page (standalone/non-Temporal)."""
+        records: list[Record] = []
+        cursor: str | None = None
+        while True:
+            page, cursor = await self.fetch_page(spec, only_items, cursor)
+            records.extend(page)
+            if cursor is None:
+                return records
+
+    def _to_record(self, entry: dict, item_type: str, authors: list[dict]) -> Record:
+        """Map one Contentful entry (+ resolved authors) to a neutral Record. Pure."""
+        cfg = self._config
+        sys = entry.get("sys", {})
+        fields = entry.get("fields", {})
+
+        source_id = sys.get("id", "")
+        name = fields.get("title") or fields.get("name") or "(untitled entry)"
+        # Date = explicit publish-date field if present, else createdAt.
+        item_date = fields.get("publishDate") or fields.get("date") or sys.get("createdAt")
+        status = "Published" if entry.get("_published", True) else "Draft"
+
+        slug = fields.get("slug")
+        ct_id = sys.get("contentType", {}).get("sys", {}).get("id", "")
+        prefix = cfg.url_prefixes.get(ct_id) if slug else None
+        url = f"{prefix}{slug}" if prefix else None
+
+        host_names = [a["name"] for a in authors if a.get("name")]
+        # authorOverwriteText (a community author with no `person`) wins for the
+        # human-readable label; resolved names still drive any author matching.
+        author = fields.get("authorOverwriteText") or ", ".join(host_names)
+        tags = [t for t in (fields.get("tags") or []) if isinstance(t, str)]
+
+        return content.content_record(
+            primary_key=source_id,
+            title_property=cfg.title_property,
+            title=str(name),
+            item_type=item_type,
+            source="Contentful",
+            url=url,
+            date=item_date,
+            status=status,
+            author=str(author),
+            authors=host_names,
+            extra={"Tags": tags},
+        )
+
+
+def _has_title(entry: dict[str, Any]) -> bool:
+    """True if the entry has a real title/name (titled drafts count; blank ones
+    don't). Keeps us from writing '(untitled entry)' placeholder rows. Pure."""
+    fields = entry.get("fields", {})
+    return bool(fields.get("title") or fields.get("name"))

durable_sync/connectors/contentful/start.py

@@ -0,0 +1,46 @@
+"""Launch OAuthTokenWorkflow from the saved Contentful bootstrap credentials.
+
+    PYTHONPATH=. python -m durable_sync.connectors.contentful.start
+
+Reads the bootstrap creds, starts the long-running auth workflow that owns the
+rotating refresh token, and serves fresh access tokens via query. After this, a
+worker hosting ContentfulMcpDestination keeps tokens fresh unattended.
+"""
+from __future__ import annotations
+
+import asyncio
+
+from durable_sync import config
+from durable_sync.auth.oauth.workflow import AuthParams, OAuthTokenWorkflow
+from durable_sync.connectors.contentful import store
+from durable_sync.temporal_client import connect
+
+
+async def main() -> None:
+    creds = store.load()
+    if not creds:
+        raise SystemExit(
+            f"No credentials at {store.path()}. Run the bootstrap first:\n"
+            f"  PYTHONPATH=. python -m durable_sync.connectors.contentful.bootstrap"
+        )
+
+    client = await connect()
+    handle = await client.start_workflow(
+        OAuthTokenWorkflow.run,
+        AuthParams(
+            client_id=creds["client_id"],
+            token_endpoint=creds["token_endpoint"],
+            refresh_token=creds["refresh_token"],
+        ),
+        id=config.CONTENTFUL_AUTH_WORKFLOW_ID,
+        task_queue=config.TASK_QUEUE,
+    )
+    print(
+        f"Started OAuthTokenWorkflow (id={handle.id}). It now owns the Contentful "
+        f"refresh token and keeps access tokens fresh.\n"
+        f"Verify:  temporal workflow query --workflow-id {handle.id} --type get_access_token"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

durable_sync/connectors/contentful/store.py

@@ -0,0 +1,25 @@
+"""Contentful binding of the generic creds store (durable_sync.auth.oauth.store).
+
+Pins Contentful's auth file path; bootstrap/prove call load()/save()/path().
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from durable_sync.auth.oauth import store as _store
+
+_FILE = os.getenv("DURABLE_SYNC_CONTENTFUL_AUTH_FILE", ".contentful_auth.json")
+
+
+def load() -> dict[str, Any] | None:
+    return _store.load(_FILE)
+
+
+def save(data: dict[str, Any]) -> None:
+    _store.save(_FILE, data)
+
+
+def path() -> Path:
+    return _store.resolve(_FILE)

durable_sync/connectors/contentful/token.py

@@ -0,0 +1,13 @@
+"""Contentful binding of the generic token accessor (durable_sync.auth.oauth.token).
+
+The default token_provider for ContentfulMcpDestination: query the OAuthTokenWorkflow
+running under config.CONTENTFUL_AUTH_WORKFLOW_ID for a fresh access token.
+"""
+from __future__ import annotations
+
+from durable_sync import config
+from durable_sync.auth.oauth.token import current_access_token as _current
+
+
+async def current_access_token() -> str:
+    return await _current(config.CONTENTFUL_AUTH_WORKFLOW_ID)