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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.7
+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.7 → cortexdb_connectors-0.2.9}/cortexdb_connectors/__init__.py

@@ -1,40 +1,40 @@
-"""cortexdb_connectors — data connector SDK for the CortexDB v1 API.
-
-Each connector subclass implements `fetch_events`, `normalize`, and
-`map_permissions`; the base class POSTs every normalised Episode to
-`/v1/experience` with the required Authorization + X-Cortex-Actor
-headers. Use the `cortexdb-sync` CLI to run a connector once or in a
-poll loop; or `from cortexdb_connectors.slack import SlackConnector`
-to drive it programmatically.
-"""
-
-__version__ = "0.2.7"
-
-from cortexdb_connectors.base import (
-    Actor,
-    CortexConnector,
-    EntityRef,
-    Episode,
-    EpisodeType,
-    RawEvent,
-    Source,
-    SyncResult,
-    SyncState,
-    Visibility,
-    VisibilityLevel,
-)
-
-__all__ = [
-    "__version__",
-    "Actor",
-    "CortexConnector",
-    "EntityRef",
-    "Episode",
-    "EpisodeType",
-    "RawEvent",
-    "Source",
-    "SyncResult",
-    "SyncState",
-    "Visibility",
-    "VisibilityLevel",
-]
+"""cortexdb_connectors — data connector SDK for the CortexDB v1 API.
+
+Each connector subclass implements `fetch_events`, `normalize`, and
+`map_permissions`; the base class POSTs every normalised Episode to
+`/v1/experience` with the required Authorization + X-Cortex-Actor
+headers. Use the `cortexdb-sync` CLI to run a connector once or in a
+poll loop; or `from cortexdb_connectors.slack import SlackConnector`
+to drive it programmatically.
+"""
+
+__version__ = "0.2.8"
+
+from cortexdb_connectors.base import (
+    Actor,
+    CortexConnector,
+    EntityRef,
+    Episode,
+    EpisodeType,
+    RawEvent,
+    Source,
+    SyncResult,
+    SyncState,
+    Visibility,
+    VisibilityLevel,
+)
+
+__all__ = [
+    "__version__",
+    "Actor",
+    "CortexConnector",
+    "EntityRef",
+    "Episode",
+    "EpisodeType",
+    "RawEvent",
+    "Source",
+    "SyncResult",
+    "SyncState",
+    "Visibility",
+    "VisibilityLevel",
+]

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

@@ -13,6 +13,7 @@ from __future__ import annotations
 import hashlib
 import logging
 import os
+import re
 import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -24,6 +25,11 @@ DEFAULT_API_URL = "https://api-v1.cortexdb.ai"
 
 logger = logging.getLogger("cortexdb_connectors")
 
+# v1 ActorRef grammar (server: cortex-types identity.rs): `kind:local` where
+# kind ∈ _ACTOR_KINDS and local matches [A-Za-z0-9_.@-]+ (no colons!).
+_ACTOR_KINDS = frozenset({"user", "agent", "service", "system"})
+_ACTOR_LOCAL_ILLEGAL = re.compile(r"[^A-Za-z0-9_.@-]")
+
 # Hard ceiling on content size sent to the server. Real items never approach
 # this; it exists only to stop a pathological payload from exceeding the request
 # body limit. When it trips we truncate on a UTF-8 boundary and log LOUDLY — we
@@ -96,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)
@@ -319,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]:
@@ -376,14 +393,17 @@ class CortexConnector(ABC):
             ),
         }
         if episode.actor and episode.actor.id:
-            # v1 ActorRef requires a `kind:id` form (the server rejects a bare
-            # id with 422: "actor id missing ':' delimiter"). Source actor ids
-            # (Slack "U123", Jira accountId, …) are bare, so default the kind to
-            # `user:` unless the connector already supplied a delimiter.
-            aid = episode.actor.id
-            if ":" not in aid:
-                aid = f"user:{aid}"
-            envelope["observed_actor"] = {"id": aid}
+            # Source actor ids are not guaranteed bare: Jira Cloud accountIds
+            # are `712020:<uuid>`, so a colon does NOT mean the connector
+            # already supplied a kind. Treat the prefix as a kind only when it
+            # is one the server accepts; otherwise the whole source id is the
+            # local part under `user:`, sanitized to the server's charset
+            # (which forbids ':' anywhere in the local part).
+            kind, sep, local = episode.actor.id.partition(":")
+            if not sep or kind not in _ACTOR_KINDS or not local:
+                kind, local = "user", episode.actor.id
+            local = _ACTOR_LOCAL_ILLEGAL.sub("_", local)
+            envelope["observed_actor"] = {"id": f"{kind}:{local}"}
 
         return envelope