durable-sync 0.1.0__py3-none-any.whl

durable_sync/connectors/contentful/token_check.py

@@ -0,0 +1,42 @@
+"""Does the MCP-minted OAuth token also work against the plain CMA REST API?
+
+The Contentful MCP returns LLM-oriented XML, awkward to parse for a sync pipeline.
+But if the OAuth token we mint for the MCP server ALSO authenticates the CMA REST
+API, we can skip the XML entirely: reuse the existing (clean-JSON) REST
+ContentfulSource/Destination with a durable, workflow-owned OAuth token — no-admin
+auth AND clean JSON. This probe answers that decisively.
+
+    PYTHONPATH=. python -m durable_sync.connectors.contentful.token_check
+"""
+from __future__ import annotations
+
+import httpx
+
+from durable_sync.env import load_env
+from durable_sync.connectors.contentful import oauth, store
+
+
+def main() -> None:
+    load_env()
+    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)
+    token = tokens["access_token"]
+
+    for url in ("https://api.contentful.com/users/me", "https://api.contentful.com/spaces"):
+        r = httpx.get(url, headers={"Authorization": f"Bearer {token}"}, timeout=30)
+        print(f"GET {url} -> {r.status_code}")
+        print(f"   {r.text[:300].strip()}")
+        print()
+
+    print("Verdict:")
+    print("  /spaces 200 (lists spaces)  -> MCP-OAuth token works on CMA REST: reuse the REST connector.")
+    print("  401 / 403 / empty           -> token is MCP-scoped only: we parse MCP tool output instead.")
+
+
+if __name__ == "__main__":
+    main()

durable_sync/connectors/github/__init__.py

@@ -0,0 +1,33 @@
+"""GitHub source: orgs + named repos -> Records.
+
+The reference Source. Ships the GitHub *mechanism* (HTTP fetchers + generic
+helpers); the *policy/vocab* (which topics mean what, language->SDK maps,
+static analysis) belongs in your app's `enrich` hook — see RepoContext.
+
+Requires the `github` extra:  pip install "durable-sync[github]"
+"""
+from __future__ import annotations
+
+from durable_sync.connectors.github.api import (
+    build_headers,
+    classify,
+    fetch_org_members,
+    is_member,
+    raw_languages,
+)
+from durable_sync.connectors.github.source import (
+    GitHubConfig,
+    GitHubSource,
+    RepoContext,
+)
+
+__all__ = [
+    "GitHubSource",
+    "GitHubConfig",
+    "RepoContext",
+    "is_member",
+    "classify",
+    "raw_languages",
+    "fetch_org_members",
+    "build_headers",
+]

durable_sync/connectors/github/api.py

@@ -0,0 +1,169 @@
+"""GitHub REST helpers — pure HTTP + small pure transforms. No Temporal, no
+config globals: every call takes its `headers`. Reusable from the Source's
+fetch loop AND from an app's enrich hook (which gets the live client via
+RepoContext).
+"""
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from durable_sync.http import request_with_retry
+
+GITHUB_API = "https://api.github.com"
+PER_PAGE = 100
+log = logging.getLogger("durable_sync.connectors.github")
+
+
+def build_headers(token: str | None, *, user_agent: str = "durable-sync") -> dict[str, str]:
+    h = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": user_agent,
+    }
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
+# --- pure transforms -------------------------------------------------------
+
+def raw_languages(byte_counts: dict[str, int]) -> list[str]:
+    """All GitHub-reported languages, most-bytes-first."""
+    return sorted(byte_counts, key=lambda lang: -byte_counts[lang])
+
+
+def classify(topics: list[str], mapping: dict[str, str]) -> list[str]:
+    """Map topics through a {topic_lower: label} dict, de-duped, order-preserving.
+    The mapping itself is app vocab — the library just applies it."""
+    out: list[str] = []
+    for t in topics:
+        label = mapping.get(t.lower())
+        if label and label not in out:
+            out.append(label)
+    return out
+
+
+def is_member(handle: str, members: set[str]) -> bool:
+    """Whether a contributor handle belongs to the org-member set (insider-or-not).
+    Neutral primitive: an app's enrich hook picks its own labels
+    (e.g. Employee/Community, Staff/External) from this boolean."""
+    return handle in members
+
+
+def iso_date(s: str | None) -> str | None:
+    """ISO date (YYYY-MM-DD); the destination handles date_properties specially."""
+    return s[:10] if s else None
+
+
+# --- HTTP fetchers ---------------------------------------------------------
+# All go through request_with_retry, which backs off on 429 + GitHub's
+# rate-limited 403 (honoring Retry-After). The enrichment fetchers below tolerate
+# a failed call by returning empty, but LOG it first — a silently empty languages
+# list (because we got rate-limited) reads as "this repo has no languages", which
+# is a data-quality landmine on a large org sweep.
+
+async def get_repo(client: httpx.AsyncClient, full_name: str, headers: dict) -> dict | None:
+    r = await request_with_retry(client, "GET", f"{GITHUB_API}/repos/{full_name}", headers=headers)
+    if r.status_code == 404:
+        log.warning("Repo not found, skipping: %s", full_name)
+        return None
+    r.raise_for_status()
+    return r.json()
+
+
+async def fetch_org_repos_page(
+    client: httpx.AsyncClient, org: str, headers: dict, *, page: int, per_page: int = PER_PAGE
+) -> tuple[list[dict], bool]:
+    """ONE page of an org's public repos. Returns (batch, has_more). The page number
+    is the pagination cursor the spine threads through `GitHubSource.fetch_page`, so
+    the fetch result never passes through workflow history as one oversized payload.
+    Caller applies inclusion gating. Ordered by full_name (stable across pages)."""
+    r = await request_with_retry(
+        client, "GET", f"{GITHUB_API}/orgs/{org}/repos",
+        headers=headers,
+        params={"per_page": per_page, "page": page, "type": "public", "sort": "full_name"},
+    )
+    r.raise_for_status()
+    batch = r.json()
+    return batch, len(batch) == per_page
+
+
+async def fetch_org_repos(
+    client: httpx.AsyncClient, org: str, headers: dict, *, per_page: int = PER_PAGE
+) -> list[dict]:
+    """All public repos in an org — drains fetch_org_repos_page. For non-Temporal
+    callers (an enrich hook, a script); the spine uses the paged form directly."""
+    repos: list[dict] = []
+    page = 1
+    while True:
+        batch, has_more = await fetch_org_repos_page(client, org, headers, page=page, per_page=per_page)
+        repos.extend(batch)
+        if not has_more:
+            return repos
+        page += 1
+
+
+async def fetch_readme(client: httpx.AsyncClient, full_name: str, headers: dict) -> str | None:
+    h = dict(headers, Accept="application/vnd.github.raw")
+    r = await request_with_retry(client, "GET", f"{GITHUB_API}/repos/{full_name}/readme", headers=h)
+    if r.status_code == 200:
+        return r.text
+    if r.status_code != 404:  # 404 = no README (normal); anything else is a real failure
+        log.warning("README fetch for %s failed: HTTP %s", full_name, r.status_code)
+    return None
+
+
+async def fetch_languages(client: httpx.AsyncClient, full_name: str, headers: dict) -> dict[str, int]:
+    r = await request_with_retry(client, "GET", f"{GITHUB_API}/repos/{full_name}/languages", headers=headers)
+    if r.status_code == 200:
+        return r.json()
+    log.warning("Languages fetch for %s failed: HTTP %s — record will list none", full_name, r.status_code)
+    return {}
+
+
+async def fetch_contributors(
+    client: httpx.AsyncClient, full_name: str, headers: dict, *, limit: int = 5
+) -> list[str]:
+    """Top contributor handles, most-commits-first, bots filtered out."""
+    r = await request_with_retry(
+        client, "GET", f"{GITHUB_API}/repos/{full_name}/contributors",
+        headers=headers, params={"per_page": 25},
+    )
+    if r.status_code != 200:
+        log.warning("Contributors fetch for %s failed: HTTP %s", full_name, r.status_code)
+        return []
+    data = r.json()
+    if not isinstance(data, list):
+        return []
+    out: list[str] = []
+    for c in data:
+        login = c.get("login")
+        if login and not login.endswith("[bot]"):
+            out.append(login)
+        if len(out) >= limit:
+            break
+    return out
+
+
+async def fetch_org_members(client: httpx.AsyncClient, org: str, headers: dict) -> set[str]:
+    """Member logins for an org (needs read:org to see private members)."""
+    members: set[str] = set()
+    page = 1
+    while True:
+        r = await request_with_retry(
+            client, "GET", f"{GITHUB_API}/orgs/{org}/members",
+            headers=headers, params={"per_page": 100, "page": page},
+        )
+        if r.status_code != 200:
+            log.warning("Org members fetch for %s failed: HTTP %s", org, r.status_code)
+            break
+        batch = r.json()
+        if not isinstance(batch, list):
+            break
+        members.update(m["login"] for m in batch if m.get("login"))
+        if len(batch) < 100:
+            break
+        page += 1
+    return members

