durable-sync 0.1.0__py3-none-any.whl

durable_sync/connectors/youtube/api.py

@@ -0,0 +1,122 @@
+"""YouTube Data API v3 helpers — pure async HTTP + small pure transforms. No
+Temporal, no config globals. Lists a channel's "uploads" playlist (channel id or
+@handle, resolved here), yielding {videoId, title, description, publishedAt,
+viewCount}. Read-only.
+
+Docs: https://developers.google.com/youtube/v3/docs
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from durable_sync.http import request_with_retry
+
+API = "https://www.googleapis.com/youtube/v3"
+PAGE = 50  # API max
+log = logging.getLogger("durable_sync.connectors.youtube")
+
+
+async def _get(client: httpx.AsyncClient, api_key: str, path: str, params: dict[str, Any]) -> dict[str, Any]:
+    r = await request_with_retry(client, "GET", f"{API}/{path}", params={**params, "key": api_key})
+    r.raise_for_status()
+    return r.json()
+
+
+def parse_ts(ts: str) -> datetime:
+    return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+
+
+async def uploads_playlist(client: httpx.AsyncClient, api_key: str, channel: str) -> str:
+    """Resolve a channel id ('UC…') or '@handle' to its uploads playlist id."""
+    ch = channel.strip()
+    if ch.startswith("UC") and " " not in ch:
+        data = await _get(client, api_key, "channels", {"part": "contentDetails", "id": ch})
+    else:
+        data = await _get(client, api_key, "channels", {"part": "contentDetails", "forHandle": ch.lstrip("@")})
+    items = data.get("items", [])
+    if not items:
+        raise RuntimeError(f"YouTube channel not found: {channel!r}")
+    return items[0]["contentDetails"]["relatedPlaylists"]["uploads"]
+
+
+async def list_videos_page(
+    client: httpx.AsyncClient, api_key: str, playlist: str, after_iso: str, *, page_token: str | None = None
+) -> tuple[list[dict[str, Any]], str | None]:
+    """ONE page of videos published on/after `after_iso` (with view counts), plus
+    the next pageToken or None. The uploads playlist is reverse-chronological, so we
+    stop (next=None) once a video predates the window — the cursor the spine threads
+    through `YouTubeSource.fetch_page`."""
+    after = parse_ts(after_iso)
+    params: dict[str, Any] = {"part": "snippet,contentDetails", "playlistId": playlist, "maxResults": PAGE}
+    if page_token:
+        params["pageToken"] = page_token
+    data = await _get(client, api_key, "playlistItems", params)
+
+    metas: list[dict[str, Any]] = []
+    stop = False
+    for it in data.get("items", []):
+        sn, cd = it.get("snippet", {}), it.get("contentDetails", {})
+        vid = cd.get("videoId")
+        pub = cd.get("videoPublishedAt") or sn.get("publishedAt")
+        if not vid or not pub:
+            continue
+        if parse_ts(pub) < after:
+            stop = True
+            break
+        metas.append({"videoId": vid, "title": sn.get("title", ""),
+                      "description": sn.get("description", ""), "publishedAt": pub})
+
+    views = await view_counts(client, api_key, [m["videoId"] for m in metas]) if metas else {}
+    for m in metas:
+        m["viewCount"] = views.get(m["videoId"])
+
+    next_token = None if stop else (data.get("nextPageToken") or None)
+    return metas, next_token
+
+
+async def list_videos(client: httpx.AsyncClient, api_key: str, playlist: str, after_iso: str) -> list[dict[str, Any]]:
+    """All videos on/after `after_iso` — drains list_videos_page. Non-Temporal
+    callers; the spine pages directly."""
+    out: list[dict[str, Any]] = []
+    page_token: str | None = None
+    while True:
+        metas, page_token = await list_videos_page(client, api_key, playlist, after_iso, page_token=page_token)
+        out.extend(metas)
+        if page_token is None:
+            return out
+
+
+async def videos_by_id(client: httpx.AsyncClient, api_key: str, ids: list[str]) -> list[dict[str, Any]]:
+    """Specific videos by id (for targeted refreshes), same meta shape as the list."""
+    ids = [i for i in ids if i]
+    if not ids:
+        return []
+    data = await _get(client, api_key, "videos", {"part": "snippet,statistics", "id": ",".join(ids[:PAGE])})
+    out: list[dict[str, Any]] = []
+    for it in data.get("items", []):
+        sn, st = it.get("snippet", {}), it.get("statistics", {})
+        vc = st.get("viewCount")
+        out.append({
+            "videoId": it.get("id", ""),
+            "title": sn.get("title", ""),
+            "description": sn.get("description", ""),
+            "publishedAt": sn.get("publishedAt"),
+            "viewCount": int(vc) if vc is not None else None,
+        })
+    return out
+
+
+async def view_counts(client: httpx.AsyncClient, api_key: str, ids: list[str]) -> dict[str, int | None]:
+    """viewCount per video id (one batched call; ids already <= PAGE)."""
+    if not ids:
+        return {}
+    data = await _get(client, api_key, "videos", {"part": "statistics", "id": ",".join(ids)})
+    out: dict[str, int | None] = {}
+    for it in data.get("items", []):
+        vc = it.get("statistics", {}).get("viewCount")
+        out[it["id"]] = int(vc) if vc is not None else None
+    return out

durable_sync/connectors/youtube/source.py

@@ -0,0 +1,152 @@
+"""YouTubeSource — a channel's uploads -> Records, with a source-side enrich hook.
+
+YouTube has no per-video author field. The base Record therefore leaves "Author"
+empty and stashes the title + description as a "Scan Text" property (and on the
+enrich context) so an app that needs attribution can scan it for known names —
+an "inverted match" — rather than relying on a structured author. That policy
+lives in your `enrich` hook, not here.
+
+Auth: a YouTube Data API v3 key, read from the env var named by
+`YouTubeConfig.token_env`. Requires the `youtube` extra.
+"""
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import 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.youtube import api
+
+log = logging.getLogger("durable_sync.connectors.youtube")
+
+EnrichHook = Callable[[Record, "YouTubeVideoContext"], Union[Record, Awaitable[Record]]]
+
+_MAX_SUMMARY = 2000
+
+
+@dataclass
+class YouTubeConfig:
+    """Everything YouTube-specific a deployment supplies. `channel` (required) is a
+    channel id ('UC…') or a handle ('@name'); the client resolves a handle to its
+    id."""
+    channel: str
+    token_env: str = "YOUTUBE_API_KEY"
+    lookback_days: int = 21
+    interval_minutes: int = 360
+    title_property: str = "Name"
+    item_type: str = "Video"         # value written to the neutral "Type" column
+
+
+@dataclass
+class YouTubeVideoContext:
+    """Handed to the enrich hook: the raw video meta (incl. full description) plus
+    the live client, so enrich can do inverted name-matching or extra lookups."""
+    raw_video: dict
+    scan_text: str                 # title + description, for inverted matching
+    client: httpx.AsyncClient
+    api_key: str
+
+
+def _heartbeat(detail: str) -> None:
+    if activity.in_activity():
+        activity.heartbeat(detail)
+
+
+class YouTubeSource:
+    name = "youtube"
+
+    def __init__(self, config: YouTubeConfig, *, enrich: EnrichHook | None = None):
+        self._config = config
+        self._enrich = enrich
+
+    def specs(self) -> list[SourceSpec]:
+        ch = self._config.channel
+        return [SourceSpec(key=f"channel:{ch}", interval_minutes=self._config.interval_minutes,
+                           params={"channel": ch})]
+
+    async def fetch_page(
+        self, spec: SourceSpec, only_items: list[str] | None, cursor: str | None
+    ) -> tuple[list[Record], str | None]:
+        """ONE page of videos + next cursor (None on the last page). The cursor
+        carries the frozen window start, the resolved uploads playlist (so we don't
+        re-resolve the channel each page), and YouTube's pageToken. A targeted
+        (`only_items`) refresh is bounded, so it returns a single page."""
+        cfg = self._config
+        api_key = os.environ.get(cfg.token_env, "")
+        channel = spec.params.get("channel", cfg.channel)
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            if only_items:
+                videos = await api.videos_by_id(client, api_key, only_items)
+                next_cursor = None
+            else:
+                if cursor is None:
+                    after_iso = (datetime.now(timezone.utc) - timedelta(days=cfg.lookback_days)).isoformat()
+                    playlist = await api.uploads_playlist(client, api_key, channel)
+                    page_token = None
+                else:
+                    c = content.unpack_cursor(cursor)
+                    after_iso, playlist, page_token = c["after"], c["playlist"], c["token"]
+                videos, next_token = await api.list_videos_page(
+                    client, api_key, playlist, after_iso, page_token=page_token)
+                next_cursor = (
+                    content.pack_cursor(after=after_iso, playlist=playlist, token=next_token)
+                    if next_token else None
+                )
+
+            out: list[Record] = []
+            for v in videos:
+                record = self._to_record(v)
+                if self._enrich is not None:
+                    title = v.get("title") or ""
+                    scan_text = f"{title}\n{v.get('description', '')}"
+                    ctx = YouTubeVideoContext(raw_video=v, scan_text=scan_text, client=client, api_key=api_key)
+                    result = self._enrich(record, ctx)
+                    record = await result if inspect.isawaitable(result) else result
+                out.append(record)
+                _heartbeat(v.get("videoId", ""))
+
+        log.info("Fetched %d YouTube videos for %s (cursor=%s)", len(out), spec.key, cursor)
+        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, v: dict) -> Record:
+        """Map one video to a neutral Record. Pure (no IO)."""
+        cfg = self._config
+        vid = v.get("videoId", "")
+        title = v.get("title") or "(untitled video)"
+        description = v.get("description") or ""
+        return content.content_record(
+            primary_key=vid,
+            title_property=cfg.title_property,
+            title=title,
+            item_type=cfg.item_type,
+            source="YouTube",
+            url=f"https://www.youtube.com/watch?v={vid}" if vid else None,
+            date=v.get("publishedAt"),
+            status="Published",
+            author="",                          # no per-video author on YouTube
+            extra={
+                "Reach": v.get("viewCount"),
+                "Summary": description[:_MAX_SUMMARY],
+                # Free text for inverted matching by an app's enrich/transform hook.
+                "Scan Text": f"{title}\n{description}"[:_MAX_SUMMARY],
+            },
+        )

durable_sync/core.py

@@ -0,0 +1,210 @@
+"""Generic, source/destination-agnostic spine. No I/O here — this module is
+imported into the Temporal workflow sandbox, so it must stay side-effect-free.
+
+The whole library reduces to two seams:
+
+  * a Source produces `Record`s (fetch + map your data),
+  * a Destination upserts them idempotently.
+
+Everything painful — durable orchestration, idempotent upsert, OAuth refresh,
+pagination, rate-limit backoff, error handling — lives in the spine and is
+inherited for free. To add a source you implement `Source`; to add a
+destination, `Destination`. Reference implementations: GitHub (source), Notion
+and Asana (destinations).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, field
+from typing import Any, AsyncContextManager, Protocol, runtime_checkable
+
+
+@dataclass
+class Record:
+    """One row to upsert, in DESTINATION-AGNOSTIC form. `properties` values are
+    NEUTRAL Python types — the Destination owns wire-encoding, so a Source author
+    never learns a destination's quirks (Notion's multi-select JSON, Asana's
+    custom fields, etc.):
+
+        str            -> text / url / select / title
+        bool           -> checkbox
+        int | float    -> number
+        list[str]      -> multi-select
+        datetime.date  -> date          datetime.datetime -> datetime
+        None           -> property omitted
+
+    `primary_key` is the IMMUTABLE idempotency key (e.g. a repo id), never a
+    name/URL — this is what makes at-least-once retries safe. `body` is optional
+    long-form content (e.g. a README / task notes), written on create.
+    """
+    primary_key: str
+    properties: dict[str, Any]
+    body: str | None = None
+
+
+@dataclass
+class SourceSpec:
+    """One unit of work for a Source, handed to its per-source entity workflow.
+    `key` is a stable id used to derive the workflow id. `params` is opaque,
+    source-defined config (e.g. {"kind": "org", "org": "temporal-community"})."""
+    key: str
+    interval_minutes: int = 30
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Source(Protocol):
+    """Implement this for your data source. GitHubSource is the reference impl."""
+    name: str
+
+    def specs(self) -> list[SourceSpec]:
+        """One SourceSpec per independent unit (each gets its own workflow)."""
+        ...
+
+    async def fetch(
+        self, spec: SourceSpec, only_items: list[str] | None = None
+    ) -> list[Record]:
+        """Fetch (optionally just `only_items`) and map to Records. All
+        source-specific I/O and field-mapping happens here. Returns the WHOLE unit
+        in one list — simplest, and fine up to ~hundreds of records.
+
+        For a source that can return many thousands, implement `fetch_page` (below)
+        instead: the spine drives it page-by-page so neither the fetch result nor
+        the upsert ever passes through Temporal history as one oversized payload."""
+        ...
+
+    # OPTIONAL (checked via getattr by the spine — like the Destination's aux hooks),
+    # but PREFERRED: every shipped connector (GitHub/Luma/YouTube/Contentful)
+    # implements it, with fetch() as a thin drain over it. The spine calls it
+    # repeatedly, threading your cursor, and upserts each page before asking for the
+    # next — bounding history regardless of total size. When present it's used in
+    # preference to fetch(). A genuinely tiny source can skip it and just implement
+    # fetch() (the spine treats that as one page).
+    #
+    #   async def fetch_page(
+    #       self, spec: SourceSpec, only_items: list[str] | None, cursor: str | None
+    #   ) -> tuple[list[Record], str | None]:
+    #       """Return (records_for_this_page, next_cursor). next_cursor is None on
+    #       the last page. `cursor` is None on the first call. Opaque to the spine —
+    #       use whatever your API's pagination token is (offset, page no, cursor)."""
+
+
+class DestinationSession(Protocol):
+    """An open connection to the destination for one sync pass."""
+
+    async def query_existing_ids(self) -> dict[str, str]:
+        """{ primary_key -> destination-internal id } for rows already present."""
+        ...
+
+    async def create(self, record: Record, synced_at: dt.datetime) -> bool:
+        """Insert a new row. `synced_at` is the sync-pass timestamp (a real
+        datetime — the destination formats it however its schema needs).
+        Returns True if written, False if SKIPPED (e.g. a destination-side enrich
+        hook dropped the record as out-of-scope)."""
+        ...
+
+    async def update(self, existing_id: str, record: Record, synced_at: dt.datetime) -> bool:
+        """Refresh an existing row, leaving `create_only` properties untouched so
+        human edits to those seeds survive. `synced_at` as in create(). Returns
+        True if written, False if skipped."""
+        ...
+
+
+class Destination(Protocol):
+    """Implement this for your destination. NotionDestination / AsanaDestination
+    are the reference impls (MCP+OAuth and REST+PAT respectively — the protocol is
+    intentionally neither transport- nor auth-shaped)."""
+    name: str
+
+    # True once the destination has the config it needs to write (e.g. a target
+    # id). The spine refuses to sync an unconfigured destination.
+    configured: bool
+
+    # Properties written only on CREATE — enrichment seeds a human refines, never
+    # overwritten on update. The mechanism is generic; each Source supplies which
+    # fields. Honored by update().
+    create_only_properties: set[str]
+
+    def connect(self) -> AsyncContextManager[DestinationSession]: ...
+
+    # OPTIONAL hooks (checked via getattr by the worker — don't define if unused):
+    #   def aux_workflows(self) -> list: ...   extra Temporal workflows to register
+    #   def aux_activities(self) -> list: ...  extra activities to register
+    # e.g. the Notion destination registers its token-owner auth workflow here.
+
+    @property
+    def config_hint(self) -> str:
+        """Human-readable hint naming what to set when `configured` is False
+        (e.g. an env var). Keeps destination-specific config names out of the
+        generic spine's error messages."""
+        ...
+
+    @staticmethod
+    def is_auth_error(err: BaseException) -> bool:
+        """True if `err` is an auth failure only a human can fix (so the workflow
+        pauses instead of hammering). Destination-specific. OPTIONAL: destinations
+        with no interactive auth (e.g. a local DB) should just `return False`.
+        Most HTTP destinations can delegate to `auth_error_in_chain` below."""
+        ...
+
+
+class DestinationHTTPError(RuntimeError):
+    """An HTTP error from a destination, carrying the numeric `status_code`
+    SEPARATELY from the message. `auth_error_in_chain` keys auth-classification on
+    this code rather than scanning the (up-to-600-char) response body — where a
+    stray standalone "403" in an error payload would spuriously pause the workflow.
+    Destinations should raise this (not a bare RuntimeError) for HTTP failures."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+# Default auth-failure signatures shared by HTTP destinations. The numeric code is
+# taken from a DestinationHTTPError.status_code when present; otherwise (a plain
+# exception) we fall back to a WORD-BOUNDARY text match so a bare "401"/"403"
+# inside a UUID or request-id can't false-positive — the bug that once paused a
+# workflow on a Notion validation_error whose id contained "401e".
+_AUTH_TEXT_NEEDLES = ("unauthorized", "forbidden", "invalid_token", "invalid_grant")
+_AUTH_STATUS_CODES = (401, 403)
+_AUTH_CODE_RE = re.compile(r"\b(401|403)\b")
+
+
+def auth_error_in_chain(err: BaseException, *, extra_needles: tuple[str, ...] = ()) -> bool:
+    """Shared `is_auth_error` implementation: walk `err`'s cause/context chain and
+    any ExceptionGroup, returning True if any link looks like a human-fixable auth
+    failure (401/403, unauthorized, forbidden, invalid_token/grant). A destination
+    passes `extra_needles` for service-specific phrasings (e.g. Asana's "not
+    authorized"). Pure/deterministic — no I/O — so it's safe to import widely.
+
+    Classification order per link: (1) a DestinationHTTPError's exact status_code;
+    (2) a text needle; (3) ONLY when the link carries no status_code, a
+    word-boundary 401/403 in the message. (3) is skipped for status-carrying errors
+    so a 422/500 whose body mentions "403" isn't misread as auth.
+
+    This lives in the spine so every destination shares ONE correct matcher
+    instead of re-deriving the chain walk + code check (which is exactly where
+    Notion and Asana had drifted apart)."""
+    needles = _AUTH_TEXT_NEEDLES + tuple(n.lower() for n in extra_needles)
+    seen: set[int] = set()
+    stack: list[BaseException] = [err]
+    while stack:
+        cur = stack.pop()
+        if id(cur) in seen:
+            continue
+        seen.add(id(cur))
+        status = getattr(cur, "status_code", None)
+        msg = str(cur).lower()
+        if status in _AUTH_STATUS_CODES:
+            return True
+        if any(n in msg for n in needles):
+            return True
+        if status is None and _AUTH_CODE_RE.search(msg):
+            return True
+        if isinstance(cur, BaseExceptionGroup):
+            stack.extend(cur.exceptions)
+        for nxt in (cur.__cause__, cur.__context__):
+            if nxt is not None:
+                stack.append(nxt)
+    return False

durable_sync/env.py

@@ -0,0 +1,55 @@
+"""Load a local `.env` into os.environ — dev convenience for `python -m …` tools
+and the live smokes, so each script doesn't roll its own (which led to scripts
+that silently ignored a populated `.env`).
+
+Idempotent, never overrides an already-set var, no-op if there's no `.env`. Uses
+python-dotenv when present (the `dev` extra); falls back to a tiny built-in parser
+so it still works in a minimal install. Run scripts from the repo root.
+
+NOT imported by config.py / the workflow sandbox — this does file IO, so it stays
+out of the deterministic path and is called explicitly by scripts only.
+"""
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+
+def load_env(path: str | os.PathLike | None = None) -> None:
+    _warn_if_world_readable(Path(path) if path else Path(".env"))
+    try:
+        from dotenv import load_dotenv
+    except ModuleNotFoundError:
+        _load_fallback(path)
+        return
+    load_dotenv(path) if path else load_dotenv()
+
+
+def _warn_if_world_readable(p: Path) -> None:
+    """The `.env` is the documented home for DURABLE_SYNC_ENC_KEY (the AES master
+    key) and connector PATs. The token JSON stores are chmod'd 0o600; the `.env`
+    must be too, or a local user reads the key that decrypts every token. Warn
+    (don't fail — a CI runner with injected env vars may have no `.env`)."""
+    try:
+        mode = p.stat().st_mode
+    except OSError:
+        return  # no file / not readable — nothing loaded from it
+    if mode & (stat.S_IRWXG | stat.S_IRWXO):
+        print(
+            f"WARNING: {p} is group/other-accessible (mode {oct(mode & 0o777)}); "
+            f"it may hold secrets (DURABLE_SYNC_ENC_KEY, PATs). Run: chmod 600 {p}",
+            file=sys.stderr,
+        )
+
+
+def _load_fallback(path: str | os.PathLike | None) -> None:
+    p = Path(path) if path else Path(".env")
+    if not p.exists():
+        return
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "=" in line:
+            k, v = line.split("=", 1)
+            os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))

