cortexdb-connectors 0.2.8__tar.gz → 0.2.9__tar.gz

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.8
+Version: 0.2.9
 Summary: Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API.
 Author-email: CortexDB Team <team@cortexdb.ai>
 License-Expression: Apache-2.0

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors/base.py

@@ -102,7 +102,7 @@ class VisibilityLevel(str, Enum):
 @dataclass(frozen=True)
 class Source:
     system: str
-    connector_version: str = "0.2.5"
+    connector_version: str = "0.2.9"
 
 
 @dataclass(frozen=True)
@@ -325,6 +325,17 @@ class CortexConnector(ABC):
 
         for key, value in replacements.items():
             tpl = tpl.replace("{" + key + "}", value or "")
+        # C6d: an unresolved placeholder used to pass through literally,
+        # producing a silently malformed scope (`.../issue:{entity.issue}`)
+        # that the server happily stores as a real path. Fail loudly instead —
+        # the sync loop records the error per event and holds the cursor.
+        leftover = re.findall(r"\{[^{}]+\}", tpl)
+        if leftover:
+            raise ValueError(
+                f"scope template resolved to {tpl!r} with unresolved "
+                f"placeholder(s) {', '.join(leftover)} — this episode does "
+                "not carry the referenced entity/field."
+            )
         return tpl
 
     def _envelope(self, episode: Episode) -> dict[str, Any]:

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors/cli.py

@@ -432,16 +432,41 @@ def _cmd_sync(args: argparse.Namespace) -> None:
 
 def _cmd_serve(args: argparse.Namespace) -> None:
     """Run the webhook receiver for real-time create/update/delete."""
-    from cortexdb_connectors.webhooks import WebhookServer, build_handlers
+    # C3: this used to import a `build_handlers` that never existed —
+    # `cortexdb-sync serve` ImportError'd on startup, killing every
+    # connector's webhook mode. WebhookServer wires its own handlers from
+    # env secrets; the CLI only supplies CortexDB creds + bind address.
+    import uvicorn
+
+    from cortexdb_connectors.webhooks import WebhookServer
 
     creds = _load_cortex_creds(args)
-    handlers = build_handlers(creds)
-    if not handlers:
+    secret_envs = [
+        "SLACK_SIGNING_SECRET",
+        "GITHUB_WEBHOOK_SECRET",
+        "JIRA_WEBHOOK_SECRET",
+        "FRESHDESK_WEBHOOK_SECRET",
+        "TLDV_WEBHOOK_SECRET",
+    ]
+    if not any(os.environ.get(v) for v in secret_envs):
         logger.warning(
-            "no webhook handlers configured — set per-source signing secrets "
-            "(e.g. SLACK_SIGNING_SECRET) so the receiver can verify deliveries."
+            "no webhook signing secrets configured — every delivery will be "
+            "rejected as unsigned. Set one or more of: %s",
+            ", ".join(secret_envs),
         )
-    WebhookServer(handlers, host=args.host, port=args.port).serve_forever()
+    server = WebhookServer(
+        cortexdb_url=creds["api_url"] or None,
+        cortexdb_api_key=creds["api_key"] or None,
+        scope=creds["scope_template"] or "user:default",
+        actor=creds["actor"] or None,
+    )
+    logger.info(
+        "webhook receiver listening on %s:%d (routes: /webhooks/{slack,github,"
+        "jira,freshdesk,tldv}/events, /health)",
+        args.host,
+        args.port,
+    )
+    uvicorn.run(server.build_app(), host=args.host, port=args.port, log_level="info")
 
 
 def _cmd_watch(args: argparse.Namespace) -> None:

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors/jira/__init__.py

@@ -8,6 +8,7 @@ them as CortexDB Episodes.  Uses the ``jira`` library for API access.
 from __future__ import annotations
 
 import logging
+import re
 from datetime import datetime, timezone
 from typing import Any
 
