linear-events 0.1.0__tar.gz

linear_events-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.3
+Name: linear-events
+Version: 0.1.0
+Summary: Linear webhook dispatch: HMAC-SHA256 signature verification, replay protection, and .on() handler routing
+Requires-Dist: httpx>=0.28 ; extra == 'client'
+Requires-Dist: fastapi>=0.110 ; extra == 'fastapi'
+Requires-Python: >=3.11
+Provides-Extra: client
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# linear-events
+
+Linear webhook payload types, HMAC signature verification, replay protection,
+and event dispatch.
+
+```sh
+pip install linear-events
+# Optional FastAPI integration and agent activity client:
+pip install 'linear-events[fastapi,client]'
+```
+
+```python
+import os
+from linear_events import LinearDispatcher
+
+hooks = LinearDispatcher(signing_secret=os.environ["LINEAR_WEBHOOK_SECRET"])
+
+@hooks.on("Issue", action="create")
+async def on_issue(payload):
+    print(payload["data"])
+```
+
+The dispatcher verifies signatures and timestamps when a signing secret is
+configured. Mount `as_fastapi_router()` for FastAPI handling, or call `dispatch`
+with the raw request body, signature, and timestamp yourself. The base package
+has no runtime dependencies. `linear_events.client.LinearAgentClient` is
+available with the `client` extra.

linear_events-0.1.0/README.md

@@ -0,0 +1,27 @@
+# linear-events
+
+Linear webhook payload types, HMAC signature verification, replay protection,
+and event dispatch.
+
+```sh
+pip install linear-events
+# Optional FastAPI integration and agent activity client:
+pip install 'linear-events[fastapi,client]'
+```
+
+```python
+import os
+from linear_events import LinearDispatcher
+
+hooks = LinearDispatcher(signing_secret=os.environ["LINEAR_WEBHOOK_SECRET"])
+
+@hooks.on("Issue", action="create")
+async def on_issue(payload):
+    print(payload["data"])
+```
+
+The dispatcher verifies signatures and timestamps when a signing secret is
+configured. Mount `as_fastapi_router()` for FastAPI handling, or call `dispatch`
+with the raw request body, signature, and timestamp yourself. The base package
+has no runtime dependencies. `linear_events.client.LinearAgentClient` is
+available with the `client` extra.