durable_sync/connectors/github/source.py

@@ -0,0 +1,230 @@
+"""GitHubSource — the reference Source, with a source-side enrichment hook.
+
+Config is injected (no module globals), so the same code serves any orgs/repos.
+The base fetch produces a raw Record per repo. If you pass an `enrich` hook, the
+source ALSO hands it a `RepoContext` (the raw repo + readme + language bytes +
+authors + employee members + the live HTTP client) so your app can layer on
+domain enrichment WITHOUT importing the source's internals.
+"""
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Union
+
+import httpx
+from temporalio import activity
+
+from durable_sync.core import Record, SourceSpec
+from durable_sync.connectors.github import api
+
+log = logging.getLogger("durable_sync.connectors.github")
+
+# enrich(record, ctx) -> Record (sync) or Awaitable[Record] (async); both ok.
+EnrichHook = Callable[[Record, "RepoContext"], Union[Record, Awaitable[Record]]]
+
+
+@dataclass
+class GitHubConfig:
+    """Everything GitHub-specific a deployment supplies.
+
+    sources: list of ("org", "name") and/or ("repos", ["owner/repo", ...]).
+      org sources are gated by inclusion_topic (unless it's None / discovery_mode);
+      named repos are included by virtue of being named.
+    """
+    sources: list[tuple[str, Any]]
+    # Include only org repos carrying this GitHub topic. None = no topic gate
+    # (include every non-archived repo). There's no universal default, so set the
+    # topic your org uses to mark in-scope repos.
+    inclusion_topic: str | None = None
+    discovery_mode: bool = False          # org sweep ignores topic + skips README
+    # Orgs whose member logins are surfaced to the enrich hook as RepoContext.members
+    # (e.g. to distinguish insiders from outside contributors). The source attaches
+    # the set; YOUR hook decides what membership means.
+    member_orgs: list[str] = field(default_factory=list)
+    title_property: str = "Name"
+    interval_minutes: int = 30
+    per_page: int = api.PER_PAGE
+    token_env: str = "GITHUB_TOKEN"
+    contributor_limit: int = 5
+
+
+@dataclass
+class RepoContext:
+    """Handed to the enrich hook: everything already fetched for one repo, plus
+    the live client + headers so enrich can make extra calls (e.g. download a
+    tarball for static analysis) without re-authenticating or re-fetching."""
+    raw_repo: dict
+    readme: str | None
+    language_bytes: dict[str, int]
+    authors: list[str]
+    members: set[str]
+    client: httpx.AsyncClient
+    headers: dict[str, str]
+
+
+def _heartbeat(detail: str) -> None:
+    """Heartbeat inside a Temporal activity; no-op otherwise, so the Source stays
+    runnable/testable standalone."""
+    if activity.in_activity():
+        activity.heartbeat(detail)
+
+
+class GitHubSource:
+    name = "github"
+
+    def __init__(self, config: GitHubConfig, *, enrich: EnrichHook | None = None):
+        self._config = config
+        self._enrich = enrich
+
+    # --- Source protocol ---------------------------------------------------
+
+    def specs(self) -> list[SourceSpec]:
+        cfg = self._config
+        specs: list[SourceSpec] = []
+        for kind, value in cfg.sources:
+            if kind == "org":
+                specs.append(SourceSpec(
+                    key=f"org:{value}",
+                    interval_minutes=cfg.interval_minutes,
+                    params={"kind": "org", "org": str(value)},
+                ))
+            else:  # "repos"
+                specs.append(SourceSpec(
+                    key="repos:named",
+                    interval_minutes=cfg.interval_minutes,
+                    params={"kind": "repos", "repos": list(value)},
+                ))
+        return specs
+
+    async def fetch_page(
+        self, spec: SourceSpec, only_items: list[str] | None, cursor: str | None
+    ) -> tuple[list[Record], str | None]:
+        """ONE page of records + the next cursor (None on the last page). For an org
+        sweep the cursor is the GitHub page number, so the spine bounds history even
+        for a huge org. The named-repos / targeted (`only_items`) paths are small and
+        bounded, so they return everything as a single page (next_cursor=None)."""
+        cfg = self._config
+        kind = spec.params.get("kind")
+        headers = api.build_headers(os.environ.get(cfg.token_env))
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            members = await self._members(client, headers)
+            repos, next_cursor = await self._select_repos_page(
+                client, headers, spec, kind, only_items, cursor)
+            records = await self._records_for_repos(client, headers, repos, members)
+
+        log.info("Fetched %d records for %s (cursor=%s -> %s)", len(records), spec.key, cursor, next_cursor)
+        return records, next_cursor
+
+    async def fetch(
+        self, spec: SourceSpec, only_items: list[str] | None = None
+    ) -> list[Record]:
+        """Whole unit as one list — drains fetch_page. Convenience for standalone /
+        non-Temporal callers; the spine drives fetch_page page-by-page instead."""
+        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
+
+    # --- internals ---------------------------------------------------------
+
+    async def _members(self, client, headers) -> set[str]:
+        """Org member logins for the enrich hook — only when a hook can use them.
+        Re-fetched per page in the paged path (activities are stateless); members
+        change rarely and member_orgs is opt-in, so the extra calls are acceptable."""
+        members: set[str] = set()
+        if self._enrich and self._config.member_orgs:
+            for org in self._config.member_orgs:
+                members |= await api.fetch_org_members(client, org, headers)
+        return members
+
+    async def _records_for_repos(self, client, headers, repos, members) -> list[Record]:
+        cfg = self._config
+        out: list[Record] = []
+        seen: set[str] = set()
+        for repo in repos:
+            rid = str(repo["id"])
+            if rid in seen:  # de-dupe within the page (cross-page dups resolve to
+                continue     # updates in the idempotent upsert, so per-page is enough)
+            seen.add(rid)
+            # Discovery skips READMEs (hundreds of calls).
+            readme = None if cfg.discovery_mode else await api.fetch_readme(
+                client, repo["full_name"], headers)
+            lang_bytes = await api.fetch_languages(client, repo["full_name"], headers)
+            authors = await api.fetch_contributors(
+                client, repo["full_name"], headers, limit=cfg.contributor_limit)
+
+            record = self._base_record(repo, readme, lang_bytes, authors)
+            if self._enrich is not None:
+                ctx = RepoContext(
+                    raw_repo=repo, readme=readme, language_bytes=lang_bytes,
+                    authors=authors, members=members, client=client, headers=headers,
+                )
+                result = self._enrich(record, ctx)
+                record = await result if inspect.isawaitable(result) else result
+            out.append(record)
+            _heartbeat(repo["full_name"])
+        return out
+
+    async def _select_repos_page(
+        self, client, headers, spec, kind, only_items, cursor
+    ) -> tuple[list[dict], str | None]:
+        if only_items:  # targeted refresh — bounded, one page (gate org repos)
+            return await self._repos_by_name(client, headers, only_items, gate=(kind == "org")), None
+        if kind == "org":
+            page = int(cursor) if cursor else 1
+            batch, has_more = await api.fetch_org_repos_page(
+                client, spec.params.get("org", ""), headers, page=page, per_page=self._config.per_page)
+            gated = [r for r in batch if self._passes_gate(r)]
+            return gated, (str(page + 1) if has_more else None)
+        # named repos — included by virtue of being named, bounded, one page
+        return await self._repos_by_name(client, headers, spec.params.get("repos", []), gate=False), None
+
+    async def _repos_by_name(self, client, headers, names, *, gate: bool) -> list[dict]:
+        repos: list[dict] = []
+        for full in names:
+            repo = await api.get_repo(client, full, headers)
+            if repo is None:
+                continue
+            if gate and not self._passes_gate(repo):
+                continue
+            repos.append(repo)
+        return repos
+
+    def _passes_gate(self, repo: dict) -> bool:
+        if repo.get("archived"):
+            return False
+        if self._config.discovery_mode or self._config.inclusion_topic is None:
+            return True
+        topics = [t.lower() for t in (repo.get("topics") or [])]
+        return self._config.inclusion_topic.lower() in topics
+
+    def _base_record(
+        self, repo: dict, readme: str | None, lang_bytes: dict[str, int], authors: list[str]
+    ) -> Record:
+        languages = api.raw_languages(lang_bytes)
+        spdx = (repo.get("license") or {}).get("spdx_id")
+        props = {
+            self._config.title_property: repo["name"],
+            "Repo ID": str(repo["id"]),
+            "Repo URL": repo["html_url"],
+            "Description": repo.get("description") or "",
+            "Languages": ", ".join(languages),
+            "Topics (raw)": ", ".join(repo.get("topics") or []),
+            "Authors": ", ".join(authors),
+            "Stars": int(repo.get("stargazers_count") or 0),
+            "Forks": int(repo.get("forks_count") or 0),
+            "Open issues": int(repo.get("open_issues_count") or 0),
+            "Is fork": bool(repo.get("fork")),
+            # NOASSERTION = no recognized license -> blank (itself a signal)
+            "License": spdx if spdx and spdx != "NOASSERTION" else None,
+            "Created": api.iso_date(repo.get("created_at")),
+            "Last updated": api.iso_date(repo.get("pushed_at") or repo.get("created_at")),
+        }
+        return Record(primary_key=str(repo["id"]), properties=props, body=readme)

