@calltelemetry/openclaw-linear 0.8.2 → 0.8.3

package/src/api/linear-api.test.ts

@@ -232,6 +232,43 @@ describe("LinearAgentApi", () => {
       );
     });
 
+    it("returns data when GraphQL errors and data coexist (partial success)", async () => {
+      // Simulates createAsUser returning warnings alongside valid comment data.
+      // This is the root cause of Bug 2 in API-477: gql() used to throw on
+      // any errors, even when the mutation succeeded and data was present.
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({
+            data: {
+              commentCreate: { success: true, comment: { id: "c-partial" } },
+            },
+            errors: [{ message: "createAsUser: user not found, using default" }],
+          }),
+        text: () => Promise.resolve(""),
+        headers: new Headers(),
+      } as unknown as Response);
+
+      const api = new LinearAgentApi(TOKEN);
+      const id = await api.createComment("issue-1", "test body", {
+        createAsUser: "NonexistentUser",
+      });
+
+      expect(id).toBe("c-partial");
+    });
+
+    it("still throws on GraphQL errors when no data is present", async () => {
+      fetchMock.mockResolvedValueOnce(
+        gqlErrorResponse([{ message: "Totally broken" }]),
+      );
+
+      const api = new LinearAgentApi(TOKEN);
+      await expect(
+        api.createComment("issue-1", "test body"),
+      ).rejects.toThrow(/Linear GraphQL/);
+    });
+
     it("retries on 401 when refresh token is available", async () => {
       // First call (via withResilience): 401
       fetchMock.mockResolvedValueOnce(errorResponse(401, "Unauthorized"));

package/src/api/linear-api.ts

@@ -193,7 +193,7 @@ export class LinearAgentApi {
       }
 
       const payload = await retryRes.json();
-      if (payload.errors?.length) {
+      if (payload.errors?.length && !payload.data) {
         throw new Error(`Linear GraphQL: ${JSON.stringify(payload.errors)}`);
       }
       return payload.data as T;
@@ -205,7 +205,7 @@ export class LinearAgentApi {
     }
 
     const payload = await res.json();
-    if (payload.errors?.length) {
+    if (payload.errors?.length && !payload.data) {
       throw new Error(`Linear GraphQL: ${JSON.stringify(payload.errors)}`);
     }
 
@@ -306,7 +306,7 @@ export class LinearAgentApi {
     title: string;
     description: string | null;
     estimate: number | null;
-    state: { name: string };
+    state: { name: string; type: string };
     assignee: { name: string } | null;
     labels: { nodes: Array<{ id: string; name: string }> };
     team: { id: string; name: string; issueEstimationType: string };
@@ -323,7 +323,7 @@ export class LinearAgentApi {
           title
           description
           estimate
-          state { name }
+          state { name type }
           assignee { name }
           labels { nodes { id name } }
           team { id name issueEstimationType }
@@ -533,7 +533,7 @@ export class LinearAgentApi {
     }>(
       `query TeamStates($id: String!) {
         team(id: $id) {
-          states: workflowStates { nodes { id name type } }
+          states { nodes { id name type } }
         }
       }`,
       { id: teamId },
@@ -591,4 +591,95 @@ export class LinearAgentApi {
     );
     return data.notifications.nodes as any;
   }
+
+  // ---------------------------------------------------------------------------
+  // Webhook management
+  // ---------------------------------------------------------------------------
+
+  async listWebhooks(): Promise<Array<{
+    id: string;
+    label: string | null;
+    url: string;
+    enabled: boolean;
+    resourceTypes: string[];
+    allPublicTeams: boolean;
+    team: { id: string; name: string } | null;
+    createdAt: string;
+  }>> {
+    const data = await this.gql<{
+      webhooks: { nodes: unknown[] };
+    }>(
+      `query Webhooks {
+        webhooks {
+          nodes {
+            id
+            label
+            url
+            enabled
+            resourceTypes
+            allPublicTeams
+            team { id name }
+            createdAt
+          }
+        }
+      }`,
+    );
+    return data.webhooks.nodes as any;
+  }
+
+  async createWebhook(input: {
+    url: string;
+    resourceTypes: string[];
+    label?: string;
+    teamId?: string;
+    allPublicTeams?: boolean;
+    enabled?: boolean;
+    secret?: string;
+  }): Promise<{ id: string; enabled: boolean }> {
+    const data = await this.gql<{
+      webhookCreate: { success: boolean; webhook: { id: string; enabled: boolean } };
+    }>(
+      `mutation WebhookCreate($input: WebhookCreateInput!) {
+        webhookCreate(input: $input) {
+          success
+          webhook { id enabled }
+        }
+      }`,
+      { input },
+    );
+    return data.webhookCreate.webhook;
+  }
+
+  async updateWebhook(webhookId: string, input: {
+    url?: string;
+    resourceTypes?: string[];
+    label?: string;
+    enabled?: boolean;
+  }): Promise<boolean> {
+    const data = await this.gql<{
+      webhookUpdate: { success: boolean };
+    }>(
+      `mutation WebhookUpdate($id: String!, $input: WebhookUpdateInput!) {
+        webhookUpdate(id: $id, input: $input) {
+          success
+        }
+      }`,
+      { id: webhookId, input },
+    );
+    return data.webhookUpdate.success;
+  }
+
+  async deleteWebhook(webhookId: string): Promise<boolean> {
+    const data = await this.gql<{
+      webhookDelete: { success: boolean };
+    }>(
+      `mutation WebhookDelete($id: String!) {
+        webhookDelete(id: $id) {
+          success
+        }
+      }`,
+      { id: webhookId },
+    );
+    return data.webhookDelete.success;
+  }
 }

package/src/infra/cli.ts

@@ -644,6 +644,156 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
         process.exitCode = 1;
       }
     });
+
+  // --- openclaw openclaw-linear webhooks ---
+  const webhooksCmd = linear
+    .command("webhooks")
+    .description("Manage Linear webhook subscriptions");
+
+  webhooksCmd
+    .command("status")
+    .description("Show current webhook configuration in Linear")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found. Run \"openclaw openclaw-linear auth\" first.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      console.log("\nLinear Webhooks");
+      console.log("─".repeat(50));
+
+      const webhooks = await linearApi.listWebhooks();
+      if (webhooks.length === 0) {
+        console.log("\n  No webhooks found.");
+        console.log("  Run \"openclaw openclaw-linear webhooks setup\" to create one.\n");
+        return;
+      }
+
+      for (const wh of webhooks) {
+        const status = wh.enabled ? "enabled" : "DISABLED";
+        const label = wh.label ?? "(no label)";
+        const team = wh.team ? ` (team: ${wh.team.name})` : " (all teams)";
+        console.log(`\n  ${label}${team}`);
+        console.log(`    ID:      ${wh.id}`);
+        console.log(`    URL:     ${wh.url}`);
+        console.log(`    Status:  ${status}`);
+        console.log(`    Events:  ${wh.resourceTypes.join(", ")}`);
+        console.log(`    Created: ${wh.createdAt}`);
+      }
+
+      console.log();
+    });
+
+  webhooksCmd
+    .command("setup")
+    .description("Auto-provision or fix the workspace webhook (create/update as needed)")
+    .option("--url <url>", "Webhook URL (default: from Cloudflare tunnel config)")
+    .option("--team <id>", "Restrict to a specific team ID (default: all public teams)")
+    .option("--dry-run", "Show what would change without making changes")
+    .action(async (opts: { url?: string; team?: string; dryRun?: boolean }) => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const { provisionWebhook, getWebhookStatus, REQUIRED_RESOURCE_TYPES } = await import("./webhook-provision.js");
+
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found. Run \"openclaw openclaw-linear auth\" first.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      const webhookUrl = opts.url
+        ?? (pluginConfig?.webhookUrl as string)
+        ?? "https://linear.calltelemetry.com/linear/webhook";
+
+      console.log("\nWebhook Provisioning");
+      console.log("─".repeat(50));
+      console.log(`  URL:    ${webhookUrl}`);
+      console.log(`  Events: ${[...REQUIRED_RESOURCE_TYPES].join(", ")}`);
+
+      if (opts.dryRun) {
+        const status = await getWebhookStatus(linearApi, webhookUrl);
+        if (!status) {
+          console.log("\n  Would CREATE a new webhook with the above config.");
+        } else if (status.issues.length === 0) {
+          console.log("\n  Webhook already configured correctly. No changes needed.");
+        } else {
+          console.log("\n  Would UPDATE existing webhook:");
+          for (const issue of status.issues) {
+            console.log(`    - Fix: ${issue}`);
+          }
+        }
+        console.log();
+        return;
+      }
+
+      const result = await provisionWebhook(linearApi, webhookUrl, {
+        teamId: opts.team,
+        allPublicTeams: !opts.team,
+      });
+
+      switch (result.action) {
+        case "created":
+          console.log(`\n  Created webhook: ${result.webhookId}`);
+          break;
+        case "updated":
+          console.log(`\n  Updated webhook: ${result.webhookId}`);
+          for (const change of result.changes ?? []) {
+            console.log(`    - ${change}`);
+          }
+          break;
+        case "already_ok":
+          console.log(`\n  Webhook already configured correctly (${result.webhookId}). No changes needed.`);
+          break;
+      }
+
+      console.log();
+    });
+
+  webhooksCmd
+    .command("delete")
+    .description("Delete a webhook by ID")
+    .argument("<webhook-id>", "ID of the webhook to delete")
+    .action(async (webhookId: string) => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (!tokenInfo.accessToken) {
+        console.error("\n  No Linear token found.\n");
+        process.exitCode = 1;
+        return;
+      }
+
+      const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+        refreshToken: tokenInfo.refreshToken,
+        expiresAt: tokenInfo.expiresAt,
+      });
+
+      const confirmAnswer = await prompt(`Delete webhook ${webhookId}? [y/N]: `);
+      if (confirmAnswer.toLowerCase() !== "y") {
+        console.log("  Aborted.\n");
+        return;
+      }
+
+      const success = await linearApi.deleteWebhook(webhookId);
+      if (success) {
+        console.log(`\n  Deleted webhook ${webhookId}\n`);
+      } else {
+        console.error(`\n  Failed to delete webhook ${webhookId}\n`);
+        process.exitCode = 1;
+      }
+    });
 }
 
 // ---------------------------------------------------------------------------