linear_events-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "linear-events"
+version = "0.1.0"
+description = "Linear webhook dispatch: HMAC-SHA256 signature verification, replay protection, and .on() handler routing"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+client = ["httpx>=0.28"]
+
+[dependency-groups]
+dev = [
+    "fastapi>=0.110",
+    "httpx>=0.28",
+    "pytest>=9.0",
+    "pytest-asyncio>=1.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

linear_events-0.1.0/src/linear_events/__init__.py

@@ -0,0 +1,39 @@
+"""linear_events: Linear webhook signature verification and .on() dispatch.
+
+Core (no dependencies): LinearDispatcher (verify + route by (type, action))
+and the payload TypedDicts, including the AgentSessionEvent model.
+linear-events[fastapi] adds a mountable endpoint via .as_fastapi_router();
+linear-events[client] adds LinearAgentClient for emitting agent activities.
+"""
+
+from linear_events.dispatch import (
+    LinearDispatcher,
+    LinearError,
+    SignatureVerificationError,
+)
+from linear_events.payloads import (
+    Actor,
+    AgentActivityWebhookPayload,
+    AgentSessionEventWebhookPayload,
+    AgentSessionWebhookPayload,
+    CommentChildWebhookPayload,
+    GuidanceRuleWebhookPayload,
+    IssueChildWebhookPayload,
+    UserChildWebhookPayload,
+    WebhookPayload,
+)
+
+__all__ = [
+    "Actor",
+    "AgentActivityWebhookPayload",
+    "AgentSessionEventWebhookPayload",
+    "AgentSessionWebhookPayload",
+    "CommentChildWebhookPayload",
+    "GuidanceRuleWebhookPayload",
+    "IssueChildWebhookPayload",
+    "LinearDispatcher",
+    "LinearError",
+    "SignatureVerificationError",
+    "UserChildWebhookPayload",
+    "WebhookPayload",
+]

linear_events-0.1.0/src/linear_events/client.py

@@ -0,0 +1,152 @@
+"""A minimal client for emitting Agent Activities (linear-events[client]).
+
+Agents answer an AgentSession by posting typed activities — thought, action,
+elicitation, response, error — which Linear renders in place and uses to
+track the session's lifecycle. The content constructors below build exactly
+the shapes Linear validates server-side.
+
+    client = LinearAgentClient(token)
+    await client.emit(session_id, thought("Looking into it…"))
+    await client.emit(session_id, action("Searching", "ENG-123"))
+    await client.emit(session_id, response("Done."))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import httpx
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "linear_events.client requires httpx — install linear-events[client]"
+    ) from e
+
+__all__ = [
+    "Activity",
+    "LinearAgentClient",
+    "LinearApiError",
+    "action",
+    "elicitation",
+    "error",
+    "response",
+    "thought",
+]
+
+Activity = dict[str, Any]  # the `content` of an agentActivityCreate
+
+
+def thought(body: str, *, ephemeral: bool = False) -> Activity:
+    """An internal note. Ephemeral thoughts are replaced by the next activity."""
+    return {"type": "thought", "body": body, "ephemeral": ephemeral}
+
+
+def elicitation(body: str) -> Activity:
+    """Ask the user for clarification or confirmation (session awaits input)."""
+    return {"type": "elicitation", "body": body}
+
+
+def action(name: str, parameter: str, result: str | None = None, *, ephemeral: bool = False) -> Activity:
+    """A tool invocation, without (running) or with (completed) a result."""
+    activity: Activity = {"type": "action", "action": name, "parameter": parameter, "ephemeral": ephemeral}
+    if result is not None:
+        activity["result"] = result
+    return activity
+
+
+def response(body: str) -> Activity:
+    """The final answer; marks the session's work complete. Markdown OK."""
+    return {"type": "response", "body": body}
+
+
+def error(body: str) -> Activity:
+    """Report a failure; puts the session in its error state. Markdown OK."""
+    return {"type": "error", "body": body}
+
+
+class LinearApiError(Exception):
+    """Linear answered a GraphQL call with an `errors` array."""
+
+
+AGENT_ACTIVITY_CREATE = """
+mutation AgentActivityCreate($input: AgentActivityCreateInput!) {
+  agentActivityCreate(input: $input) {
+    success
+    agentActivity { id }
+  }
+}
+"""
+
+
+class LinearAgentClient:
+    """Emits activities with an app-user OAuth token (Bearer). Pass an
+    existing httpx.AsyncClient as `http` to share one; otherwise each call
+    uses a short-lived client."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        api_base: str = "https://api.linear.app",
+        http: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._token = token
+        self._api_base = api_base.rstrip("/")
+        self._http = http
+
+    async def emit(self, agent_session_id: str, content: Activity, *, activity_id: str | None = None) -> dict[str, Any]:
+        """POST agentActivityCreate; returns the created activity's data."""
+        content = dict(content)
+        ephemeral = content.pop("ephemeral", None)
+        activity_input = {"agentSessionId": agent_session_id, "content": content}
+        if ephemeral is not None:
+            activity_input["ephemeral"] = ephemeral
+        if activity_id is not None:
+            activity_input["id"] = activity_id
+        try:
+            data = await self._graphql(AGENT_ACTIVITY_CREATE, {"input": activity_input})
+            result = data["agentActivityCreate"]
+            if not result.get("success") or not result.get("agentActivity"):
+                raise LinearApiError("Linear did not accept the activity")
+            return result["agentActivity"]
+        except (httpx.HTTPError, LinearApiError):
+            # An earlier attempt may have succeeded before its response was
+            # lost. Confirm the stable id instead of creating a second reply.
+            if activity_id is not None:
+                data = await self._graphql(
+                    "query MoActivity($id: String!) { agentActivity(id: $id) { id agentSession { id } } }",
+                    {"id": activity_id},
+                )
+                existing = data.get("agentActivity")
+                if existing and existing["agentSession"]["id"] == agent_session_id:
+                    return {"id": existing["id"]}
+            raise
+
+    async def link(self, agent_session_id: str, url: str, label: str) -> None:
+        """Add a dashboard link without replacing links contributed elsewhere."""
+        data = await self._graphql(
+            "mutation MoSessionLink($id: String!, $input: AgentSessionUpdateInput!) { agentSessionUpdate(id: $id, input: $input) { success } }",
+            {"id": agent_session_id, "input": {"addedExternalUrls": [{"url": url, "label": label}]}},
+        )
+        if not data["agentSessionUpdate"]["success"]:
+            raise LinearApiError("Linear did not accept the session link")
+
+    async def _graphql(self, query: str, variables: dict[str, Any]) -> Any:
+        async def call(http: httpx.AsyncClient) -> httpx.Response:
+            return await http.post(
+                f"{self._api_base}/graphql",
+                headers={"Authorization": f"Bearer {self._token}"},
+                json={"query": query, "variables": variables},
+                timeout=15,
+            )
+
+        if self._http is not None:
+            res = await call(self._http)
+        else:
+            async with httpx.AsyncClient() as http:
+                res = await call(http)
+        res.raise_for_status()
+        body = res.json()
+        if errors := body.get("errors"):
+            raise LinearApiError(errors[0].get("message", "unknown error"))
+        return body["data"]

linear_events-0.1.0/src/linear_events/dispatch.py

@@ -0,0 +1,157 @@
+"""Framework-free Linear webhook dispatch: verify, parse, route.
+
+Works with any HTTP framework (or none) — you bring the raw request body and
+the signature/timestamp headers, LinearDispatcher does the rest.
+linear_events.fastapi wraps this for FastAPI apps.
+
+Routing keys are (type, action) pairs read from the payload body:
+
+    @hook.on("Issue")                    -> every Issue action
+    @hook.on("Comment", action="create") -> only new comments
+    @hook.on_any                         -> (type, action, payload) for all
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import inspect
+import json
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+__all__ = ["LinearDispatcher", "LinearError", "SignatureVerificationError"]
+
+Handler = TypeVar("Handler", bound=Callable[..., Any])
+
+# Linear recommends rejecting deliveries older than a minute (replay window).
+REPLAY_TOLERANCE_MS = 60 * 1000
+
+
+class LinearError(Exception):
+    """Base class for dispatch failures."""
+
+
+class SignatureVerificationError(LinearError):
+    """Linear-Signature was missing/stale/mismatched."""
+
+
+class LinearDispatcher:
+    """Handler registry keyed by (type, action), with signature verification.
+
+    Handlers may be sync or async and receive the full payload; `payload["data"]`
+    holds the serialized entity. Verification is a no-op unless a signing
+    secret is configured.
+    """
+
+    def __init__(self, signing_secret: str | bytes | None = None) -> None:
+        if isinstance(signing_secret, str):
+            signing_secret = signing_secret.encode()
+        self._secret = signing_secret
+        self._handlers: dict[tuple[str, str | None], list[Callable[..., Any]]] = {}
+        self._any_handlers: list[Callable[..., Any]] = []
+
+    def on(
+        self, type: str, action: str | list[str] | None = None
+    ) -> Callable[[Handler], Handler]:
+        """Register a handler for one entity type, optionally narrowed to one
+        action or a list of actions (the handler fires for any of them)."""
+        actions: list[str | None]
+        if action is None:
+            actions = [None]
+        elif isinstance(action, str):
+            actions = [action]
+        else:
+            actions = list(dict.fromkeys(action))  # dedupe, keep order
+            if not actions:
+                raise ValueError("action list must not be empty")
+
+        def register(fn: Handler) -> Handler:
+            for a in actions:
+                self._handlers.setdefault((type, a), []).append(fn)
+            return fn
+
+        return register
+
+    def on_any(self, fn: Handler) -> Handler:
+        """Register a handler called with (type, action, payload) for every delivery."""
+        self._any_handlers.append(fn)
+        return fn
+
+    def verify_signature(self, body: bytes, signature: str | None) -> None:
+        """Linear-Signature is a plain hex HMAC-SHA256 over the raw body,
+        constant-time compared. No-op unless a signing secret is configured."""
+        if self._secret is None:
+            return
+        if not signature:
+            raise SignatureVerificationError("missing Linear-Signature header")
+        expected = hmac.new(self._secret, body, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected, signature):
+            raise SignatureVerificationError("Linear-Signature mismatch")
+
+    def _check_freshness(self, timestamp_ms: int | None) -> None:
+        """The 60-second replay window Linear recommends, from the
+        Linear-Timestamp header or the body's webhookTimestamp."""
+        if self._secret is None:
+            return
+        if timestamp_ms is None:
+            raise SignatureVerificationError(
+                "missing Linear-Timestamp header / webhookTimestamp field"
+            )
+        if abs(time.time() * 1000 - timestamp_ms) > REPLAY_TOLERANCE_MS:
+            raise SignatureVerificationError(
+                "stale Linear-Timestamp (replay protection)"
+            )
+
+    async def dispatch(
+        self,
+        body: bytes | str,
+        *,
+        timestamp: str | None = None,
+        signature: str | None = None,
+    ) -> dict[str, Any]:
+        """Verify, parse and route one delivery; returns the payload.
+
+        Raises SignatureVerificationError (a secret is configured and the
+        signature is missing/wrong or the timestamp is missing/stale),
+        json.JSONDecodeError (malformed body), LinearError (unusable payload).
+        """
+        raw = body.encode() if isinstance(body, str) else body
+        self.verify_signature(raw, signature)
+        payload = json.loads(raw)
+        if not isinstance(payload, dict) or "type" not in payload:
+            raise LinearError("malformed payload: expected a JSON object with a `type`")
+
+        timestamp_ms: int | None
+        if timestamp is not None:
+            try:
+                timestamp_ms = int(timestamp)
+            except ValueError:
+                raise SignatureVerificationError("malformed Linear-Timestamp header")
+        else:
+            timestamp_ms = payload.get("webhookTimestamp")
+            if not isinstance(timestamp_ms, int):
+                timestamp_ms = None
+        self._check_freshness(timestamp_ms)
+
+        event_type = payload["type"]
+        action = payload.get("action")
+        # dict.fromkeys dedupes (action-less events would otherwise route twice)
+        for key in dict.fromkeys(((event_type, action), (event_type, None))):
+            for fn in self._handlers.get(key, []):
+                if inspect.isawaitable(result := fn(payload)):
+                    await result
+        for fn in self._any_handlers:
+            if inspect.isawaitable(result := fn(event_type, action, payload)):
+                await result
+        return payload
+
+    def as_fastapi_router(self, *, path: str = "/") -> Any:
+        """Build a FastAPI APIRouter with a POST endpoint wired to this dispatcher.
+
+        Requires fastapi (linear-events[fastapi]). Returns fastapi.APIRouter.
+        """
+        from linear_events.fastapi import create_router
+
+        return create_router(self, path=path)

linear_events-0.1.0/src/linear_events/fastapi.py

@@ -0,0 +1,55 @@
+"""FastAPI integration: mount one endpoint that verifies and dispatches deliveries.
+
+    from fastapi import FastAPI
+    from linear_events import LinearDispatcher
+
+    hook = LinearDispatcher(signing_secret="...")
+    app = FastAPI()
+    app.include_router(hook.as_fastapi_router(path="/webhooks/linear"))
+
+Responses: 200 on success (handled or not — Linear retries anything non-200,
+so unknown types are acknowledged too), 400 for malformed payloads, 401 for
+bad signatures or stale timestamps.
+"""
+
+from __future__ import annotations
+
+import json
+
+try:
+    from fastapi import APIRouter, HTTPException, Request, Response
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "linear_events.fastapi requires fastapi — install linear-events[fastapi]"
+    ) from e
+
+from linear_events.dispatch import (
+    LinearDispatcher,
+    LinearError,
+    SignatureVerificationError,
+)
+
+__all__ = ["create_router"]
+
+
+def create_router(dispatcher: LinearDispatcher, *, path: str = "/") -> APIRouter:
+    """An APIRouter whose single POST endpoint feeds deliveries to `dispatcher`."""
+    router = APIRouter()
+
+    @router.post(path)
+    async def receive_linear_event(request: Request) -> Response:
+        try:
+            await dispatcher.dispatch(
+                await request.body(),
+                timestamp=request.headers.get("linear-timestamp"),
+                signature=request.headers.get("linear-signature"),
+            )
+        except SignatureVerificationError as e:
+            raise HTTPException(401, str(e)) from e
+        except json.JSONDecodeError as e:
+            raise HTTPException(400, f"invalid JSON body: {e}") from e
+        except LinearError as e:
+            raise HTTPException(400, str(e)) from e
+        return Response(status_code=200)
+
+    return router