durable_sync/http.py

@@ -0,0 +1,71 @@
+"""Shared httpx retry/backoff for REST sources & destinations.
+
+The destinations and the GitHub source all talk HTTP and all need the same
+manners under rate limiting (honor `Retry-After`, otherwise exponential backoff).
+That logic had drifted — Asana honored `Retry-After`, GitHub had no backoff at
+all — so it lives here once. NOT used by the Notion destination: the MCP
+transport surfaces failures as `isError` *results* rather than HTTP statuses, so
+it keeps its own small retry loop in `NotionDestination.call`.
+
+Runs inside Temporal activities (source fetch / destination session), never in a
+workflow, so wall-clock `asyncio.sleep` is fine. Sleeps are capped so a long
+rate-limit window becomes an activity retry (bounded by the activity timeout)
+rather than a single multi-minute blocking sleep.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+
+_MAX_ATTEMPTS = 6
+_BASE_DELAY_SECONDS = 1.0
+_MAX_DELAY_SECONDS = 60.0
+
+
+def _should_retry(resp: httpx.Response, retry_statuses: tuple[int, ...]) -> bool:
+    if resp.status_code in retry_statuses:
+        return True
+    # GitHub signals both its primary and secondary rate limits with 403 plus
+    # either a Retry-After or an exhausted X-RateLimit-Remaining. A plain 403
+    # (genuine permission failure) has neither and is NOT retried — it surfaces
+    # so `is_auth_error` can pause the workflow.
+    if resp.status_code == 403 and (
+        resp.headers.get("Retry-After")
+        or resp.headers.get("X-RateLimit-Remaining") == "0"
+    ):
+        return True
+    return False
+
+
+def _retry_delay(resp: httpx.Response, attempt: int, base: float) -> float:
+    retry_after = resp.headers.get("Retry-After")
+    if retry_after and retry_after.isdigit():
+        return min(float(retry_after), _MAX_DELAY_SECONDS)
+    return min(base * (2 ** attempt), _MAX_DELAY_SECONDS)
+
+
+async def request_with_retry(
+    client: httpx.AsyncClient,
+    method: str,
+    url: str,
+    *,
+    headers: dict | None = None,
+    params: dict | None = None,
+    json: object | None = None,
+    max_attempts: int = _MAX_ATTEMPTS,
+    base_delay: float = _BASE_DELAY_SECONDS,
+    retry_statuses: tuple[int, ...] = (429,),
+) -> httpx.Response:
+    """Issue an httpx request, retrying rate-limited/transient responses with
+    backoff that honors `Retry-After`. Returns the final `Response` (this helper
+    never raises on HTTP status — the caller decides how to treat 4xx/5xx, since
+    e.g. GitHub treats 404 as "skip" and Asana raises). Network errors propagate
+    to Temporal, which retries the whole activity."""
+    resp = await client.request(method, url, headers=headers, params=params, json=json)
+    for attempt in range(max_attempts - 1):
+        if not _should_retry(resp, retry_statuses):
+            return resp
+        await asyncio.sleep(_retry_delay(resp, attempt, base_delay))
+        resp = await client.request(method, url, headers=headers, params=params, json=json)
+    return resp