durable_sync/connectors/luma/__init__.py

@@ -0,0 +1,20 @@
+"""Luma connector: a Luma calendar's events, BOTH directions.
+
+`LumaSource` reads events -> Records; `LumaDestination` creates/updates events
+(e.g. cross-posting from Notion), sharing api.py. Source policy (e.g. matching
+hosts against your own directory) belongs in the source's `enrich` hook — see
+LumaEventContext. Because Luma events can't hold a foreign key, the destination
+takes a required `LinkStore` (app-owned correspondence; see the boundary doctrine).
+
+Requires the `luma` extra:  pip install "durable-sync[luma]"
+"""
+from __future__ import annotations
+
+from durable_sync.linkstore import InMemoryLinkStore, LinkStore  # re-export for convenience
+from durable_sync.connectors.luma.destination import LumaDestination
+from durable_sync.connectors.luma.source import LumaConfig, LumaEventContext, LumaSource
+
+__all__ = [
+    "LumaSource", "LumaConfig", "LumaEventContext",
+    "LumaDestination", "LinkStore", "InMemoryLinkStore",
+]

durable_sync/connectors/luma/api.py

@@ -0,0 +1,121 @@
+"""Luma API helpers — pure async HTTP + small pure transforms. No Temporal, no
+config globals: every call takes its `headers`. Reusable from the Source's fetch
+loop AND from an app's enrich hook (which gets the live client via the context).
+
+Verify paths/params against Luma's docs as they evolve:
+https://docs.luma.com/reference/get_v1-calendar-list-events
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from durable_sync.core import DestinationHTTPError
+from durable_sync.http import request_with_retry
+
+BASE_URL = "https://public-api.luma.com/v1"
+LIST_EVENTS_PATH = "/calendar/list-events"
+GET_EVENT_PATH = "/event/get"
+PAGE_LIMIT = 50
+log = logging.getLogger("durable_sync.connectors.luma")
+
+
+def build_headers(api_key: str | None) -> dict[str, str]:
+    return {"x-luma-api-key": api_key or "", "Accept": "application/json"}
+
+
+async def list_event_entries_page(
+    client: httpx.AsyncClient, headers: dict, after_iso: str, *,
+    cursor: str | None = None, page_limit: int = PAGE_LIMIT,
+) -> tuple[list[dict[str, Any]], str | None]:
+    """ONE page of raw Luma event entries on/after `after_iso`. Returns
+    (entries, next_cursor) where next_cursor is Luma's pagination_cursor for the
+    next page, or None when there are no more — the cursor the spine threads
+    through `LumaSource.fetch_page`. `list-events` does NOT include hosts."""
+    params: dict[str, Any] = {"after": after_iso, "pagination_limit": page_limit}
+    if cursor:
+        params["pagination_cursor"] = cursor
+    r = await request_with_retry(
+        client, "GET", f"{BASE_URL}{LIST_EVENTS_PATH}", headers=headers, params=params
+    )
+    r.raise_for_status()
+    data = r.json()
+    entries = data.get("entries", data.get("events", []))
+    next_cursor = data.get("next_cursor") if data.get("has_more") else None
+    return entries, next_cursor
+
+
+async def list_event_entries(
+    client: httpx.AsyncClient, headers: dict, after_iso: str, *, page_limit: int = PAGE_LIMIT
+) -> list[dict[str, Any]]:
+    """All raw Luma event entries on/after `after_iso` — drains
+    list_event_entries_page. For non-Temporal callers; the spine pages directly."""
+    entries: list[dict[str, Any]] = []
+    cursor: str | None = None
+    while True:
+        batch, cursor = await list_event_entries_page(
+            client, headers, after_iso, cursor=cursor, page_limit=page_limit)
+        entries.extend(batch)
+        if cursor is None:
+            return entries
+
+
+async def get_event(client: httpx.AsyncClient, headers: dict, api_id: str) -> dict[str, Any] | None:
+    """One event by id, as a list-style entry ({event, hosts, ...}) or None if
+    gone. Used for targeted refreshes (only_items)."""
+    if not api_id:
+        return None
+    r = await request_with_retry(
+        client, "GET", f"{BASE_URL}{GET_EVENT_PATH}", headers=headers, params={"api_id": api_id}
+    )
+    if r.status_code == 404:
+        log.warning("Luma event not found, skipping: %s", api_id)
+        return None
+    r.raise_for_status()
+    return r.json()
+
+
+async def get_event_hosts(client: httpx.AsyncClient, headers: dict, api_id: str) -> list[dict[str, Any]]:
+    """Hosts for one event: [{name, email, ...}]. N+1 against the list (fine at
+    current volume; gate behind a change-token if a source grows high-volume)."""
+    if not api_id:
+        return []
+    r = await request_with_retry(
+        client, "GET", f"{BASE_URL}{GET_EVENT_PATH}", headers=headers, params={"api_id": api_id}
+    )
+    if r.status_code == 404:
+        return []
+    r.raise_for_status()
+    return r.json().get("hosts", [])
+
+
+# --- write side (used by LumaDestination) -----------------------------------
+# Verify paths/payload keys against Luma's docs — the write API evolves:
+# https://docs.luma.com/reference/post_v1-event-create
+
+CREATE_EVENT_PATH = "/event/create"
+UPDATE_EVENT_PATH = "/event/update"
+
+
+async def _write(client: httpx.AsyncClient, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """POST to Luma; raise with status text (so is_auth_error can classify a 401).
+    The client carries the x-luma-api-key header (set in connect)."""
+    r = await request_with_retry(client, "POST", f"{BASE_URL}{path}", json=payload)
+    if r.status_code >= 400:
+        raise DestinationHTTPError(r.status_code, f"Luma POST {path} -> {r.status_code}: {r.text[:600]}")
+    return r.json() if r.content else {}
+
+
+async def create_event(client: httpx.AsyncClient, payload: dict[str, Any]) -> str:
+    """Create an event; return its api_id."""
+    data = await _write(client, CREATE_EVENT_PATH, payload)
+    event = data.get("event", data)
+    return event.get("api_id") or data.get("api_id") or ""
+
+
+async def update_event(client: httpx.AsyncClient, api_id: str, payload: dict[str, Any]) -> None:
+    """Update an existing event in place. NB: /event/update names the identifier
+    `event_id` (create returns it as `api_id`) — confirmed against the live API."""
+    await _write(client, UPDATE_EVENT_PATH, {"event_id": api_id, **payload})