linear_events-0.1.0/src/linear_events/payloads.py

@@ -0,0 +1,140 @@
+"""Hand-written TypedDicts for the Linear webhook envelope.
+
+The envelope's fields are stable and documented; `data` is the serialized
+entity (Issue, Comment, ...) and moves with Linear's GraphQL schema, so it
+stays a plain dict — handlers can rely on the envelope, not the entity.
+"""
+
+from typing import Any, TypedDict
+
+__all__ = [
+    "Actor",
+    "AgentActivityWebhookPayload",
+    "AgentSessionEventWebhookPayload",
+    "AgentSessionWebhookPayload",
+    "CommentChildWebhookPayload",
+    "GuidanceRuleWebhookPayload",
+    "IssueChildWebhookPayload",
+    "UserChildWebhookPayload",
+    "WebhookPayload",
+]
+
+
+class Actor(TypedDict, total=False):
+    """Who triggered the action. None when the triggering user or integration
+    has since been deleted."""
+
+    id: str
+    type: str  # "user" | "application" | "integration"
+    name: str
+    email: str
+    url: str
+
+
+class WebhookPayload(TypedDict, total=False):
+    """One Linear delivery. Data-change events (Issue, Comment, ...) carry
+    action/type/data; convenience streams (Issue SLA, OAuthApp revoked) add
+    their own fields on top."""
+
+    action: str  # "create" | "update" | "remove" for data-change events
+    type: str  # "Issue" | "Comment" | "Project" | ... (mirrors Linear-Event)
+    actor: Actor | None
+    createdAt: str  # ISO-8601
+    data: dict[str, Any]  # the serialized subject entity
+    url: str  # deep link to the subject entity
+    updatedFrom: dict[str, Any]  # update actions: previous values
+    organizationId: str
+    webhookId: str
+    webhookTimestamp: int  # ms; Linear recommends a 60s freshness window
+
+
+# ---------------------------------------------------------------------------
+# Agent session events (the Agent Interaction model): type is
+# "AgentSessionEvent", action "created" (mention/delegation — a new agent
+# loop should start) or "prompted" (a follow-up user message, in
+# agentActivity.content["body"]).
+
+
+class UserChildWebhookPayload(TypedDict, total=False):
+    id: str
+    name: str
+    displayName: str
+    email: str
+    url: str
+
+
+class IssueChildWebhookPayload(TypedDict, total=False):
+    id: str
+    identifier: str  # "ENG-123"
+    title: str
+    description: str
+    url: str
+    teamId: str
+
+
+class CommentChildWebhookPayload(TypedDict, total=False):
+    id: str
+    body: str
+    userId: str
+    issueId: str
+    url: str
+
+
+class GuidanceRuleWebhookPayload(TypedDict, total=False):
+    """Instructions configured at the workspace/team level (preferred repos,
+    task constraints); the nearest team-specific rule takes precedence."""
+
+    id: str
+    body: str
+    origin: str  # "workspace" | "parentTeam" | "team"
+
+
+class AgentSessionWebhookPayload(TypedDict, total=False):
+    id: str
+    status: str  # pending | active | awaitingInput | complete | error | stale
+    type: str
+    appUserId: str
+    organizationId: str
+    issueId: str | None
+    issue: IssueChildWebhookPayload | None
+    commentId: str | None
+    comment: CommentChildWebhookPayload | None
+    creatorId: str | None  # the responsible human (unset for automation)
+    creator: UserChildWebhookPayload | None
+    sourceCommentId: str | None
+    url: str | None
+    summary: str | None
+    startedAt: str | None
+    endedAt: str | None
+    createdAt: str
+    updatedAt: str
+
+
+class AgentActivityWebhookPayload(TypedDict, total=False):
+    id: str
+    agentSessionId: str
+    content: dict[str, Any]  # {"type": "prompt", "body": ...} for `prompted`
+    signal: str | None
+    signalMetadata: dict[str, Any] | None
+    sourceCommentId: str | None
+    userId: str
+    user: UserChildWebhookPayload
+    createdAt: str
+    updatedAt: str
+
+
+class AgentSessionEventWebhookPayload(TypedDict, total=False):
+    action: str  # "created" | "prompted"
+    type: str  # always "AgentSessionEvent"
+    agentSession: AgentSessionWebhookPayload
+    agentActivity: AgentActivityWebhookPayload | None  # set for `prompted`
+    appUserId: str
+    oauthClientId: str
+    organizationId: str
+    guidance: list[GuidanceRuleWebhookPayload] | None
+    previousComments: list[CommentChildWebhookPayload] | None
+    # Formatted context string (issue, comments, guidance); `created` only.
+    promptContext: str | None
+    webhookId: str
+    webhookTimestamp: int  # ms
+    createdAt: str