durable-sync 0.1.0__py3-none-any.whl

durable_sync/auth/oauth/workflow.py

@@ -0,0 +1,172 @@
+"""OAuthTokenWorkflow — the entity workflow that owns a rotating OAuth refresh
+token (provider-agnostic).
+
+Why a workflow and not a cron job + a file:
+- It's the SINGLE owner of the rotating refresh token, so refreshes are
+  serialized by construction — the concurrent-refresh `invalid_grant` race that
+  rotating-refresh-token providers warn about can't happen.
+- Its state (the refresh token) is durable across worker restarts.
+- It hands out fresh access tokens via @workflow.query, which is NOT recorded in
+  history — so activities fetch a token without it touching the event log. (Pair
+  with the encryption codec to protect the token in workflow state.)
+
+Start one per provider/account, with the id the destination expects (e.g.
+config.NOTION_AUTH_WORKFLOW_ID). A bootstrap captures the initial refresh token;
+from then on this runs unattended, refreshing ~5 min before expiry.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from temporalio import workflow
+from temporalio.common import RetryPolicy
+from temporalio.exceptions import ApplicationError
+
+with workflow.unsafe.imports_passed_through():
+    from durable_sync.auth.oauth.refresh import RefreshInput, RefreshOutput, refresh_oauth_token
+
+# Refresh this long before the access token's stated expiry.
+_REFRESH_SKEW = timedelta(minutes=5)
+# Continue-as-new after this many refreshes to keep event history small.
+_REFRESHES_BEFORE_CONTINUE = 24
+# Back-off between retries when a refresh fails for a TRANSIENT reason (the token
+# endpoint is down) — so the workflow self-heals instead of giving up.
+_TRANSIENT_BACKOFF = timedelta(seconds=60)
+
+
+def _is_auth_failure(err: BaseException | None) -> bool:
+    """The refresh activity raises a non-retryable ApplicationError(type=AuthError)
+    when the refresh token is dead (mirrors sync_records). Type-only check, so it's
+    pure/deterministic and safe in the workflow."""
+    while err is not None:
+        if isinstance(err, ApplicationError) and err.type == "AuthError":
+            return True
+        err = err.__cause__
+    return False
+
+
+@dataclass
+class AuthParams:
+    client_id: str
+    token_endpoint: str
+    refresh_token: str
+    # Carried across continue-as-new so the count survives history truncation.
+    refreshes_so_far: int = 0
+    # Carried across continue-as-new so the query stays warm at the boundary
+    # (otherwise the new run starts with an empty token until its first refresh,
+    # and any sync querying right then gets an empty token). The codec encrypts it
+    # in history — the reason the codec exists.
+    access_token: str = ""
+
+
+@workflow.defn
+class OAuthTokenWorkflow:
+    @workflow.init
+    def __init__(self, params: AuthParams) -> None:
+        self._access_token = params.access_token
+        self._refresh_token = params.refresh_token
+        self._refreshes = params.refreshes_so_far
+        # Pause/recover state (mirrors SourceSyncWorkflow) — a dead refresh token
+        # parks the workflow instead of crashing it, so it stays queryable and is
+        # resumable via the `reauthorize` signal without re-creating it.
+        self._paused = False
+        self._last_error: str | None = None
+        self._last_refresh: str | None = None
+        self._new_refresh_token = ""  # supplied by reauthorize after a re-bootstrap
+
+    @workflow.run
+    async def run(self, params: AuthParams) -> None:
+        while True:
+            try:
+                out: RefreshOutput = await workflow.execute_activity(
+                    refresh_oauth_token,
+                    RefreshInput(
+                        client_id=params.client_id,
+                        token_endpoint=params.token_endpoint,
+                        refresh_token=self._refresh_token,
+                    ),
+                    start_to_close_timeout=timedelta(seconds=30),
+                    retry_policy=RetryPolicy(maximum_attempts=5),
+                )
+            except Exception as e:  # noqa: BLE001 - classify, never let the workflow die
+                self._last_error = str(e)
+                if _is_auth_failure(e):
+                    # Refresh token revoked/expired/spent — only a human re-auth fixes
+                    # it. Park until `reauthorize` supplies a fresh refresh token.
+                    self._paused = True
+                    workflow.logger.error(
+                        "OAuth refresh permanently rejected for %s — pausing until "
+                        "`reauthorize` with a fresh refresh token.", params.client_id,
+                    )
+                    await workflow.wait_condition(lambda: not self._paused)
+                    if self._new_refresh_token:
+                        self._refresh_token = self._new_refresh_token
+                        self._new_refresh_token = ""
+                else:
+                    # Transient (endpoint down, network) — back off and retry rather
+                    # than terminating the only source of access tokens.
+                    workflow.logger.warning(
+                        "OAuth refresh transient failure for %s; retrying after backoff.",
+                        params.client_id,
+                    )
+                    await workflow.sleep(_TRANSIENT_BACKOFF)
+                continue
+
+            self._access_token = out.access_token
+            self._refresh_token = out.refresh_token  # rotated — keep the newest
+            self._refreshes += 1
+            self._last_refresh = workflow.now().isoformat()
+            self._last_error = None
+
+            sleep_for = timedelta(seconds=out.expires_in) - _REFRESH_SKEW
+            if sleep_for <= timedelta(0):
+                sleep_for = timedelta(seconds=max(out.expires_in // 2, 30))
+            await workflow.sleep(sleep_for)
+
+            # Roll history only AFTER sleeping until the token is near expiry, so
+            # the fresh run's immediate refresh is the one that's actually due —
+            # not a wasted back-to-back rotation. Carries the latest refresh AND
+            # access token so the new run picks up exactly where this one left off
+            # (no empty-token query gap at the boundary).
+            if self._refreshes >= _REFRESHES_BEFORE_CONTINUE:
+                await workflow.wait_condition(workflow.all_handlers_finished)
+                workflow.continue_as_new(
+                    AuthParams(
+                        client_id=params.client_id,
+                        token_endpoint=params.token_endpoint,
+                        refresh_token=self._refresh_token,
+                        refreshes_so_far=0,
+                        access_token=self._access_token,
+                    )
+                )
+
+    # --- Signals (flip flags only; non-async; tolerate stray payloads) -------
+
+    @workflow.signal
+    def reauthorize(self, refresh_token: str = "", *_: object) -> None:
+        """Resume after a pause. Pass a fresh refresh token (from re-running the
+        provider's bootstrap) when the old one was revoked/expired; a bare signal
+        just retries with the current token (e.g. to recover from a long outage)."""
+        if refresh_token:
+            self._new_refresh_token = refresh_token
+        self._paused = False
+
+    # --- Queries (read-only) -------------------------------------------------
+
+    @workflow.query
+    def get_access_token(self) -> str:
+        """Current valid access token. Queries aren't written to history, so
+        callers get the secret without it ever touching the event log."""
+        return self._access_token
+
+    @workflow.query
+    def status(self) -> dict:
+        """Operational state (no secret) — is it healthy, and if not, why."""
+        return {
+            "paused": self._paused,
+            "refreshes": self._refreshes,
+            "last_refresh": self._last_refresh,
+            "last_error": self._last_error,
+            "has_token": bool(self._access_token),
+        }

durable_sync/bootstrap.py

@@ -0,0 +1,44 @@
+"""Start one entity workflow per source unit. Idempotent: re-running won't
+disturb a workflow that's already up (USE_EXISTING), so it doubles as a reconcile.
+
+    from durable_sync.bootstrap import start_sources
+    await start_sources(SOURCE)
+
+No Schedule is needed — each workflow's own timer loop is the periodicity. Drive
+or inspect them by id, e.g.:
+
+    temporal workflow signal --workflow-id "durable-sync:org:temporal-community" \
+        --name sync_now --input '[]'
+    temporal workflow query  --workflow-id "durable-sync:org:temporal-community" \
+        --type status
+"""
+from __future__ import annotations
+
+from temporalio.client import Client
+from temporalio.common import WorkflowIDConflictPolicy
+
+from durable_sync import config
+from durable_sync.core import Source
+from durable_sync.temporal_client import connect
+from durable_sync.workflows.sync import SourceState, SourceSyncWorkflow
+
+
+async def start_sources(
+    source: Source,
+    *,
+    client: Client | None = None,
+    task_queue: str | None = None,
+    id_prefix: str = "durable-sync",
+) -> None:
+    client = client or await connect()
+    tq = task_queue or config.TASK_QUEUE
+    for spec in source.specs():
+        wf_id = f"{id_prefix}:{spec.key}"
+        await client.start_workflow(
+            SourceSyncWorkflow.run,
+            SourceState(spec=spec),
+            id=wf_id,
+            task_queue=tq,
+            id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING,
+        )
+        print(f"ensured entity workflow: {wf_id}")

durable_sync/codec.py

@@ -0,0 +1,80 @@
+"""Encryption codec for Temporal payloads (AES-256-GCM).
+
+When a destination's auth uses a workflow-owned token (e.g. the Notion
+auth workflow), the refresh token lives in that workflow's state and in the
+refresh activity's input/output — all of which Temporal persists in event
+history. This codec encrypts every payload's bytes before they leave the worker,
+so secrets are ciphertext at rest in the cluster and the Web UI.
+
+Opt-in: set DURABLE_SYNC_ENC_KEY to a base64-encoded 32-byte key (generate one
+with `python -m durable_sync.codec`). With no key set, payloads are unencrypted
+(fine for local dev). Wire `encryption_codec()` into your Temporal client's
+data_converter so encode/decode stays consistent across the whole system.
+
+Requires the `crypto` extra:  pip install "durable-sync[crypto]"
+"""
+from __future__ import annotations
+
+import base64
+import os
+from typing import Iterable
+
+from temporalio.api.common.v1 import Payload
+from temporalio.converter import PayloadCodec
+
+_ENCODING = b"binary/encrypted"
+_KEY_ENV = "DURABLE_SYNC_ENC_KEY"
+
+
+def load_key() -> bytes | None:
+    raw = os.getenv(_KEY_ENV, "")
+    if not raw:
+        return None
+    key = base64.b64decode(raw)
+    if len(key) != 32:
+        raise ValueError(f"{_KEY_ENV} must decode to 32 bytes (got {len(key)}).")
+    return key
+
+
+class EncryptionCodec(PayloadCodec):
+    def __init__(self, key: bytes) -> None:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+        self._aesgcm = AESGCM(key)
+
+    async def encode(self, payloads: Iterable[Payload]) -> list[Payload]:
+        return [
+            Payload(
+                metadata={"encoding": _ENCODING},
+                data=self._encrypt(p.SerializeToString()),
+            )
+            for p in payloads
+        ]
+
+    async def decode(self, payloads: Iterable[Payload]) -> list[Payload]:
+        out: list[Payload] = []
+        for p in payloads:
+            if p.metadata.get("encoding") != _ENCODING:
+                out.append(p)  # not ours (e.g. written before encryption was on)
+                continue
+            decrypted = Payload()
+            decrypted.ParseFromString(self._decrypt(p.data))
+            out.append(decrypted)
+        return out
+
+    def _encrypt(self, data: bytes) -> bytes:
+        nonce = os.urandom(12)
+        return nonce + self._aesgcm.encrypt(nonce, data, None)
+
+    def _decrypt(self, data: bytes) -> bytes:
+        return self._aesgcm.decrypt(data[:12], data[12:], None)
+
+
+def encryption_codec() -> EncryptionCodec | None:
+    """The configured codec, or None if DURABLE_SYNC_ENC_KEY is unset (dev mode)."""
+    key = load_key()
+    return EncryptionCodec(key) if key else None
+
+
+if __name__ == "__main__":
+    # Generate a key to put in your env as DURABLE_SYNC_ENC_KEY=...
+    print(base64.b64encode(os.urandom(32)).decode())

durable_sync/config.py

@@ -0,0 +1,35 @@
+"""Runtime + connection config (generic). Side-effect-free: imported indirectly
+into the workflow sandbox, so no IO / no import-time failures.
+
+Integration-specific config (which orgs, which Notion DB, Asana project) lives in
+the Source/Destination you wire up — not here.
+"""
+from __future__ import annotations
+
+import os
+
+TASK_QUEUE = os.environ.get("DURABLE_SYNC_TASK_QUEUE", "durable-sync")
+
+# Worker Versioning — OPT-IN, off by default so local/simple runs need zero setup.
+# Set DURABLE_SYNC_BUILD_ID (e.g. a git SHA) in production: a redeploy whose
+# workflow code changed then only affects NEW/continued executions, while in-flight
+# histories drain on the old build — the safe way to evolve the long-lived entity
+# workflows (SourceSyncWorkflow / OAuthTokenWorkflow) without non-determinism
+# errors. When unset, all workflows run unversioned exactly as before. The
+# alternative for in-place changes is workflow.patched() (see CONTRIBUTING).
+BUILD_ID = os.environ.get("DURABLE_SYNC_BUILD_ID", "")
+DEPLOYMENT_NAME = os.environ.get("DURABLE_SYNC_DEPLOYMENT_NAME", "durable-sync")
+
+# Temporal connection (defaults to a local dev server; set these for Cloud).
+TEMPORAL_ADDRESS = os.environ.get("TEMPORAL_ADDRESS", "localhost:7233")
+TEMPORAL_NAMESPACE = os.environ.get("TEMPORAL_NAMESPACE", "default")
+TEMPORAL_API_KEY = os.environ.get("TEMPORAL_API_KEY")  # set for Temporal Cloud
+
+# Ids of the workflows that own each provider's OAuth token
+# (auth.workflow.OAuthTokenWorkflow, started via connectors.<provider>.start).
+NOTION_AUTH_WORKFLOW_ID = os.environ.get(
+    "DURABLE_SYNC_NOTION_AUTH_WORKFLOW_ID", "durable-sync:notion-auth"
+)
+CONTENTFUL_AUTH_WORKFLOW_ID = os.environ.get(
+    "DURABLE_SYNC_CONTENTFUL_AUTH_WORKFLOW_ID", "durable-sync:contentful-auth"
+)

durable_sync/connectors/__init__.py

@@ -0,0 +1,14 @@
+"""Connectors — one subpackage per external system, each exposing the halves it
+supports: a `source.py` (read: implements `Source`), a `destination.py` (write:
+implements `Destination`), or both, sharing one client + auth.
+
+Grouped by SYSTEM rather than by direction because a system is often both (Notion
+is read in one route and written in another), and its read/write sides share a
+transport (e.g. Notion's MCP client + OAuth). The neutral `Source`/`Destination`
+protocols still live in `durable_sync.core`; this package is only packaging.
+
+Reference systems: github / luma / youtube / contentful (sources today),
+notion / asana (destinations today). `content.py` holds the shared neutral column
+vocabulary for content-style sources; `multi.py` fans several sources onto one
+worker. Import-free on purpose (a connector may contain workflow code).
+"""

durable_sync/connectors/asana/__init__.py

@@ -0,0 +1,13 @@
+"""Asana destination: direct REST + a self-serve Personal Access Token.
+
+The second reference destination, deliberately different from Notion's MCP/OAuth:
+plain REST, a PAT any user can mint (no admin, no workflow). If the Destination
+protocol holds here too, it's neither transport- nor auth-shaped.
+
+Requires the `asana` extra:  pip install "durable-sync[asana]"
+"""
+from __future__ import annotations
+
+from durable_sync.connectors.asana.destination import AsanaDestination
+
+__all__ = ["AsanaDestination"]

durable_sync/connectors/asana/destination.py

@@ -0,0 +1,213 @@
+"""Asana destination — direct REST, self-serve PAT.
+
+Why this exists: it's the abstraction's stress test. Notion let property names BE
+column names; Asana tasks have a FIXED schema (name, notes, due_on, completed) plus
+custom fields addressed by gid — so a neutral Record needs an explicit
+destination-owned `field_map`. That mapping living here (not in the source) is
+exactly the seam working as intended.
+
+Idempotency: the source's primary_key is stored in the task's `external.gid`
+(Asana's purpose-built external-system handle). `query_existing_ids` lists the
+project's tasks with `opt_fields=external` and maps external.gid -> task gid.
+
+Auth: a Personal Access Token (Bearer). Self-serve, no admin, no auth workflow —
+so this destination defines no aux_workflows/aux_activities.
+
+Requires the `asana` extra:  pip install "durable-sync[asana]"
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime as dt
+import os
+from contextlib import asynccontextmanager
+from typing import Any, Awaitable, Callable, AsyncIterator
+
+import httpx
+
+from durable_sync.core import DestinationHTTPError, Record, auth_error_in_chain
+from durable_sync.http import request_with_retry
+
+ASANA_API = "https://app.asana.com/api/1.0"
+_MAX_NOTES = 65000
+_MAX_RETRIES = 6
+_BACKOFF_BASE_SECONDS = 1.0
+
+# Native task fields a field_map value may target directly (everything else must
+# be a custom field). Kept small + explicit on purpose.
+_NATIVE_FIELDS = {"name", "notes", "html_notes", "due_on", "due_at",
+                  "start_on", "completed", "assignee", "resource_subtype"}
+
+TokenProvider = Callable[[], Awaitable[str]]
+# A field_map value: a native field name ("due_on") OR {"custom_field": "<gid>"}.
+FieldTarget = Any
+
+
+class AsanaDestination:
+    name = "asana"
+
+    def __init__(
+        self,
+        project_gid: str,
+        *,
+        title_property: str = "Name",
+        body_field: str = "notes",            # native field record.body maps to
+        field_map: dict[str, FieldTarget] | None = None,
+        create_only_properties: set[str] | None = None,
+        token_provider: TokenProvider | None = None,
+        token_env: str = "ASANA_PAT",
+        synced_custom_field_gid: str | None = None,   # optional date CF to stamp
+        pacing_seconds: float = 0.0,
+    ):
+        self.project_gid = project_gid
+        self.title_property = title_property
+        self.body_field = body_field
+        # record-property -> Asana target. Unmapped properties are DROPPED
+        # (Asana can't hold arbitrary columns); title/body are handled separately.
+        self.field_map = field_map or {}
+        self.create_only_properties = create_only_properties or set()
+        self.token_env = token_env
+        self._token_provider = token_provider or self._env_token
+        self.synced_custom_field_gid = synced_custom_field_gid
+        self.pacing_seconds = pacing_seconds
+
+    async def _env_token(self) -> str:
+        return os.environ.get(self.token_env, "")
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.project_gid)
+
+    @property
+    def config_hint(self) -> str:
+        return f"ASANA project gid / {self.token_env} unset"
+
+    @asynccontextmanager
+    async def connect(self) -> AsyncIterator["_AsanaSession"]:
+        token = await self._token_provider()
+        headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+        async with httpx.AsyncClient(base_url=ASANA_API, headers=headers, timeout=30) as client:
+            yield _AsanaSession(client, self)
+
+    @staticmethod
+    def is_auth_error(err: BaseException) -> bool:
+        """A rejected PAT (401/403). Delegates to the shared matcher so we get the
+        word-boundary code check for free — Asana errors carry gids/request-ids,
+        and a bare `"401" in msg` would false-positive on one. "not authorized" is
+        Asana's own phrasing for a permission failure."""
+        return auth_error_in_chain(err, extra_needles=("not authorized",))
+
+
+class _AsanaSession:
+    def __init__(self, client: httpx.AsyncClient, dest: AsanaDestination):
+        self._client = client
+        self._d = dest
+
+    async def _request(self, method: str, path: str, *, params=None, json=None) -> dict:
+        # Shared backoff (honors Retry-After); we keep the raise here so the error
+        # text carries the status for is_auth_error to classify.
+        r = await request_with_retry(
+            self._client, method, path, params=params, json=json,
+            max_attempts=_MAX_RETRIES, base_delay=_BACKOFF_BASE_SECONDS,
+        )
+        if r.status_code >= 400:
+            raise DestinationHTTPError(
+                r.status_code, f"Asana {method} {path} -> {r.status_code}: {r.text[:600]}"
+            )
+        return r.json() if r.content else {}
+
+    async def query_existing_ids(self) -> dict[str, str]:
+        """{ external.gid (== our primary_key) -> task gid } for the project."""
+        mapping: dict[str, str] = {}
+        params: dict[str, Any] = {
+            "project": self._d.project_gid, "opt_fields": "external", "limit": 100,
+        }
+        while True:
+            resp = await self._request("GET", "/tasks", params=params)
+            for t in resp.get("data", []):
+                ext = t.get("external") or {}
+                gid = ext.get("gid")
+                if gid and t.get("gid"):
+                    mapping[gid] = t["gid"]
+            nxt = resp.get("next_page")
+            if not nxt or not nxt.get("offset"):
+                break
+            params["offset"] = nxt["offset"]
+        return mapping
+
+    async def create(self, record: Record, synced_at: dt.datetime) -> bool:
+        data = _encode_task(self._d, record, synced_at, creating=True)
+        await self._request("POST", "/tasks", json={"data": data})
+        await self._pace()
+        return True
+
+    async def update(self, existing_id: str, record: Record, synced_at: dt.datetime) -> bool:
+        data = _encode_task(self._d, record, synced_at, creating=False)
+        await self._request("PUT", f"/tasks/{existing_id}", json={"data": data})
+        await self._pace()
+        return True
+
+    async def _pace(self) -> None:
+        if self._d.pacing_seconds > 0:
+            await asyncio.sleep(self._d.pacing_seconds)
+
+
+def _encode_task(
+    dest: AsanaDestination, record: Record, synced_at: dt.datetime, *, creating: bool
+) -> dict[str, Any]:
+    """Neutral Record -> Asana task `data`. Pure (no IO) so it's unit-testable.
+
+    title_property -> name; record.body -> body_field; mapped props -> native
+    fields or custom fields; UNMAPPED props are dropped (Asana has no arbitrary
+    columns). On create we also set projects + external (idempotency key)."""
+    props = record.properties
+    data: dict[str, Any] = {}
+    custom: dict[str, Any] = {}
+
+    name = props.get(dest.title_property)
+    if name is not None:
+        data["name"] = str(name)
+    if record.body:
+        data[dest.body_field] = record.body[:_MAX_NOTES]
+
+    for key, val in props.items():
+        if key == dest.title_property or val is None:
+            continue
+        if not creating and key in dest.create_only_properties:
+            continue
+        target = dest.field_map.get(key)
+        if target is None:
+            continue  # unmapped -> dropped (logged at debug by caller if desired)
+        if isinstance(target, dict) and "custom_field" in target:
+            custom[target["custom_field"]] = _coerce(val)
+        elif target in _NATIVE_FIELDS:
+            data[target] = _coerce_native(target, val)
+
+    if dest.synced_custom_field_gid:
+        custom[dest.synced_custom_field_gid] = synced_at.date().isoformat()
+    if custom:
+        data["custom_fields"] = custom
+    if creating:
+        data["projects"] = [dest.project_gid]
+        data["external"] = {"gid": record.primary_key}  # idempotency handle
+    return data
+
+
+def _coerce(val: Any) -> Any:
+    """Custom-field value: numbers pass through; lists join (enum option gids are
+    app-specific, out of scope); everything else stringifies."""
+    if isinstance(val, bool):
+        return str(val)
+    if isinstance(val, (int, float)):
+        return val
+    if isinstance(val, (list, tuple)):
+        return ", ".join(str(v) for v in val)
+    return str(val)
+
+
+def _coerce_native(field: str, val: Any) -> Any:
+    if field == "completed":
+        return bool(val)
+    if field in ("due_on", "start_on"):
+        return str(val)[:10]        # YYYY-MM-DD
+    return str(val)

durable_sync/connectors/content.py

@@ -0,0 +1,80 @@
+"""Shared property vocabulary for content-style sources (events, videos, CMS
+entries, …).
+
+These sources all map an external item onto the SAME neutral columns, so the
+names live here ONCE instead of being hand-typed in each source's `_to_record` —
+where they would silently drift (the same failure mode we hit with `is_auth_error`,
+now fixed by one shared matcher). A destination or transform can import the `P_*`
+constants to address the same columns without re-typing the strings.
+
+Opt-in: `GitHubSource` deliberately does NOT use this — its columns (Stars, Forks,
+License, …) are repo-specific. A source uses `content_record` only when the shared
+content shape genuinely fits; per-source logic (URL building, status rules, author
+resolution) still lives in that source — that's real variation, not duplication.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from durable_sync.core import Record
+
+
+# --- paging cursor (shared by the windowed content sources) -----------------
+# Each content source paginates a rolling time window, so its `fetch_page` cursor
+# carries the window start (`after`, frozen on the first page so all pages query
+# the same window) plus whatever native pagination token the API uses (Luma's
+# next_cursor, YouTube's pageToken + resolved playlist, Contentful's skip). It's a
+# small JSON blob threaded through Temporal as the spine's opaque cursor string.
+
+def pack_cursor(**fields: Any) -> str:
+    return json.dumps(fields)
+
+
+def unpack_cursor(cursor: str) -> dict[str, Any]:
+    return json.loads(cursor)
+
+# Canonical neutral property names every content-style source emits.
+P_TYPE = "Type"
+P_SOURCE = "Source"
+P_SOURCE_ID = "Source ID"
+P_URL = "URL"
+P_DATE = "Date"
+P_STATUS = "Status"
+P_AUTHOR = "Author"
+P_AUTHORS = "Authors"
+
+_MAX_TEXT = 2000
+
+
+def content_record(
+    *,
+    primary_key: str,
+    title_property: str,
+    title: str,
+    item_type: str,
+    source: str,
+    url: str | None = None,
+    date: str | None = None,
+    status: str = "Published",
+    author: str = "",
+    authors: list[str] | None = None,
+    extra: dict[str, Any] | None = None,
+) -> Record:
+    """Build a Record with the shared content columns (+ any source-specific
+    `extra`). `primary_key` is also written as the Source ID column. `title`/
+    `author` are length-capped here so each source doesn't repeat that."""
+    props: dict[str, Any] = {
+        title_property: (title or "")[:_MAX_TEXT],
+        P_TYPE: item_type,
+        P_SOURCE: source,
+        P_SOURCE_ID: primary_key,
+        P_URL: url,
+        P_DATE: date,
+        P_STATUS: status,
+        P_AUTHOR: (author or "")[:_MAX_TEXT],
+        P_AUTHORS: authors or [],
+    }
+    if extra:
+        props.update(extra)
+    return Record(primary_key=primary_key, properties=props)

durable_sync/connectors/contentful/__init__.py

@@ -0,0 +1,25 @@
+"""Contentful connector: entries by content type, BOTH directions.
+
+`ContentfulSource` reads (CDA preferred, CMA fallback — the only mode that sees
+drafts); `ContentfulDestination` writes via the CMA (create/update/publish).
+Source keep/drop policy for shared types belongs in your enrich/transform hook
+(see ContentfulEntryContext). The destination takes a required `LinkStore`
+(primary_key -> entry id) since neutral property names don't match content-model
+field ids — see the boundary doctrine in CONTRIBUTING.
+
+Requires the `contentful` extra:  pip install "durable-sync[contentful]"
+"""
+from __future__ import annotations
+
+from durable_sync.connectors.contentful.destination import ContentfulDestination
+from durable_sync.connectors.contentful.mcp_destination import ContentfulMcpDestination
+from durable_sync.connectors.contentful.source import (
+    ContentfulConfig,
+    ContentfulEntryContext,
+    ContentfulSource,
+)
+
+__all__ = [
+    "ContentfulSource", "ContentfulConfig", "ContentfulEntryContext",
+    "ContentfulDestination", "ContentfulMcpDestination",
+]