@sentry/junior-linear 0.162.0 → 0.164.0

package/README.md

@@ -21,6 +21,14 @@ This package does not require a shared `LINEAR_API_KEY` or a custom OAuth app fo
 
 Linear operations use Linear's hosted MCP tools directly. When an issue is created through that path, Junior links it to the current conversation.
 
+To run watches or event tasks when Linear issues are created:
+
+1. Set `LINEAR_WEBHOOK_SECRET` to the Linear webhook signing secret.
+2. Create a Linear webhook for the `Issue` resource at `https://<junior-host>/api/webhooks/linear`.
+3. Redeploy Junior.
+
+The plugin verifies the `Linear-Signature` header and publishes `issue.created` for the issue identifier and the team key. Team event tasks use the Linear team key, such as `SRE`.
+
 Optional: set channel defaults when a Slack thread usually routes work to the same Linear destination:
 
 ```bash

package/dist/index.js

@@ -2,11 +2,162 @@
 import {
   defineJuniorPlugin
 } from "@sentry/junior-plugin-api";
+import { z as z2 } from "zod";
+
+// src/resource-events/issue.ts
+var LINEAR_ISSUE_EVENTS = ["issue.created"];
+function linearIssueResource(input) {
+  const identifier = input.identifier.toUpperCase();
+  return {
+    identifier,
+    label: `Linear issue ${identifier}`,
+    namespace: "linear"
+  };
+}
+function linearTeamResource(input) {
+  const teamKey = input.teamKey.toUpperCase();
+  return {
+    identifier: teamKey,
+    label: `Linear team ${teamKey}`,
+    namespace: "linear"
+  };
+}
+
+// src/webhooks/handler.ts
+import { createHmac, timingSafeEqual } from "crypto";
+
+// src/webhooks/resource-events.ts
 import { z } from "zod";
-var saveIssueResultSchema = z.object({
-  issue: z.object({
+var issueWebhookSchema = z.object({
+  action: z.string(),
+  createdAt: z.string().optional(),
+  data: z.object({
+    assignee: z.object({ name: z.string().optional() }).passthrough().optional().nullable(),
+    description: z.string().optional().nullable(),
+    id: z.string().min(1),
     identifier: z.string().trim().min(1),
+    labels: z.array(z.object({ name: z.string().min(1) }).passthrough()).optional(),
+    priorityLabel: z.string().optional(),
+    project: z.object({ name: z.string().optional() }).passthrough().optional().nullable(),
+    state: z.object({ name: z.string().optional() }).passthrough().optional().nullable(),
+    team: z.object({ key: z.string().trim().min(1) }).passthrough().optional(),
+    teamKey: z.string().trim().min(1).optional(),
+    title: z.string().optional(),
     url: z.url()
+  }).passthrough(),
+  type: z.string(),
+  url: z.url().optional(),
+  webhookTimestamp: z.number().finite().optional()
+}).passthrough();
+function issueText(issue) {
+  const labels = issue.labels?.map((label) => label.name).join(", ");
+  const parts = [
+    issue.title ? `Title: ${issue.title}` : void 0,
+    issue.description ? `Description: ${issue.description}` : void 0,
+    issue.state?.name ? `State: ${issue.state.name}` : void 0,
+    issue.priorityLabel ? `Priority: ${issue.priorityLabel}` : void 0,
+    issue.project?.name ? `Project: ${issue.project.name}` : void 0,
+    labels ? `Labels: ${labels}` : void 0,
+    issue.assignee?.name ? `Assignee: ${issue.assignee.name}` : void 0,
+    `URL: ${issue.url}`
+  ].filter((part) => part !== void 0);
+  return parts.length > 0 ? parts.join("\n") : void 0;
+}
+function occurredAtMs(input) {
+  const createdAt = input.createdAt ? Date.parse(input.createdAt) : Number.NaN;
+  if (Number.isFinite(createdAt)) return createdAt;
+  if (Number.isFinite(input.webhookTimestamp)) return input.webhookTimestamp;
+  return Date.now();
+}
+function normalizeLinearResourceEvents(input) {
+  if (input.linearEvent.toLowerCase() !== "issue") return [];
+  const parsed = issueWebhookSchema.safeParse(input.body);
+  if (!parsed.success || parsed.data.action !== "create" || parsed.data.type.toLowerCase() !== "issue") {
+    return [];
+  }
+  const issue = parsed.data.data;
+  const teamKey = issue.team?.key ?? issue.teamKey;
+  if (!teamKey) return [];
+  const issueResource = linearIssueResource({ identifier: issue.identifier });
+  const teamResource = linearTeamResource({ teamKey });
+  const eventType = "issue.created";
+  const event = {
+    eventKey: `linear:${issue.id}:${eventType}`,
+    eventType,
+    occurredAtMs: occurredAtMs(parsed.data),
+    trustedSummary: `${issueResource.label} was created.`,
+    data: {
+      issueId: issue.id,
+      issueIdentifier: issueResource.identifier,
+      teamKey: teamResource.identifier,
+      url: issue.url
+    },
+    untrustedText: issueText(issue)
+  };
+  return [
+    { ...event, identifier: issueResource.identifier },
+    { ...event, identifier: teamResource.identifier }
+  ];
+}
+
+// src/webhooks/handler.ts
+function verifyLinearSignature(body, signature, secret) {
+  if (!secret || !/^[0-9a-f]{64}$/i.test(signature)) return false;
+  const actual = Buffer.from(signature.toLowerCase());
+  const expected = Buffer.from(
+    createHmac("sha256", secret).update(body).digest("hex")
+  );
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function createLinearWebhookRoute(args) {
+  return {
+    method: "POST",
+    path: "/api/webhooks/linear",
+    async handler(request) {
+      const rawBody = await request.text();
+      const signature = request.headers.get("linear-signature") ?? "";
+      if (!verifyLinearSignature(rawBody, signature, args.webhookSecret())) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+      const body = parseJson(rawBody);
+      if (body === void 0) {
+        return new Response("Malformed Linear webhook", { status: 400 });
+      }
+      const delivery = request.headers.get("linear-delivery")?.trim();
+      const linearEvent = request.headers.get("linear-event")?.trim();
+      if (!delivery || !linearEvent) {
+        return new Response("Malformed Linear webhook headers", {
+          status: 400
+        });
+      }
+      const events = normalizeLinearResourceEvents({ body, linearEvent });
+      for (const event of events) {
+        await args.resourceEvents.publish(event);
+      }
+      return new Response(events.length ? "Accepted" : "Ignored", {
+        status: 200
+      });
+    }
+  };
+}
+
+// src/webhooks/secret.ts
+function linearWebhookSecret() {
+  return process.env.LINEAR_WEBHOOK_SECRET?.trim() || void 0;
+}
+
+// src/plugin.ts
+var saveIssueResultSchema = z2.object({
+  issue: z2.object({
+    identifier: z2.string().trim().min(1),
+    url: z2.url()
   }).passthrough()
 }).passthrough();
 async function annotateCreatedIssue(ctx) {
@@ -35,10 +186,29 @@ async function annotateCreatedIssue(ctx) {
 function linearPlugin() {
   return defineJuniorPlugin({
     packageName: "@sentry/junior-linear",
+    resourceEvents: {
+      resourceTypes: [
+        {
+          type: "issue",
+          supportedEvents: [...LINEAR_ISSUE_EVENTS],
+          suggestedEvents: [...LINEAR_ISSUE_EVENTS]
+        },
+        {
+          type: "team",
+          supportedEvents: [...LINEAR_ISSUE_EVENTS],
+          suggestedEvents: [...LINEAR_ISSUE_EVENTS]
+        }
+      ],
+      isEnabled: () => Boolean(linearWebhookSecret()),
+      normalizeIdentifier: (identifier) => identifier.toUpperCase()
+    },
     manifest: {
       configKeys: ["team", "project"],
-      description: "Linear issue tracking via hosted MCP server",
+      description: "Linear issue tracking via hosted MCP server and issue webhooks",
       displayName: "Linear",
+      envVars: {
+        LINEAR_WEBHOOK_SECRET: {}
+      },
       mcp: {
         transport: "http",
         url: "https://mcp.linear.app/mcp"
@@ -46,7 +216,15 @@ function linearPlugin() {
       name: "linear"
     },
     hooks: {
-      afterMcpTool: annotateCreatedIssue
+      afterMcpTool: annotateCreatedIssue,
+      routes(ctx) {
+        return [
+          createLinearWebhookRoute({
+            resourceEvents: ctx.resourceEvents,
+            webhookSecret: linearWebhookSecret
+          })
+        ];
+      }
     }
   });
 }

package/dist/resource-events/issue.d.ts

@@ -0,0 +1,10 @@
+import type { SubscribableResource } from "@sentry/junior-plugin-api";
+export declare const LINEAR_ISSUE_EVENTS: readonly ["issue.created"];
+/** Build the stable Linear issue identity shared by tools and webhooks. */
+export declare function linearIssueResource(input: {
+    identifier: string;
+}): Pick<SubscribableResource, "identifier" | "label" | "namespace">;
+/** Build the stable Linear team identity used for team-scoped events. */
+export declare function linearTeamResource(input: {
+    teamKey: string;
+}): Pick<SubscribableResource, "identifier" | "label" | "namespace">;

package/dist/webhooks/handler.d.ts

@@ -0,0 +1,6 @@
+import type { PluginRoute, ResourceEventPublisher } from "@sentry/junior-plugin-api";
+/** Create the public, signed Linear resource-event webhook route. */
+export declare function createLinearWebhookRoute(args: {
+    resourceEvents: ResourceEventPublisher;
+    webhookSecret(): string | undefined;
+}): PluginRoute;

package/dist/webhooks/resource-events.d.ts

@@ -0,0 +1,6 @@
+import type { ResourceEventInput } from "@sentry/junior-plugin-api";
+/** Normalize one verified Linear webhook into issue- and team-scoped events. */
+export declare function normalizeLinearResourceEvents(input: {
+    body: unknown;
+    linearEvent: string;
+}): ResourceEventInput[];

package/dist/webhooks/secret.d.ts

@@ -0,0 +1,2 @@
+/** Read the secret used to verify Linear webhook deliveries. */
+export declare function linearWebhookSecret(): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-linear",
-  "version": "0.162.0",
+  "version": "0.164.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -23,17 +23,19 @@
   ],
   "dependencies": {
     "zod": "^4.4.3",
-    "@sentry/junior-plugin-api": "0.162.0"
+    "@sentry/junior-plugin-api": "0.164.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
     "oxlint": "^1.66.0",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "lint": "oxlint --config ../junior/.oxlintrc.json --deny-warnings src tsup.config.ts",
+    "lint": "oxlint --config ../junior/.oxlintrc.json --deny-warnings src tests tsup.config.ts vitest.config.ts",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }