stackvitals 0.1.0__py3-none-any.whl

stackvitals/connectors/copilot.py

@@ -0,0 +1,104 @@
+"""GitHub Copilot usage reports (the report API that replaced the old metrics API in April 2026), kept day by day: the
+org's active users, suggestions accepted and Copilot pull requests, and this repo's Copilot pull requests. GitHub keeps
+these reports for a limited time; the copy in the data branch keeps them as long as the branch does."""
+import json
+from datetime import date, datetime, timedelta
+
+import httpx
+
+from stackvitals.ci.api import API  # GitHub Enterprise Server's too, when Actions names it
+from stackvitals.connectors.base import ConnectorError, json_of
+
+NAME, TOKEN_ENV = "copilot", "STACKVITALS_COPILOT_TOKEN"
+VERSION = "2026-03-10"
+DAYS = 60       # the most days one run reads, and how far back a first run starts
+LAG = 2         # a day is first asked for two days on; one GitHub hasn't finished yet is asked for again
+SETTLED = 4     # a day still without a report this long after (and none after it) had no usage
+FIRST = date(2025, 12, 12)  # the oldest organization report
+ORG_FIELDS = ("daily_active_users", "weekly_active_users", "monthly_active_users", "monthly_active_chat_users",
+              "monthly_active_agent_users", "code_generation_activity_count", "code_acceptance_activity_count",
+              "loc_suggested_to_add_sum", "loc_added_sum", "loc_deleted_sum")
+PR_FIELDS = ("total_created", "total_reviewed", "total_merged", "median_minutes_to_merge", "total_created_by_copilot",
+             "total_reviewed_by_copilot", "total_merged_created_by_copilot", "total_merged_reviewed_by_copilot",
+             "median_minutes_to_merge_copilot_authored")
+
+__all__ = ["ConnectorError", "configured", "pull"]
+
+
+def configured(env: dict, cfg: dict) -> bool:
+    return bool((env.get(TOKEN_ENV) or "").strip())
+
+
+def _report(client: httpx.Client, key: str, path: str, day: str) -> list[dict] | None:
+    """The NDJSON rows of one day's report, or None when GitHub has none for that day."""
+    try:
+        resp = client.get(f"{API}{path}", params={"day": day}, headers={
+            "Authorization": f"Bearer {key}", "Accept": "application/vnd.github+json", "X-GitHub-Api-Version": VERSION})
+    except httpx.HTTPError as exc:
+        raise ConnectorError(f"GitHub could not be reached for Copilot reports ({type(exc).__name__}).") from None
+    if resp.status_code in (401, 403):
+        raise ConnectorError(f"GitHub refused the Copilot reports key ({resp.status_code}): it needs \"Organization Copilot "
+                             "metrics: read\" (an org App or a fine-grained token) from an org owner.")
+    if resp.status_code == 404:
+        raise ConnectorError("GitHub has no Copilot usage reports for this organization (404): check org under "
+                             "[connectors.copilot] and that Copilot usage metrics are turned on.")
+    if resp.status_code == 204:
+        return None
+    if resp.status_code != 200:
+        raise ConnectorError(f"GitHub answered {resp.status_code} for Copilot reports; the next run tries again.")
+    rows = []
+    for link in json_of(resp, "GitHub").get("download_links") or []:
+        try:
+            # A signed link: fetched without the key, so the key never reaches the file host.
+            got = client.get(link)
+        except httpx.HTTPError as exc:
+            raise ConnectorError(f"A Copilot report file could not be downloaded ({type(exc).__name__}).") from None
+        if got.status_code != 200:
+            raise ConnectorError(f"A Copilot report file answered {got.status_code}; the next run tries again.")
+        try:
+            rows += [json.loads(line) for line in got.text.split("\n") if line.strip()]
+        except ValueError:
+            raise ConnectorError("A Copilot report file was not JSON lines; the next run tries again.") from None
+    return rows
+
+
+def _prs(row: dict) -> dict:
+    return {k: v for k, v in (row.get("pull_requests") or {}).items() if k in PR_FIELDS}
+
+
+def pull(store, env: dict, cfg: dict, now: datetime, client: httpx.Client | None = None, days: int = DAYS) -> dict:
+    owner, _, repo = (env.get("GITHUB_REPOSITORY") or "/").partition("/")
+    org = cfg["connectors"]["copilot"]["org"] or owner
+    key = env.get(TOKEN_ENV, "").strip()
+    own = client is None
+    client = client or httpx.Client(timeout=60)
+    try:
+        latest = now.date() - timedelta(days=LAG)
+        through = store.state().get("through")
+        start = date.fromisoformat(through) + timedelta(days=1) if through else max(FIRST, latest - timedelta(days=days - 1))
+        read, day, last, newest = 0, start, through, None
+        while day <= latest and (day - start).days < days:
+            org_rows = _report(client, key, f"/orgs/{org}/copilot/metrics/reports/organization-1-day", day.isoformat())
+            records = []
+            for row in org_rows or []:
+                gen, acc = row.get("code_generation_activity_count") or 0, row.get("code_acceptance_activity_count") or 0
+                records.append({"t": "org_day", "id": f"copilot:org:{day}", "day": day.isoformat(), "org": org,
+                                **{k: row.get(k) for k in ORG_FIELDS}, "acceptance": round(acc / gen, 4) if gen else None,
+                                "pull_requests": _prs(row)})
+            if org_rows:
+                read, newest = read + 1, day
+                repo_rows = _report(client, key, f"/orgs/{org}/copilot/metrics/reports/repos-1-day", day.isoformat()) or []
+                records += [{"t": "repo_day", "id": f"copilot:repo:{day}", "day": day.isoformat(), "pull_requests": _prs(row)}
+                            for row in repo_rows if row.get("repo_name") == repo and (row.get("repo_owner_name") or owner) == owner]
+            store.add(records, now.date().isoformat())
+            # Settled: it has a report, a later day does, or it ended long enough ago; else the next run asks again.
+            if org_rows or day < now.date() - timedelta(days=SETTLED):
+                last = day.isoformat()
+            day += timedelta(days=1)
+        if newest and newest.isoformat() > (last or ""):
+            last = newest.isoformat()
+        store.save_state({"through": last} if last else {})
+        return {"read": read, "incidents": 0, "complete": day > latest}
+    finally:
+        if own:
+            client.close()

stackvitals/connectors/discord.py

@@ -0,0 +1,103 @@
+"""Discord: support text channels read with a bot token the user installs (View Channel and Read Message History; message
+content isn't needed): each message that isn't a reply, when anyone first replied to it and when the team did (the user
+ids under `team`). The first pull reads 180 days, later ones the last 30; what was read is kept even when a later call
+fails, and a channel the bot can't read (a forum channel, say) is said while the others go on. Only times and flags are
+kept: no text and no user ids."""
+import time
+from datetime import datetime, timedelta
+
+import httpx
+
+from stackvitals.connectors.base import BACKFILL_DAYS, PAGES, ConnectorError, json_of, utc
+from stackvitals.core import identity
+
+NAME, TOKEN_ENV = "discord", "STACKVITALS_DISCORD_TOKEN"
+API = "https://discord.com/api/v10"
+RECENT_DAYS = 30
+MAX_WAIT = 60
+
+__all__ = ["ConnectorError", "configured", "pull"]
+
+
+def configured(env: dict, cfg: dict) -> bool:
+    return bool((env.get(TOKEN_ENV) or "").strip())
+
+
+def _messages(client: httpx.Client, key: str, channel: str, before: str | None, sleep) -> list[dict]:
+    for attempt in (1, 2):
+        try:
+            resp = client.get(f"{API}/channels/{channel}/messages", params={"limit": 100, **({"before": before} if before else {})},
+                              headers={"Authorization": f"Bot {key}"})
+        except httpx.HTTPError as exc:
+            raise ConnectorError(f"Discord could not be reached ({type(exc).__name__}); the next run tries again.") from None
+        if resp.status_code == 429:
+            wait = float(resp.headers.get("retry-after", MAX_WAIT))
+            if attempt == 1 and wait <= MAX_WAIT:
+                sleep(wait)
+                continue
+            raise ConnectorError("Discord's rate limit was reached; what was read is kept and the next run carries on.")
+        if resp.status_code in (401, 403):
+            raise ConnectorError(f"Discord refused the bot ({resp.status_code}): it needs View Channel and Read Message History "
+                                 f"in channel {channel}.")
+        if resp.status_code != 200:
+            raise ConnectorError(f"Discord answered {resp.status_code} for channel {channel} (a forum channel isn't read).")
+        return json_of(resp, "Discord", (list,))
+    raise ConnectorError("Discord's rate limit was reached; the next run carries on.")
+
+
+def _topics(msgs: list[dict], channel: str, team: set, since: str) -> list[dict]:
+    replies = {}
+    for m in sorted(msgs, key=lambda m: m["timestamp"]):
+        ref = (m.get("message_reference") or {}).get("message_id")
+        if ref:
+            replies.setdefault(ref, []).append(m)
+    out = []
+    for m in msgs:
+        created = utc(m.get("timestamp"))
+        if (m.get("message_reference") or {}).get("message_id") or not created or created < since:
+            continue
+        author = (m.get("author") or {}).get("id")
+        theirs = [r for r in replies.get(m["id"], []) if (r.get("author") or {}).get("id") != author]
+        ours = next((r for r in theirs if (r.get("author") or {}).get("id") in team), None)
+        out.append({"t": "topic", "src": NAME, "id": f"{NAME}:{channel}:{m['id']}", "created": created,
+                    "by_team": author in team, "first_reply": utc(theirs[0]["timestamp"]) if theirs else None,
+                    "first_team_reply": utc(ours["timestamp"]) if ours else None, "solved": None, "closed": False})
+    return out
+
+
+def pull(store, env: dict, cfg: dict, now: datetime, client: httpx.Client | None = None, pages: int = PAGES,
+         sleep=time.sleep) -> dict:
+    c = cfg["connectors"][NAME]
+    # Team members are the ids listed here, plus those [identity] aliases map to a team member.
+    key, team = env.get(TOKEN_ENV, "").strip(), set(c["team"]) | identity.tool_ids(cfg.get("identity"), NAME)
+    days = RECENT_DAYS if store.state().get("backfilled") else BACKFILL_DAYS
+    since = utc((now - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ"))
+    own = client is None
+    client = client or httpx.Client(timeout=30)
+    fresh, complete, failed = [], True, []
+    try:
+        for channel in c["channels"]:
+            msgs, before = [], None
+            try:
+                for _ in range(pages):
+                    batch = _messages(client, key, channel, before, sleep)
+                    msgs += [m for m in batch if not (m.get("author") or {}).get("bot")]
+                    if not batch or (utc(batch[-1].get("timestamp")) or "") < since:
+                        break
+                    before = batch[-1]["id"]
+                else:
+                    complete = False
+            except ConnectorError as exc:
+                failed.append(f"{channel}: {exc}")
+                complete = False
+            # What a channel gave before it failed still counts.
+            fresh += _topics(msgs, channel, team, since)
+    finally:
+        if own:
+            client.close()
+        store.add(fresh, now.date().isoformat())
+    if len(failed) == len(c["channels"]) and failed:
+        raise ConnectorError(failed[0])
+    if complete:
+        store.save_state({**store.state(), "backfilled": True})
+    return {"read": len(fresh), "complete": complete, **({"note": "; ".join(failed[:2])} if failed else {})}

stackvitals/connectors/discourse.py

@@ -0,0 +1,117 @@
+"""Discourse: a project's forum, read from its public JSON (no key): each topic of the last 180 days, when anyone first
+replied, when the team first did (forum staff, the usernames under `team`, or members of the `groups`), and whether it
+was solved. Only times and flags are kept: no usernames, titles or post text."""
+import time
+from datetime import datetime, timedelta
+
+import httpx
+
+from stackvitals.connectors.base import BACKFILL_DAYS, ConnectorError, json_of, utc
+from stackvitals.core import stats
+
+NAME = "discourse"
+LIST_PAGES, TOPICS = 10, 120  # a run reads at most 10 list pages and 120 topics; the next run carries on
+PAUSE, MAX_WAIT = 0.25, 60
+
+__all__ = ["ConnectorError", "configured", "pull", "answers"]
+
+
+def configured(env: dict, cfg: dict) -> bool:
+    return bool(((cfg.get("connectors") or {}).get(NAME) or {}).get("url"))
+
+
+def _get(client: httpx.Client, path: str, sleep=time.sleep, **params) -> dict:
+    for attempt in (1, 2):
+        sleep(PAUSE)  # a public forum, read politely: well under Discourse's anonymous limit
+        try:
+            resp = client.get(path, params=params, headers={"Accept": "application/json"})
+        except httpx.HTTPError as exc:
+            raise ConnectorError(f"The forum could not be reached ({type(exc).__name__}); the next run tries again.") from None
+        if resp.status_code != 429:
+            break
+        wait = float(resp.headers.get("retry-after", MAX_WAIT))
+        if attempt == 2 or wait > MAX_WAIT:
+            raise ConnectorError("The forum's rate limit was reached; what was read is kept and the next run carries on.")
+        sleep(wait)
+    if resp.status_code != 200:
+        raise ConnectorError(f"The forum answered {resp.status_code} for {path}; check url under [connectors.discourse].")
+    return json_of(resp, "The forum")
+
+
+def _record(topic: dict, posts: list[dict], team: set[str], groups: set[str]) -> dict:
+    def ours(p):
+        return bool(p.get("staff")) or (p.get("username") or "").lower() in team or (p.get("primary_group_name") or "").lower() in groups
+    # Only people's regular posts are replies: moderator notes ("closed", "moved") and the system account's aren't.
+    posts = [p for p in posts if p.get("post_type", 1) == 1 and p.get("username") != "system"]
+    first, replies = posts[0] if posts else {}, posts[1:]
+    reply = next((p for p in replies if p.get("username") != first.get("username")), None)
+    team_reply = next((p for p in replies if ours(p) and p.get("username") != first.get("username")), None)
+    return {"t": "topic", "src": NAME, "id": f"{NAME}:{topic['id']}", "created": utc(topic.get("created_at")),
+            "updated": utc(topic.get("last_posted_at") or topic.get("created_at")), "by_team": ours(first),
+            "first_reply": utc((reply or {}).get("created_at")), "first_team_reply": utc((team_reply or {}).get("created_at")),
+            "solved": bool(topic.get("has_accepted_answer")), "closed": bool(topic.get("closed"))}
+
+
+def pull(store, env: dict, cfg: dict, now: datetime, client: httpx.Client | None = None, pages: int = LIST_PAGES,
+         sleep=time.sleep) -> dict:
+    c = cfg["connectors"][NAME]
+    team, groups = {x.lower() for x in c["team"]}, {x.lower() for x in c["groups"]}
+    since = utc((now - timedelta(days=BACKFILL_DAYS)).strftime("%Y-%m-%dT%H:%M:%SZ"))
+    known = {r["id"]: r for r in store.load().get("topic") or []}
+    own = client is None
+    client = client or httpx.Client(base_url=c["url"].rstrip("/"), timeout=30, follow_redirects=False)
+    read, complete, fresh = 0, True, []
+    try:
+        for page in range(pages):
+            listing = (_get(client, "/latest.json", sleep, order="created", page=page).get("topic_list") or {})
+            topics = listing.get("topics") or []
+            old = False
+            for t in topics:
+                created = utc(t.get("created_at"))
+                if not created or created < since:
+                    old = True
+                    continue
+                stored = known.get(f"{NAME}:{t['id']}")
+                # A topic is read again only when it has new posts and is not settled yet.
+                if stored and stored["updated"] >= (utc(t.get("last_posted_at")) or "") or (stored and stored["first_team_reply"]):
+                    continue
+                if read >= TOPICS:
+                    complete = False
+                    break
+                posts = (_get(client, f"/t/{t['id']}.json", sleep).get("post_stream") or {}).get("posts") or []
+                fresh.append(_record(t, posts, team, groups))
+                read += 1
+            if old or not topics or not listing.get("more_topics_url") or not complete:
+                break
+        else:
+            complete = False
+    finally:
+        if own:
+            client.close()
+        store.add(fresh, now.date().isoformat())  # kept even when a later request failed
+    return {"read": read, "complete": complete}
+
+
+def answers(topics: list[dict], now: datetime, days: int = 90) -> dict | None:
+    """Topics opened by people outside the team in the last `days`: how fast the team first replied (topics still
+    waiting stay in the median), how often anyone replied first, and the share solved."""
+    since = (now - timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
+    mine = [t for t in topics if not t.get("by_team") and (t.get("created") or "") >= since]
+    if not mine:
+        return None
+
+    def hours(a, b):
+        return (datetime.fromisoformat(b.replace("Z", "+00:00")) - datetime.fromisoformat(a.replace("Z", "+00:00"))).total_seconds() / 3600
+    end = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+    # A topic closed without a team reply stops the clock at its last post; only open ones are still waiting.
+    km = stats.km_median([hours(t["created"], t["first_team_reply"] or (t.get("updated") if t.get("closed") else None) or end)
+                          for t in mine], [bool(t["first_team_reply"]) for t in mine])
+    waits = sorted(hours(t["created"], t["first_team_reply"]) for t in mine if t["first_team_reply"])
+    mid = len(waits) // 2
+    median = (waits[mid] if len(waits) % 2 else (waits[mid - 1] + waits[mid]) / 2) if waits else None
+    return {"days": days, "topics": len(mine), "km": km, "median_hours": round(median, 2) if median is not None else None,
+            "team_answered": round(len(waits) / len(mine), 4),
+            "anyone_answered": round(sum(1 for t in mine if t["first_reply"]) / len(mine), 4),
+            # Chat has no solved mark: None there, not zero.
+            "solved_share": round(sum(1 for t in mine if t["solved"]) / len(mine), 4)
+            if any(t.get("solved") is not None for t in mine) else None}

stackvitals/connectors/incident_io.py

@@ -0,0 +1,106 @@
+"""incident.io: real incidents (declined, canceled and merged ones are kept as not-incidents), read with an API key (v2 List
+incidents), resuming from the newest update read; the resolve time is the incident's "Resolved at" timestamp."""
+from datetime import datetime, timedelta
+
+import httpx
+
+from stackvitals.connectors.base import (
+    BACKFILL_DAYS,
+    PAGES,
+    ConnectorError,
+    json_of,
+    utc,
+)
+from stackvitals.core.time import iso, parse
+
+NAME, TOKEN_ENV = "incident_io", "STACKVITALS_INCIDENT_IO_TOKEN"
+URL = "https://api.incident.io/v2/incidents"
+PAGE = 250
+OVERLAP = timedelta(hours=1)
+CATEGORY = {"triage": "TODO", "live": "IN_PROGRESS", "paused": "IN_PROGRESS", "learning": "DONE", "closed": "DONE"}
+NOT_INCIDENTS = {"declined", "canceled", "merged"}
+NOT_REAL = {"test", "tutorial"}
+
+__all__ = ["ConnectorError", "configured", "pull"]
+
+
+def configured(env: dict, cfg: dict) -> bool:
+    return bool((env.get(TOKEN_ENV) or "").strip())
+
+
+def scope(cfg: dict) -> str | None:
+    """Said on the Integrations page while every incident type counts for this repo."""
+    if not cfg["connectors"]["incident_io"]["incident_types"]:
+        return ("counts every incident type; list this repo's under incident_types in [connectors.incident_io] to count "
+                "only those")
+    return None
+
+
+def _get(client: httpx.Client, key: str, params: dict) -> dict:
+    try:
+        resp = client.get(URL, params=params, headers={"Authorization": f"Bearer {key}", "Accept": "application/json"})
+    except httpx.HTTPError as exc:
+        raise ConnectorError(f"incident.io could not be reached ({type(exc).__name__}); the next run tries again.") from None
+    if resp.status_code in (401, 403):
+        raise ConnectorError(f"incident.io refused the key ({resp.status_code}): check the INCIDENT_IO_API_KEY secret.")
+    if resp.status_code == 429:
+        raise ConnectorError("incident.io's limit for listing incidents (60 a minute) was reached; the next run carries on.")
+    if resp.status_code in (400, 404, 422) and "after" in params:
+        return None  # the saved place in a pass is no longer known
+    if resp.status_code != 200:
+        raise ConnectorError(f"incident.io answered {resp.status_code}; the next run tries again.")
+    return json_of(resp, "incident.io")
+
+
+def _resolved(i: dict) -> str | None:
+    for stamp in i.get("incident_timestamp_values") or []:
+        if ((stamp.get("incident_timestamp") or {}).get("name") or "").lower() == "resolved at":
+            return utc((stamp.get("value") or {}).get("value"))
+    return None
+
+
+def _record(i: dict, types: set[str]) -> dict:
+    category = (i.get("incident_status") or {}).get("category")
+    cat = CATEGORY.get(category, "TODO")
+    return {"t": "issue", "src": NAME, "id": f"incident_io:{i['id']}", "key": i.get("reference"), "title": i.get("name"),
+            "type": "INCIDENT", "original_type": None, "status": (i.get("incident_status") or {}).get("name"), "cat": cat,
+            "created": utc(i.get("created_at")), "updated": utc(i.get("updated_at")), "resolved": _resolved(i) if cat == "DONE" else None,
+            "points": None, "priority": (i.get("severity") or {}).get("name"),
+            "labels": [x for x in ((i.get("severity") or {}).get("name"),) if x], "sprints": [], "incident": True,
+            "canceled": False, "url": i.get("permalink"),
+            # One declined or merged after it was read stays stored, but no longer as an incident; so do test runs and
+            # (when incident_types is set) other teams' types.
+            **({"incident": False, "canceled": True} if category in NOT_INCIDENTS or i.get("mode") in NOT_REAL
+               or types and ((i.get("incident_type") or {}).get("name") or "").lower() not in types else {})}
+
+
+def pull(store, env: dict, cfg: dict, now: datetime, client: httpx.Client | None = None, pages: int = PAGES) -> dict:
+    key = env.get(TOKEN_ENV, "").strip()
+    own = client is None
+    client = client or httpx.Client(timeout=30)
+    try:
+        types = {t.lower() for t in cfg["connectors"]["incident_io"]["incident_types"]}
+        state = store.state()
+        since = state.get("since") or iso(now - timedelta(days=BACKFILL_DAYS))
+        params = {"page_size": PAGE, "updated_at[gte]": iso(parse(since) - OVERLAP), "sort_by": "created_at_oldest_first"}
+        # Sorted by creation, not update, so a capped pass keeps its place and only a finished one moves `since` on.
+        after, newest = state.get("after"), state.get("newest") or since
+        read, complete, day = 0, False, now.date().isoformat()
+        for _ in range(pages):
+            body = _get(client, key, {**params, **({"after": after} if after else {})})
+            if body is None:
+                after, newest = None, since
+                continue
+            found = body.get("incidents") or []
+            store.add([_record(i, types) for i in found], day)
+            read += len(found)
+            newest = max([newest, *(utc(i.get("updated_at")) or "" for i in found)])
+            after = (body.get("pagination_meta") or {}).get("after")
+            if not after:
+                complete = True
+                break
+        store.save_state({"since": newest} if complete else {"since": since, **({"after": after, "newest": newest} if after else {})})
+        return {"read": read, "incidents": read, "complete": complete}
+    finally:
+        if own:
+            client.close()

stackvitals/connectors/jira.py

@@ -0,0 +1,210 @@
+"""Jira Cloud: issues in the scope query, their status and sprint changes, and their sprints, read with the account's email
+and an API token (REST v3 enhanced search), resuming from the newest update read last time."""
+import base64
+import re
+from datetime import datetime, timedelta
+
+import httpx
+
+from stackvitals.connectors.base import BACKFILL_DAYS, PAGES, ConnectorError, request, std_type, utc
+from stackvitals.core.time import iso, parse
+
+NAME, TOKEN_ENV, EMAIL_ENV = "jira", "STACKVITALS_JIRA_TOKEN", "STACKVITALS_JIRA_EMAIL"
+# What is asked for: 2 adds the assignee, so answers kept before it are read again, not rebuilt.
+ASKED = 2
+PAGE = 100
+# JQL reads dates in the account's own time zone, so each pull starts a day early; records seen twice just win again.
+OVERLAP = timedelta(days=1)
+SPRINT_FIELD = "com.pyxis.greenhopper.jira:gh-sprint"
+POINTS_FIELDS = {"com.pyxis.greenhopper.jira:jsw-story-points", "com.atlassian.jira.plugin.system.customfieldtypes:float"}
+CATEGORY = {"new": "TODO", "indeterminate": "IN_PROGRESS", "done": "DONE"}
+NOT_DONE = {"won't do", "won't fix", "duplicate", "cannot reproduce", "declined", "rejected"}
+
+__all__ = ["ConnectorError", "configured", "extract", "pull"]
+
+
+def configured(env: dict, cfg: dict) -> bool:
+    return bool((env.get(TOKEN_ENV) or "").strip())
+
+
+def _bad(resp) -> str | None:
+    if resp.status_code != 400:
+        return None
+    try:
+        said = "; ".join((resp.json() or {}).get("errorMessages") or [])[:200]
+    except (ValueError, AttributeError):
+        said = ""
+    return f"Jira could not run the query ({said or 'bad request'}): check scope_jql and incident_jql under [connectors.jira]."
+
+
+def _get(client: httpx.Client, path: str, params: dict | None, auth: str):
+    return request(client, "GET", path, "Jira", kinds=(dict, list), bad=_bad, params=params,
+                   refused="check the JIRA_EMAIL and JIRA_API_TOKEN secrets and that the token has not expired",
+                   headers={"Authorization": auth, "Accept": "application/json"})
+
+
+def _ids(text: str | None) -> list[str]:
+    return [f"jira:sprint:{x}" for x in re.findall(r"\d+", text or "")]
+
+
+def _epic(parent) -> dict:
+    # The epic an issue belongs to is its parent when that parent is an epic (a sub-task's parent is a story).
+    f = (parent or {}).get("fields") or {}
+    if not parent or "epic" not in ((f.get("issuetype") or {}).get("name") or "").lower():
+        return {}
+    return {"epic": parent.get("key"), "epic_title": f.get("summary")}
+
+
+def _text(value) -> str | None:
+    """A custom field's value as text: an option's value, a team's or user's name, or the first of a list."""
+    if isinstance(value, list):
+        value = value[0] if value else None
+    if isinstance(value, dict):
+        value = value.get("value") or value.get("name") or value.get("title") or value.get("displayName")
+    return str(value)[:100] if value not in (None, "") else None
+
+
+def field_id(fields: list[dict], wanted: str) -> str | None:
+    """The id of the field the settings name, by its id or its name (any case)."""
+    w = (wanted or "").strip().lower()
+    return next((f["id"] for f in fields if w and w in ((f.get("id") or "").lower(), (f.get("name") or "").lower())), None)
+
+
+def _records(raw: dict, site: str, sprint_f: str | None, points_f: str | None, incident: bool, extra: dict | None = None) -> list[dict]:
+    f = raw.get("fields") or {}
+    status = f.get("status") or {}
+    kind = (f.get("issuetype") or {}).get("name") or ""
+    sprints = [s for s in (f.get(sprint_f) or [] if sprint_f else []) if isinstance(s, dict) and s.get("id") is not None]
+    points = f.get(points_f) if points_f else None
+    iid = f"jira:{raw['id']}"
+    histories = (raw.get("changelog") or {}).get("histories") or []
+    cat = CATEGORY.get((status.get("statusCategory") or {}).get("key"), "TODO")
+    resolved = utc(f.get("resolutiondate"))
+    if not resolved and cat == "DONE":
+        # A workflow that never sets a resolution: done when it last moved into the status it is in.
+        resolved = max((utc(h.get("created")) or "" for h in histories for item in h.get("items") or []
+                        if (item.get("field") or "").lower() == "status" and item.get("toString") == status.get("name")),
+                       default=None) or None
+    out = [{"t": "issue", "src": NAME, "id": iid, "key": raw["key"], "title": f.get("summary"),
+            "type": std_type(kind), "original_type": kind, "status": status.get("name"),
+            "cat": cat, "created": utc(f.get("created")), "updated": utc(f.get("updated")), "resolved": resolved,
+            "points": points if isinstance(points, (int, float)) and not isinstance(points, bool) else None,
+            "priority": (f.get("priority") or {}).get("name"), "labels": [str(x) for x in f.get("labels") or []],
+            "sprints": [f"jira:sprint:{s['id']}" for s in sprints], "incident": False,
+            "canceled": ((f.get("resolution") or {}).get("name") or "").lower() in NOT_DONE,
+            "url": f"{site}/browse/{raw['key']}", **_epic(f.get("parent")),
+            # The fields the settings map (team_field, severity_field), as text.
+            **{k: v for k, fid in (extra or {}).items() if fid and (v := _text(f.get(fid)))},
+            # Who it is assigned to, for [identity] aliases to name the GitHub login; never kept on a public repo.
+            **({"assignee": f"jira:{f['assignee']['accountId']}", "assignee_email": f["assignee"].get("emailAddress"),
+                "assignee_name": f["assignee"].get("displayName")}
+               if (f.get("assignee") or {}).get("accountId") else {})}]
+    for h in histories:
+        for k, item in enumerate(h.get("items") or []):
+            field = (item.get("field") or "").lower()
+            if field == "status":
+                out.append({"t": "change", "src": NAME, "id": f"{iid}:{h.get('id')}:{k}", "issue": iid, "field": "status",
+                            "from": item.get("fromString"), "to": item.get("toString"), "at": utc(h.get("created"))})
+            elif field == "sprint":
+                out.append({"t": "change", "src": NAME, "id": f"{iid}:{h.get('id')}:{k}", "issue": iid, "field": "sprint",
+                            "from": _ids(item.get("from")), "to": _ids(item.get("to")), "at": utc(h.get("created"))})
+    if incident:
+        # Both queries write the issue alike; this mark makes it an incident at load while it is as new as the issue.
+        out.append({"t": "mark", "src": NAME, "id": f"{iid}:incident", "issue": iid, "updated": utc(f.get("updated"))})
+    for s in sprints:
+        out.append({"t": "sprint", "src": NAME, "id": f"jira:sprint:{s['id']}", "name": s.get("name"),
+                    "state": str(s.get("state") or "").upper(), "start": utc(s.get("startDate")),
+                    "end": utc(s.get("endDate")), "complete": utc(s.get("completeDate"))})
+    return out
+
+
+def finish(got: dict) -> dict:
+    """An issue is an incident while the incident query's mark is as new as the issue's latest update."""
+    marks = {m["issue"]: m.get("updated") or "" for m in got.get("mark") or []}
+    for i in got.get("issue") or []:
+        if i["id"] in marks and marks[i["id"]] >= (i.get("updated") or ""):
+            i["incident"], i["type"] = True, "INCIDENT"
+    return got
+
+
+def extract(kind: str, ctx: dict, body: dict) -> list[dict]:
+    """The records in one kept answer (a page of the scope or incident search)."""
+    return [r for raw in body.get("issues") or [] for r in _records(raw, ctx["site"], ctx["sprint_f"], ctx["points_f"], ctx["incident"], ctx.get("extra"))]
+
+
+def _search(client, store, jql: str, wanted: list[str], auth: str, site: str, sprint_f, points_f, incident: bool,
+            pages: int, day: str, extra: dict | None = None) -> tuple[int, str | None, str | None, bool]:
+    """(issues read, newest update in UTC, that update as Jira wrote it in the account's zone, finished)."""
+    read, newest, local, token = 0, None, None, None
+    for _ in range(pages):
+        body = _get(client, "/rest/api/3/search/jql", {"jql": jql, "fields": ",".join(wanted), "expand": "changelog",
+                                                        "maxResults": PAGE, **({"nextPageToken": token} if token else {})}, auth)
+        issues = body.get("issues") or []
+        ctx = {"site": site, "sprint_f": sprint_f, "points_f": points_f, "incident": incident, "extra": extra or {}}
+        store.keep("search", ctx, body, day)
+        store.add(extract("search", ctx, body), day)
+        read += len(issues)
+        for raw in issues:
+            stamp = (raw.get("fields") or {}).get("updated")
+            if (utc(stamp) or "") > (newest or ""):
+                newest, local = utc(stamp), stamp
+        token = body.get("nextPageToken")
+        if body.get("isLast") or not token:
+            return read, newest, local, True
+    return read, newest, local, False
+
+
+def _minute(text: str, add: int = 0) -> str:
+    return f"{datetime.strptime(text, '%Y/%m/%d %H:%M') + timedelta(minutes=add):%Y/%m/%d %H:%M}"
+
+
+def pull(store, env: dict, cfg: dict, now: datetime, client: httpx.Client | None = None, pages: int = PAGES) -> dict:
+    c = cfg["connectors"]["jira"]
+    if not c["url"]:
+        raise ConnectorError("Set url under [connectors.jira] in .github/stackvitals.toml to your Jira Cloud site "
+                             "(https://<name>.atlassian.net).")
+    email = (env.get(EMAIL_ENV) or "").strip() or c["email"]
+    if not email:
+        raise ConnectorError("Jira needs the account's email: the JIRA_EMAIL secret, or email under [connectors.jira].")
+    auth = "Basic " + base64.b64encode(f"{email}:{env.get(TOKEN_ENV, '').strip()}".encode()).decode()
+    own = client is None
+    client = client or httpx.Client(base_url=c["url"], timeout=30, follow_redirects=False)
+    try:
+        fields = _get(client, "/rest/api/3/field", None, auth)
+        custom = lambda f: (f.get("schema") or {}).get("custom")  # noqa: E731
+        sprint_f = next((f["id"] for f in fields if custom(f) == SPRINT_FIELD), None)
+        points_f = next((f["id"] for f in fields if custom(f) in POINTS_FIELDS
+                         and re.fullmatch(r"(?i)story points?( estimate)?", f.get("name") or "")), None)
+        extra = {k: field_id(fields, c.get(f"{k}_field") or "") for k in ("team", "severity")}
+        wanted = ["summary", "issuetype", "status", "created", "updated", "resolutiondate", "resolution", "priority", "labels", "parent",
+                  "assignee",
+                  *(x for x in (sprint_f, points_f, *extra.values()) if x)]
+        state, day = store.state(), now.date().isoformat()
+        new, got, notes = dict(state), {}, []
+        # Sleuth's way for teams with no pager tool: the issues the incident query finds are the incidents.
+        queries = [("", c["scope_jql"].strip(), False)]
+        if c["incident_jql"].strip():
+            queries.append(("incident_", c["incident_jql"].strip(), True))
+        for prefix, jql, incident in queries:
+            since = state.get(prefix + "since") or iso(now - timedelta(days=BACKFILL_DAYS))
+            # A capped pass carries on from the minute it reached, in the account's zone; a finished one reads a day again.
+            start = state.get(prefix + "resume") or f"{parse(since) - OVERLAP:%Y/%m/%d %H:%M}"
+            where = f'updated >= "{start}" ORDER BY updated ASC'
+            read, newest, local, done = _search(client, store, f"({jql}) AND {where}" if jql else where, wanted, auth, c["url"],
+                                                sprint_f, points_f, incident, pages, day, extra)
+            new[prefix + "since"] = max(since, newest or since)
+            new.pop(prefix + "resume", None)
+            if not done and local:
+                resume = f"{datetime.fromisoformat(local):%Y/%m/%d %H:%M}"
+                if resume <= start:
+                    resume = _minute(start, 1)
+                    notes.append(f"more issues changed in one minute ({start}) than one run reads ({PAGE * pages:,}); "
+                                 "the rest of that minute was skipped.")
+                new[prefix + "resume"] = resume
+            got[prefix] = (read, done)
+        store.save_state(new)
+        return {"read": got[""][0], "incidents": got.get("incident_", (0, True))[0], "complete": all(d for _r, d in got.values()),
+                **({"note": " ".join(notes)} if notes else {})}
+    finally:
+        if own:
+            client.close()