package/src/infra/doctor.test.ts

@@ -11,6 +11,9 @@ vi.mock("../api/linear-api.js", () => ({
     expiresAt: Date.now() + 24 * 3_600_000,
     source: "profile" as const,
   })),
+  LinearAgentApi: class MockLinearAgentApi {
+    constructor() {}
+  },
   AUTH_PROFILES_PATH: "/tmp/test-auth-profiles.json",
   LINEAR_GRAPHQL_URL: "https://api.linear.app/graphql",
 }));
@@ -57,6 +60,16 @@ vi.mock("../tools/code-tool.js", () => ({
   })),
 }));
 
+vi.mock("./webhook-provision.js", () => ({
+  getWebhookStatus: vi.fn(async () => null),
+  provisionWebhook: vi.fn(async () => ({
+    action: "created",
+    webhookId: "wh-test-1",
+    changes: ["created new webhook"],
+  })),
+  REQUIRED_RESOURCE_TYPES: ["Comment", "Issue"],
+}));
+
 import {
   checkAuth,
   checkAgentConfig,
@@ -64,6 +77,7 @@ import {
   checkFilesAndDirs,
   checkConnectivity,
   checkDispatchHealth,
+  checkWebhooks,
   runDoctor,
   formatReport,
   formatReportJson,
@@ -330,7 +344,7 @@ describe("checkDispatchHealth", () => {
 // ---------------------------------------------------------------------------
 
 describe("runDoctor", () => {
-  it("returns all 6 sections", async () => {
+  it("returns all 7 sections", async () => {
     vi.stubGlobal("fetch", vi.fn(async (url: string) => {
       if (url.includes("linear.app")) {
         return {
@@ -342,7 +356,7 @@ describe("runDoctor", () => {
     }));
 
     const report = await runDoctor({ fix: false, json: false });
-    expect(report.sections).toHaveLength(6);
+    expect(report.sections).toHaveLength(7);
     expect(report.sections.map((s) => s.name)).toEqual([
       "Authentication & Tokens",
       "Agent Configuration",
@@ -350,6 +364,7 @@ describe("runDoctor", () => {
       "Files & Directories",
       "Connectivity",
       "Dispatch Health",
+      "Webhook Configuration",
     ]);
     expect(report.summary.passed + report.summary.warnings + report.summary.errors).toBeGreaterThan(0);
   });

package/src/infra/doctor.ts

@@ -8,11 +8,12 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 
-import { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
+import { resolveLinearToken, LinearAgentApi, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
 import { readDispatchState, listActiveDispatches, listStaleDispatches, pruneCompleted, type DispatchState } from "../pipeline/dispatch-state.js";
 import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
 import { listWorktrees } from "./codex-worktree.js";
 import { loadCodingConfig, type CodingBackend } from "../tools/code-tool.js";
+import { getWebhookStatus, provisionWebhook, REQUIRED_RESOURCE_TYPES } from "./webhook-provision.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -650,6 +651,68 @@ export async function checkDispatchHealth(pluginConfig?: Record<string, unknown>
   return checks;
 }
 
+// ---------------------------------------------------------------------------
+// Section 7: Webhook Configuration
+// ---------------------------------------------------------------------------
+
+export async function checkWebhooks(pluginConfig?: Record<string, unknown>, fix = false): Promise<CheckResult[]> {
+  const checks: CheckResult[] = [];
+
+  const tokenInfo = resolveLinearToken(pluginConfig);
+  if (!tokenInfo.accessToken) {
+    checks.push(warn("Webhook check skipped (no Linear token)"));
+    return checks;
+  }
+
+  const linearApi = new LinearAgentApi(tokenInfo.accessToken, {
+    refreshToken: tokenInfo.refreshToken,
+    expiresAt: tokenInfo.expiresAt,
+  });
+
+  const webhookUrl = (pluginConfig?.webhookUrl as string)
+    ?? "https://linear.calltelemetry.com/linear/webhook";
+
+  try {
+    const status = await getWebhookStatus(linearApi, webhookUrl);
+
+    if (!status) {
+      if (fix) {
+        const result = await provisionWebhook(linearApi, webhookUrl, { allPublicTeams: true });
+        checks.push(pass(`Workspace webhook created (${result.webhookId}) (--fix)`));
+      } else {
+        checks.push(fail(
+          `No workspace webhook found for ${webhookUrl}`,
+          undefined,
+          'Run: openclaw openclaw-linear webhooks setup',
+        ));
+      }
+      return checks;
+    }
+
+    if (status.issues.length === 0) {
+      checks.push(pass(`Workspace webhook OK (${[...REQUIRED_RESOURCE_TYPES].join(", ")})`));
+    } else {
+      if (fix) {
+        const result = await provisionWebhook(linearApi, webhookUrl);
+        const changes = result.changes?.join(", ") ?? "fixed";
+        checks.push(pass(`Workspace webhook fixed: ${changes} (--fix)`));
+      } else {
+        for (const issue of status.issues) {
+          checks.push(warn(
+            `Webhook issue: ${issue}`,
+            undefined,
+            { fixable: true, fix: 'Run: openclaw openclaw-linear webhooks setup' },
+          ));
+        }
+      }
+    }
+  } catch (err) {
+    checks.push(warn(`Webhook check failed: ${err instanceof Error ? err.message : String(err)}`));
+  }
+
+  return checks;
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -685,6 +748,12 @@ export async function runDoctor(opts: DoctorOptions): Promise<DoctorReport> {
     checks: await checkDispatchHealth(opts.pluginConfig, opts.fix),
   });
 
+  // 7. Webhook configuration (auto-fix if --fix)
+  sections.push({
+    name: "Webhook Configuration",
+    checks: await checkWebhooks(opts.pluginConfig, opts.fix),
+  });
+
   // Fix: chmod auth-profiles.json if needed
   if (opts.fix) {
     const permCheck = auth.checks.find((c) => c.fixable && c.label.includes("permissions"));

package/src/infra/webhook-provision.test.ts

@@ -0,0 +1,162 @@
+/**
+ * webhook-provision.test.ts — Unit tests for webhook auto-provisioning.
+ *
+ * Tests getWebhookStatus() and provisionWebhook() with inline mock objects.
+ * No vi.mock needed — both functions accept linearApi as a parameter.
+ */
+import { describe, expect, it, vi } from "vitest";
+import {
+  getWebhookStatus,
+  provisionWebhook,
+  REQUIRED_RESOURCE_TYPES,
+  WEBHOOK_LABEL,
+} from "./webhook-provision.js";
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+const TEST_URL = "https://example.com/linear/webhook";
+
+function makeWebhook(overrides?: Record<string, unknown>) {
+  return {
+    id: "wh-1",
+    label: WEBHOOK_LABEL,
+    url: TEST_URL,
+    enabled: true,
+    resourceTypes: ["Comment", "Issue"],
+    allPublicTeams: true,
+    team: null,
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function makeMockApi(overrides?: Record<string, unknown>) {
+  return {
+    listWebhooks: vi.fn().mockResolvedValue([]),
+    createWebhook: vi.fn().mockResolvedValue({ id: "new-wh", enabled: true }),
+    updateWebhook: vi.fn().mockResolvedValue(true),
+    deleteWebhook: vi.fn().mockResolvedValue(true),
+    ...overrides,
+  } as any;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe("REQUIRED_RESOURCE_TYPES", () => {
+  it("contains exactly Comment and Issue", () => {
+    expect([...REQUIRED_RESOURCE_TYPES]).toEqual(["Comment", "Issue"]);
+  });
+});
+
+describe("getWebhookStatus", () => {
+  it("returns null when no webhook matches URL", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([
+        makeWebhook({ url: "https://other.com/webhook" }),
+      ]),
+    });
+    const status = await getWebhookStatus(api, TEST_URL);
+    expect(status).toBeNull();
+  });
+
+  it("returns status with no issues when webhook is correctly configured", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([makeWebhook()]),
+    });
+    const status = await getWebhookStatus(api, TEST_URL);
+    expect(status).not.toBeNull();
+    expect(status!.id).toBe("wh-1");
+    expect(status!.issues).toEqual([]);
+  });
+
+  it("reports disabled webhook", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([
+        makeWebhook({ enabled: false }),
+      ]),
+    });
+    const status = await getWebhookStatus(api, TEST_URL);
+    expect(status!.issues).toContain("disabled");
+  });
+
+  it("reports missing event types", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([
+        makeWebhook({ resourceTypes: ["Comment"] }),
+      ]),
+    });
+    const status = await getWebhookStatus(api, TEST_URL);
+    expect(status!.issues.some((i) => i.includes("missing event type: Issue"))).toBe(true);
+  });
+
+  it("reports unnecessary event types", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([
+        makeWebhook({ resourceTypes: ["Comment", "Issue", "User"] }),
+      ]),
+    });
+    const status = await getWebhookStatus(api, TEST_URL);
+    expect(status!.issues.some((i) => i.includes("unnecessary event types: User"))).toBe(true);
+  });
+});
+
+describe("provisionWebhook", () => {
+  it("creates new webhook when none exists", async () => {
+    const api = makeMockApi();
+    const result = await provisionWebhook(api, TEST_URL);
+
+    expect(result.action).toBe("created");
+    expect(result.webhookId).toBe("new-wh");
+    expect(result.changes).toContain("created new webhook");
+    expect(api.createWebhook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: TEST_URL,
+        resourceTypes: [...REQUIRED_RESOURCE_TYPES],
+        enabled: true,
+      }),
+    );
+  });
+
+  it("returns already_ok when webhook is correct", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([makeWebhook()]),
+    });
+    const result = await provisionWebhook(api, TEST_URL);
+
+    expect(result.action).toBe("already_ok");
+    expect(result.webhookId).toBe("wh-1");
+    expect(api.createWebhook).not.toHaveBeenCalled();
+    expect(api.updateWebhook).not.toHaveBeenCalled();
+  });
+
+  it("updates webhook to fix issues", async () => {
+    const api = makeMockApi({
+      listWebhooks: vi.fn().mockResolvedValue([
+        makeWebhook({
+          enabled: false,
+          resourceTypes: ["Comment", "Issue", "User", "Customer"],
+        }),
+      ]),
+    });
+    const result = await provisionWebhook(api, TEST_URL);
+
+    expect(result.action).toBe("updated");
+    expect(result.webhookId).toBe("wh-1");
+    expect(result.changes).toBeDefined();
+    expect(result.changes!.some((c) => c.includes("enabled"))).toBe(true);
+    expect(result.changes!.some((c) => c.includes("removed event types"))).toBe(true);
+    expect(api.updateWebhook).toHaveBeenCalledWith("wh-1", expect.objectContaining({
+      enabled: true,
+      resourceTypes: [...REQUIRED_RESOURCE_TYPES],
+    }));
+  });
+
+  it("passes teamId option to createWebhook", async () => {
+    const api = makeMockApi();
+    await provisionWebhook(api, TEST_URL, { teamId: "team-1" });
+
+    expect(api.createWebhook).toHaveBeenCalledWith(
+      expect.objectContaining({ teamId: "team-1" }),
+    );
+  });
+});