@@ -80,22 +81,41 @@ class JiraConnector(CortexConnector):
         """
         from jira import JIRA
 
+        # C6b: an empty key list would produce unbounded JQL, which Jira
+        # Cloud rejects with an unhandled 400 mid-sync. Fail up front with
+        # an actionable message instead.
+        if not self.project_keys:
+            raise ValueError(
+                "JiraConnector requires at least one project key "
+                "(project_keys=[...] / JIRA_PROJECT_KEYS) — Jira Cloud "
+                "rejects unbounded JQL queries."
+            )
+
         client = JIRA(
             server=self.jira_url,
             basic_auth=(self.jira_email, self.jira_api_token),
         )
 
-        jql_parts: list[str] = []
-        if self.project_keys:
-            keys_str = ", ".join(self.project_keys)
-            jql_parts.append(f"project in ({keys_str})")
+        # C6a: Jira Cloud answers /search/jql with an EMPTY result set (not
+        # 401) for bad/expired tokens, so without this pre-flight a broken
+        # credential looks identical to an empty project ("sync done
+        # fetched=0 errors=0"). myself() does require valid auth.
+        try:
+            client.myself()
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(
+                f"Jira authentication failed for {self.jira_email} at "
+                f"{self.jira_url} — check JIRA_EMAIL / JIRA_API_TOKEN: {exc}"
+            ) from exc
+
+        sprint_field, points_field = self._custom_field_ids(client)
+
+        keys_str = ", ".join(self.project_keys)
+        jql_parts: list[str] = [f"project in ({keys_str})"]
         if since:
             jql_date = since.strftime("%Y-%m-%d %H:%M")
             jql_parts.append(f'updated >= "{jql_date}"')
-
-        jql = " AND ".join(jql_parts) if jql_parts else "ORDER BY updated DESC"
-        if jql_parts:
-            jql += " ORDER BY updated DESC"
+        jql = " AND ".join(jql_parts) + " ORDER BY updated DESC"
 
         raw_events: list[RawEvent] = []
         start_at = 0
@@ -118,7 +138,7 @@ class JiraConnector(CortexConnector):
                 except (ValueError, TypeError):
                     updated_at = datetime.now(timezone.utc)
 
-                issue_data = self._serialize_issue(issue)
+                issue_data = self._serialize_issue(issue, sprint_field, points_field)
                 project_data = issue_data.get("project", {})
 
                 raw_events.append(
@@ -136,7 +156,12 @@ class JiraConnector(CortexConnector):
                     )
                 )
 
-            if start_at + _PAGE_SIZE >= results.total:
+            # C5: current Jira Cloud (enhanced /search/jql) reports
+            # `results.total` as the CURRENT PAGE's length (and maxResults as
+            # 0), so a total-based check exits after page 1 every time and
+            # projects >_PAGE_SIZE issues silently under-sync. A short page is
+            # the only trustworthy end-of-results signal.
+            if len(results) < _PAGE_SIZE:
                 break
             start_at += _PAGE_SIZE
 
@@ -184,7 +209,11 @@ class JiraConnector(CortexConnector):
             # Version-aware key: each updated state of the issue is its own
             # retained event (occurred_at = the issue's updated time), so the
             # full history is preserved (e.g. owner Alice → Bob, with when).
-            idempotency_key=f"{raw.external_id}:{raw.timestamp.isoformat()}",
+            # C4: source-namespaced and shaped exactly like the webhook
+            # handler's key (`jira:{key}:{updated.isoformat()}`) so the same
+            # issue state dedups across poll and webhook paths instead of
+            # double-storing (or 409ing a second scope's sync).
+            idempotency_key=f"jira:{raw.external_id}:{raw.timestamp.isoformat()}",
         )
 
     def map_permissions(self, raw: RawEvent) -> Visibility:
@@ -202,7 +231,61 @@ class JiraConnector(CortexConnector):
     # -- helpers -------------------------------------------------------------
 
     @staticmethod
-    def _serialize_issue(issue: Any) -> dict[str, Any]:
+    def _custom_field_ids(client: Any) -> tuple[str | None, str | None]:
+        """Resolve the instance's Sprint / Story-Points custom field ids.
+
+        C6c: sprint and story points live in per-instance ``customfield_*``
+        ids, so they must be looked up by NAME once per sync (one
+        ``client.fields()`` call). Returns ``(sprint_id, points_id)``; either
+        is None when the instance has no such field — serialization then
+        keeps the documented null.
+        """
+        sprint_field: str | None = None
+        points_field: str | None = None
+        try:
+            for f in client.fields():
+                name = (f.get("name") or "").strip().lower()
+                if name == "sprint" and sprint_field is None:
+                    sprint_field = f.get("id")
+                elif name in ("story points", "story point estimate") and (
+                    points_field is None
+                ):
+                    points_field = f.get("id")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "could not resolve Jira custom fields (sprint/story points "
+                "stay null): %s",
+                exc,
+            )
+        return sprint_field, points_field
+
+    @staticmethod
+    def _sprint_name(value: Any) -> str | None:
+        """Best-effort current-sprint name from a Sprint custom-field value.
+
+        The field is a list; entries are objects with ``.name`` on current
+        API versions, or legacy ``com.atlassian.greenhopper...[...,name=X,...]``
+        strings. The LAST entry is the most recent sprint.
+        """
+        if not value:
+            return None
+        entries = value if isinstance(value, list) else [value]
+        last = entries[-1]
+        name = getattr(last, "name", None)
+        if name:
+            return str(name)
+        if isinstance(last, str):
+            m = re.search(r"name=([^,\]]+)", last)
+            if m:
+                return m.group(1)
+        return None
+
+    @staticmethod
+    def _serialize_issue(
+        issue: Any,
+        sprint_field: str | None = None,
+        points_field: str | None = None,
+    ) -> dict[str, Any]:
         """Flatten a ``jira.Issue`` into a plain dict."""
         fields = issue.fields
         assignee = getattr(fields, "assignee", None)
@@ -247,8 +330,12 @@ class JiraConnector(CortexConnector):
             ],
             "created": getattr(fields, "created", ""),
             "updated": getattr(fields, "updated", ""),
-            "sprint": None,  # Populated from custom fields if available.
-            "story_points": None,
+            "sprint": JiraConnector._sprint_name(
+                getattr(fields, sprint_field, None) if sprint_field else None
+            ),
+            "story_points": (
+                getattr(fields, points_field, None) if points_field else None
+            ),
         }
 
     @staticmethod
@@ -268,6 +355,17 @@ class JiraConnector(CortexConnector):
         """Extract entity references from issue data."""
         entities: list[EntityRef] = []
 
+        # C6d: the webhook path emits an `issue` entity; the poll path must
+        # too, or an `{entity.issue}` scope template never resolves.
+        if data.get("key"):
+            entities.append(
+                EntityRef(
+                    entity_type="issue",
+                    entity_id=data["key"],
+                    display_name=data["key"],
+                )
+            )
+
         project = data.get("project", {})
         if project.get("key"):
             entities.append(

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors/webhooks.py

@@ -574,6 +574,29 @@ class _HmacWebhookHandler:
             payload = json.loads(body)
         except json.JSONDecodeError:
             return JSONResponse({"error": "invalid json"}, status_code=400)
+        # C2: a source-side hard delete must REMOVE data, not ingest another
+        # event. When the subclass recognizes a delete event it names the
+        # deleted entity and we redact it via /v1/forget instead of calling
+        # normalize (which can only produce an Episode to ingest).
+        try:
+            deleted_entity = self.deletion_entity(payload)
+        except Exception:
+            logger.exception("%s webhook delete-detection failed", self.provider)
+            return JSONResponse({"error": "processing failed"}, status_code=500)
+        if deleted_entity:
+            try:
+                await _forget_entity_v1(
+                    deleted_entity,
+                    self.cortexdb_url,
+                    self.cortexdb_api_key,
+                    self.actor,
+                    self.scope,
+                    source=self.provider,
+                )
+            except Exception:
+                logger.exception("%s webhook forget failed", self.provider)
+                return JSONResponse({"error": "forget failed"}, status_code=500)
+            return JSONResponse({"ok": True, "forgot": deleted_entity})
         try:
             episode = self.normalize(payload)
         except Exception:
@@ -593,6 +616,13 @@ class _HmacWebhookHandler:
     def normalize(self, payload: dict[str, Any]) -> Episode | None:  # pragma: no cover
         raise NotImplementedError
 
+    def deletion_entity(self, payload: dict[str, Any]) -> str | None:
+        """Return the deleted entity's id when *payload* is a hard-delete
+        event (→ the handler redacts it via ``/v1/forget`` instead of
+        ingesting), or None for everything else. Default: no delete
+        detection."""
+        return None
+
 
 def _parse_iso(value: Any) -> datetime:
     """Parse an ISO-8601 string (Z or offset) → aware datetime; fall back to now."""
@@ -609,6 +639,13 @@ class JiraWebhookHandler(_HmacWebhookHandler):
 
     provider = "jira"
 
+    def deletion_entity(self, payload: dict[str, Any]) -> str | None:
+        # C2: jira:issue_deleted → redact the issue (its key is what the
+        # ingested content/entities carry) instead of ingesting a new event.
+        if payload.get("webhookEvent") == "jira:issue_deleted":
+            return (payload.get("issue") or {}).get("key") or None
+        return None
+
     def normalize(self, payload: dict[str, Any]) -> Episode | None:
         issue = payload.get("issue") or {}
         fields = issue.get("fields") or {}
@@ -644,7 +681,13 @@ class JiraWebhookHandler(_HmacWebhookHandler):
                 "issuetype": issuetype,
                 "webhook_event": payload.get("webhookEvent", ""),
             },
-            idempotency_key=f"jira:{key}:{updated or 'na'}",
+            # C4: keyed as `jira:{key}:{updated.isoformat()}` — the SAME shape
+            # (and the same parsed-timestamp formatting) as the poll path, so
+            # one issue state dedups across webhook and poll instead of
+            # double-storing.
+            idempotency_key=(
+                f"jira:{key}:{_parse_iso(updated).isoformat() if updated else 'na'}"
+            ),
         )
 
 

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.8
+Version: 0.2.9
 Summary: Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API.
 Author-email: CortexDB Team <team@cortexdb.ai>
 License-Expression: Apache-2.0

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/cortexdb_connectors.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ tests/test_base.py
 tests/test_connector_coverage.py
 tests/test_github.py
 tests/test_ingest_e2e.py
+tests/test_jira_findings_0_2_9.py
 tests/test_slack.py
 tests/test_streaming_cursor.py
 tests/test_webhooks.py

{cortexdb_connectors-0.2.8 → cortexdb_connectors-0.2.9}/pyproject.toml

@@ -1,87 +1,87 @@
-[build-system]
-requires = ["setuptools>=68.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "cortexdb-connectors"
-version = "0.2.8"
-description = "Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API."
-readme = "README.md"
-requires-python = ">=3.10"
-license = "Apache-2.0"
-authors = [
-    {name = "CortexDB Team", email = "team@cortexdb.ai"},
-]
-keywords = ["ai", "memory", "connectors", "etl", "slack", "github", "jira", "cortexdb"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Database",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-]
-dependencies = [
-    "httpx>=0.27",
-    "pydantic>=2.0",
-    "croniter>=2.0",
-]
-
-[project.optional-dependencies]
-slack = ["slack-sdk>=3.0"]
-github = ["pygithub>=2.0"]
-pagerduty = ["pdpyras>=5.0"]
-jira = ["jira>=3.0"]
-confluence = ["atlassian-python-api>=3.0"]
-notion = ["notion-client>=2.0"]
-linear = []
-discord = ["aiohttp>=3.9"]
-teams = ["msal>=1.28"]
-google-workspace = ["google-api-python-client>=2.0", "google-auth>=2.0"]
-salesforce = ["simple-salesforce>=1.12"]
-hubspot = ["hubspot-api-client>=9.0"]
-zendesk = []
-intercom = []
-servicenow = []
-gitlab = ["python-gitlab>=4.0"]
-webhooks = [
-    "starlette>=0.37",
-    "uvicorn>=0.29",
-    "python-multipart>=0.0.9",
-]
-all = [
-    "slack-sdk>=3.0",
-    "pygithub>=2.0",
-    "pdpyras>=5.0",
-    "jira>=3.0",
-    "atlassian-python-api>=3.0",
-    "notion-client>=2.0",
-    "aiohttp>=3.9",
-    "msal>=1.28",
-    "google-api-python-client>=2.0",
-    "google-auth>=2.0",
-    "simple-salesforce>=1.12",
-    "hubspot-api-client>=9.0",
-    "python-gitlab>=4.0",
-    "PyYAML>=6.0",
-    "starlette>=0.37",
-    "uvicorn>=0.29",
-    "python-multipart>=0.0.9",
-]
-
-[project.scripts]
-cortexdb-sync = "cortexdb_connectors.cli:main"
-
-[project.urls]
-Homepage = "https://cortexdb.ai"
-Documentation = "https://cortexdb.ai/docs/connectors/slack"
-Repository = "https://github.com/cortexdb/cortexdb"
-Issues = "https://github.com/cortexdb/cortexdb/issues"
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["cortexdb_connectors*"]
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cortexdb-connectors"
+version = "0.2.9"
+description = "Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    {name = "CortexDB Team", email = "team@cortexdb.ai"},
+]
+keywords = ["ai", "memory", "connectors", "etl", "slack", "github", "jira", "cortexdb"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "croniter>=2.0",
+]
+
+[project.optional-dependencies]
+slack = ["slack-sdk>=3.0"]
+github = ["pygithub>=2.0"]
+pagerduty = ["pdpyras>=5.0"]
+jira = ["jira>=3.0"]
+confluence = ["atlassian-python-api>=3.0"]
+notion = ["notion-client>=2.0"]
+linear = []
+discord = ["aiohttp>=3.9"]
+teams = ["msal>=1.28"]
+google-workspace = ["google-api-python-client>=2.0", "google-auth>=2.0"]
+salesforce = ["simple-salesforce>=1.12"]
+hubspot = ["hubspot-api-client>=9.0"]
+zendesk = []
+intercom = []
+servicenow = []
+gitlab = ["python-gitlab>=4.0"]
+webhooks = [
+    "starlette>=0.37",
+    "uvicorn>=0.29",
+    "python-multipart>=0.0.9",
+]
+all = [
+    "slack-sdk>=3.0",
+    "pygithub>=2.0",
+    "pdpyras>=5.0",
+    "jira>=3.0",
+    "atlassian-python-api>=3.0",
+    "notion-client>=2.0",
+    "aiohttp>=3.9",
+    "msal>=1.28",
+    "google-api-python-client>=2.0",
+    "google-auth>=2.0",
+    "simple-salesforce>=1.12",
+    "hubspot-api-client>=9.0",
+    "python-gitlab>=4.0",
+    "PyYAML>=6.0",
+    "starlette>=0.37",
+    "uvicorn>=0.29",
+    "python-multipart>=0.0.9",
+]
+
+[project.scripts]
+cortexdb-sync = "cortexdb_connectors.cli:main"
+
+[project.urls]
+Homepage = "https://cortexdb.ai"
+Documentation = "https://cortexdb.ai/docs/connectors/slack"
+Repository = "https://github.com/cortexdb/cortexdb"
+Issues = "https://github.com/cortexdb/cortexdb/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["cortexdb_connectors*"]

cortexdb_connectors-0.2.9/tests/test_jira_findings_0_2_9.py

@@ -0,0 +1,341 @@
+"""Regression tests for the 0.2.8 Jira connector findings report (C2–C6).
+
+C5  pagination termination must not trust `results.total`
+C3  `cortexdb-sync serve` must not ImportError
+C2  jira:issue_deleted webhook → /v1/forget, not ingest
+C4  poll + webhook idempotency keys share one shape
+C6a bad-token auth pre-flight fails loudly
+C6b empty project_keys fails loudly
+C6c sprint / story_points populated from custom fields
+C6d poll path emits `issue` entity; unresolved scope placeholders raise
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import types
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from cortexdb_connectors.base import Episode, EpisodeType, RawEvent, Source
+from cortexdb_connectors.jira import JiraConnector
+from cortexdb_connectors.webhooks import JiraWebhookHandler, _parse_iso
+
+CORTEXDB_URL = "http://localhost:8080"
+
+
+# ---------------------------------------------------------------------------
+# Fake jira client machinery
+# ---------------------------------------------------------------------------
+
+
+class _FakeField:
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+
+class _FakeIssue:
+    def __init__(self, key: str, idx: int, **custom):
+        self.key = key
+        self.id = str(10000 + idx)
+        self.fields = _FakeField(
+            summary=f"Issue {key}",
+            description=f"Body of {key}",
+            status="To Do",
+            priority="Medium",
+            issuetype="Task",
+            project=_FakeField(key="CT", name="Cortex Test", projectTypeKey="software"),
+            labels=[],
+            components=[],
+            created="2026-07-20T10:00:00.000+0000",
+            updated=f"2026-07-20T10:{idx:02d}:00.000+0000",
+            assignee=None,
+            reporter=_FakeField(
+                displayName="Rep Orter",
+                emailAddress="rep@example.com",
+                accountId=f"712020:uuid-{idx}",
+            ),
+            **custom,
+        )
+
+
+class _FakePage(list):
+    """Mimics jira's ResultList: current Jira Cloud reports `total` as the
+    CURRENT PAGE length (the C5 trap), and maxResults as 0."""
+
+    def __init__(self, items):
+        super().__init__(items)
+        self.total = len(items)
+        self.maxResults = 0
+
+
+class _FakeJira:
+    def __init__(self, issues, fields=None, auth_ok=True):
+        self._issues = issues
+        self._fields = fields or []
+        self._auth_ok = auth_ok
+        self.search_calls = []
+
+    def myself(self):
+        if not self._auth_ok:
+            raise RuntimeError("401 Unauthorized")
+        return {"accountId": "712020:me"}
+
+    def fields(self):
+        return self._fields
+
+    def search_issues(self, jql, startAt=0, maxResults=50, **kw):
+        self.search_calls.append(startAt)
+        return _FakePage(self._issues[startAt : startAt + maxResults])
+
+
+def _connector(**kw) -> JiraConnector:
+    defaults = dict(
+        cortex_url=CORTEXDB_URL,
+        cortex_api_key="k",
+        jira_url="https://example.atlassian.net",
+        jira_email="me@example.com",
+        jira_api_token="t",
+        project_keys=["CT"],
+    )
+    defaults.update(kw)
+    return JiraConnector(**defaults)
+
+
+def _fetch(connector: JiraConnector, fake: _FakeJira):
+    """Run fetch_events with the fake jira client injected."""
+    fake_mod = types.SimpleNamespace(JIRA=lambda **kw: fake)
+    with patch.dict(sys.modules, {"jira": fake_mod}):
+        return asyncio.run(connector.fetch_events())
+
+
+# ---------------------------------------------------------------------------
+# C5 — pagination
+# ---------------------------------------------------------------------------
+
+
+class TestPagination:
+    def test_fetches_past_page_one_despite_lying_total(self, monkeypatch):
+        import cortexdb_connectors.jira as jira_mod
+
+        monkeypatch.setattr(jira_mod, "_PAGE_SIZE", 2)
+        issues = [_FakeIssue(f"CT-{i}", i) for i in range(5)]
+        fake = _FakeJira(issues)
+        events = _fetch(_connector(), fake)
+        assert len(events) == 5, "must page past `total`==page-length"
+        assert fake.search_calls == [0, 2, 4]
+
+    def test_exact_multiple_of_page_size_terminates(self, monkeypatch):
+        import cortexdb_connectors.jira as jira_mod
+
+        monkeypatch.setattr(jira_mod, "_PAGE_SIZE", 2)
+        issues = [_FakeIssue(f"CT-{i}", i) for i in range(4)]
+        fake = _FakeJira(issues)
+        events = _fetch(_connector(), fake)
+        assert len(events) == 4
+        # One trailing empty page is the price of not trusting `total`.
+        assert fake.search_calls == [0, 2, 4]
+
+
+# ---------------------------------------------------------------------------
+# C6a / C6b — loud failures
+# ---------------------------------------------------------------------------
+
+
+class TestLoudFailures:
+    def test_bad_token_raises(self):
+        fake = _FakeJira([], auth_ok=False)
+        with pytest.raises(RuntimeError, match="authentication failed"):
+            _fetch(_connector(), fake)
+
+    def test_empty_project_keys_raises(self):
+        fake = _FakeJira([])
+        with pytest.raises(ValueError, match="project key"):
+            _fetch(_connector(project_keys=[]), fake)
+
+
+# ---------------------------------------------------------------------------
+# C6c — sprint / story points
+# ---------------------------------------------------------------------------
+
+
+class TestCustomFields:
+    FIELDS = [
+        {"id": "customfield_10020", "name": "Sprint"},
+        {"id": "customfield_10016", "name": "Story point estimate"},
+    ]
+
+    def test_populated_from_custom_fields(self):
+        issue = _FakeIssue(
+            "CT-1",
+            1,
+            customfield_10020=[_FakeField(name="Sprint 7")],
+            customfield_10016=5.0,
+        )
+        fake = _FakeJira([issue], fields=self.FIELDS)
+        events = _fetch(_connector(), fake)
+        assert events[0].data["sprint"] == "Sprint 7"
+        assert events[0].data["story_points"] == 5.0
+
+    def test_greenhopper_string_sprint(self):
+        raw = (
+            "com.atlassian.greenhopper.service.sprint.Sprint@1f4[id=7,"
+            "rapidViewId=3,state=ACTIVE,name=Sprint 7,startDate=2026-07-01]"
+        )
+        issue = _FakeIssue("CT-2", 2, customfield_10020=[raw])
+        fake = _FakeJira([issue], fields=self.FIELDS)
+        events = _fetch(_connector(), fake)
+        assert events[0].data["sprint"] == "Sprint 7"
+
+    def test_absent_fields_stay_null(self):
+        issue = _FakeIssue("CT-3", 3)
+        fake = _FakeJira([issue], fields=[])
+        events = _fetch(_connector(), fake)
+        assert events[0].data["sprint"] is None
+        assert events[0].data["story_points"] is None
+
+
+# ---------------------------------------------------------------------------
+# C4 — idempotency key parity, C6d — issue entity
+# ---------------------------------------------------------------------------
+
+
+class TestKeyAndEntities:
+    UPDATED = "2026-07-20T10:01:00.000+0000"
+
+    def _poll_episode(self) -> Episode:
+        conn = _connector()
+        fake = _FakeJira([_FakeIssue("CT-1", 1)])
+        raw = _fetch(conn, fake)[0]
+        return conn.normalize(raw)
+
+    def test_poll_key_is_source_namespaced_and_matches_webhook(self):
+        poll = self._poll_episode()
+        handler = JiraWebhookHandler(
+            secret="s", cortexdb_url=CORTEXDB_URL, cortexdb_api_key="k"
+        )
+        webhook = handler.normalize(
+            {
+                "webhookEvent": "jira:issue_updated",
+                "issue": {
+                    "key": "CT-1",
+                    "fields": {
+                        "summary": "Issue CT-1",
+                        "description": "Body of CT-1",
+                        "updated": self.UPDATED,
+                        "reporter": {"accountId": "712020:uuid-1"},
+                    },
+                },
+            }
+        )
+        assert poll.idempotency_key.startswith("jira:CT-1:")
+        assert poll.idempotency_key == webhook.idempotency_key
+        assert len(poll.idempotency_key) <= 64
+
+    def test_poll_path_emits_issue_entity(self):
+        poll = self._poll_episode()
+        kinds = {(e.entity_type, e.entity_id) for e in poll.entities}
+        assert ("issue", "CT-1") in kinds
+
+    def test_issue_scope_template_resolves(self):
+        conn = _connector()
+        conn.scope_template = "org:acme/issue:{entity.issue}"
+        assert conn._resolve_scope(self._poll_episode()) == "org:acme/issue:CT-1"
+
+    def test_unresolved_placeholder_raises(self):
+        conn = _connector()
+        conn.scope_template = "org:acme/x:{entity.bogus}"
+        with pytest.raises(ValueError, match="unresolved"):
+            conn._resolve_scope(self._poll_episode())
+
+
+# ---------------------------------------------------------------------------
+# C2 — deletion wiring
+# ---------------------------------------------------------------------------
+
+
+class TestDeletion:
+    def _handler(self) -> JiraWebhookHandler:
+        return JiraWebhookHandler(
+            secret="s",
+            cortexdb_url=CORTEXDB_URL,
+            cortexdb_api_key="k",
+            actor="user:tester",
+        )
+
+    def test_issue_deleted_names_the_entity(self):
+        h = self._handler()
+        assert (
+            h.deletion_entity({"webhookEvent": "jira:issue_deleted", "issue": {"key": "CT-9"}})
+            == "CT-9"
+        )
+        assert h.deletion_entity({"webhookEvent": "jira:issue_updated", "issue": {"key": "CT-9"}}) is None
+
+    def test_handle_routes_delete_to_forget_not_ingest(self):
+        import hashlib
+        import hmac as hmac_mod
+        import json as json_mod
+
+        h = self._handler()
+        body = json_mod.dumps(
+            {"webhookEvent": "jira:issue_deleted", "issue": {"key": "CT-9"}}
+        ).encode()
+        sig = "sha256=" + hmac_mod.new(b"s", body, hashlib.sha256).hexdigest()
+
+        class _Req:
+            headers = {"X-Hub-Signature-256": sig}
+
+            async def body(self):
+                return body
+
+        with patch(
+            "cortexdb_connectors.webhooks._forget_entity_v1", new_callable=AsyncMock
+        ) as forget, patch(
+            "cortexdb_connectors.webhooks._ingest_episode_v1", new_callable=AsyncMock
+        ) as ingest:
+            resp = asyncio.run(h.handle(_Req()))
+        assert resp.status_code == 200
+        forget.assert_awaited_once()
+        assert forget.await_args.args[0] == "CT-9"
+        ingest.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# C3 — serve wiring
+# ---------------------------------------------------------------------------
+
+
+class TestServe:
+    def test_serve_imports_and_builds_app(self):
+        # The 0.2.8 crash was an ImportError at `from ... import build_handlers`.
+        from cortexdb_connectors import cli
+        from cortexdb_connectors.webhooks import WebhookServer
+
+        app = WebhookServer(
+            cortexdb_url=CORTEXDB_URL, cortexdb_api_key="k"
+        ).build_app()
+        paths = {r.path for r in app.routes}
+        assert "/webhooks/jira/events" in paths
+        assert callable(cli._cmd_serve)
+
+    def test_cmd_serve_runs_uvicorn(self):
+        import argparse
+
+        from cortexdb_connectors import cli
+
+        args = argparse.Namespace(
+            host="127.0.0.1",
+            port=0,
+            api_url=CORTEXDB_URL,
+            api_key="k",
+            actor="user:tester",
+            scope_template="user:tester",
+            config=None,
+        )
+        with patch("uvicorn.run") as run:
+            cli._cmd_serve(args)
+        run.assert_called_once()
+        assert run.call_args.kwargs["host"] == "127.0.0.1"