@anura-gate/watcher-jira 0.1.0

package/cli.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+// -----------------------------------------------------------------
+// GATE Watcher -- Jira CLI
+//
+// Quick-start mode: runs the watcher with terminal output.
+// Jira uses API token auth -- no QR code needed.
+//
+// Usage:
+//   npx @anura-gate/watcher-jira
+//   # or
+//   GATE_URL=... GATE_KEY=... GATE_INTEGRATION_ID=... \
+//   JIRA_DOMAIN=yourcompany.atlassian.net \
+//   JIRA_EMAIL=you@company.com JIRA_TOKEN=ATATT3x... \
+//   JIRA_PROJECTS=PROJ,ENG \
+//   npx @anura-gate/watcher-jira
+// -----------------------------------------------------------------
+
+require("dotenv").config();
+const { GateJiraWatcher } = require("./lib/gate-watcher-jira");
+
+// -- Config ----------------------------------------------------------
+
+const GATE_URL = process.env.GATE_URL; // optional -- SDK has default
+const GATE_KEY = process.env.GATE_KEY;
+const INTEGRATION_ID = process.env.GATE_INTEGRATION_ID;
+const JIRA_DOMAIN = process.env.JIRA_DOMAIN;
+const JIRA_EMAIL = process.env.JIRA_EMAIL;
+const JIRA_TOKEN = process.env.JIRA_TOKEN;
+const JIRA_PROJECTS = process.env.JIRA_PROJECTS; // comma-separated: "PROJ,ENG"
+
+if (!GATE_KEY) {
+  console.error("Missing GATE_KEY environment variable");
+  console.error("   Get your virtual key from GATE Dashboard -> Keys");
+  process.exit(1);
+}
+
+if (!INTEGRATION_ID) {
+  console.error("Missing GATE_INTEGRATION_ID environment variable");
+  console.error("   Get your integration ID from GATE Dashboard -> Integrations");
+  process.exit(1);
+}
+
+if (!JIRA_DOMAIN) {
+  console.error("Missing JIRA_DOMAIN environment variable");
+  console.error("   e.g. yourcompany.atlassian.net");
+  process.exit(1);
+}
+
+if (!JIRA_EMAIL) {
+  console.error("Missing JIRA_EMAIL environment variable");
+  console.error("   Your Atlassian account email address");
+  process.exit(1);
+}
+
+if (!JIRA_TOKEN) {
+  console.error("Missing JIRA_TOKEN environment variable");
+  console.error("   Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens");
+  console.error("   It stays local and is NEVER sent to GATE.");
+  process.exit(1);
+}
+
+// -- Create Watcher --------------------------------------------------
+
+const projects = JIRA_PROJECTS
+  ? JIRA_PROJECTS.split(",").map((p) => p.trim()).filter(Boolean)
+  : [];
+
+const opts = {
+  gateKey: GATE_KEY,
+  integrationId: INTEGRATION_ID,
+  jiraDomain: JIRA_DOMAIN,
+  jiraEmail: JIRA_EMAIL,
+  jiraToken: JIRA_TOKEN,
+  projects,
+};
+if (GATE_URL) opts.gateUrl = GATE_URL;
+
+const watcher = new GateJiraWatcher(opts);
+
+// -- Wire up events for terminal display -----------------------------
+
+watcher.on("ready", (displayName) => {
+  console.log(`Jira ready: ${displayName}`);
+  console.log(`   GATE URL:        ${opts.gateUrl || "https://anuragate.com"}`);
+  console.log(`   Integration ID:  ${INTEGRATION_ID}`);
+  console.log(`   Jira domain:     ${JIRA_DOMAIN}`);
+  if (projects.length > 0) {
+    console.log(`   Watching:        ${projects.join(", ")}`);
+  } else {
+    console.log(`   Watching:        all projects`);
+  }
+  console.log("");
+});
+
+watcher.on("event", (event, result) => {
+  if (result.rateLimited) {
+    console.warn("Daily event limit reached -- event not processed");
+    return;
+  }
+  const actions = result.securityActions;
+  const suffix = actions.length > 0 ? ` [${actions.join(", ")}]` : "";
+  const text = event.content.text || "(no text)";
+  const body = text.length > 80 ? text.slice(0, 80) + "..." : text;
+  console.log(`[${event.eventType}] ${body}${suffix}`);
+});
+
+watcher.on("action", (action) => {
+  console.log(`[ACTION] ${action.action} -> ${JSON.stringify(action.params)}`);
+});
+
+watcher.on("action_result", ({ actionId, action, success, error }) => {
+  if (success) {
+    console.log(`  ${action} completed`);
+  } else {
+    console.error(`  ${action} failed: ${error}`);
+  }
+});
+
+watcher.on("gate_error", ({ path, status, error }) => {
+  console.error(`GATE ${path} -> ${status}: ${error?.message || "unknown error"}`);
+});
+
+watcher.on("jira_error", ({ path, error }) => {
+  console.error(`Jira ${path} -> ${error}`);
+});
+
+watcher.on("limit_reached", (type) => {
+  console.warn(`Plan limit reached: ${type}`);
+});
+
+// -- Graceful shutdown -----------------------------------------------
+
+async function shutdown(signal) {
+  console.log(`\n${signal} -- shutting down...`);
+  await watcher.stop();
+  console.log("Disconnected");
+  process.exit(0);
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+// -- Web Panel (optional) --------------------------------------------
+
+const WEB_PORT = process.env.WEB_PORT ? parseInt(process.env.WEB_PORT, 10) : null;
+
+if (WEB_PORT) {
+  watcher.startPanel(WEB_PORT);
+  console.log(`Dashboard: http://localhost:${WEB_PORT}\n`);
+}
+
+// -- Start -----------------------------------------------------------
+
+console.log("GATE Watcher (Jira) starting...\n");
+
+watcher.start().catch((err) => {
+  console.error("Failed to start:", err.message);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,2 @@
+const { GateJiraWatcher } = require("./lib/gate-watcher-jira");
+module.exports = { GateJiraWatcher };

package/lib/gate-watcher-jira.js

@@ -0,0 +1,745 @@
+// -----------------------------------------------------------------
+// GateJiraWatcher -- SDK class for Jira event monitoring
+//
+// Polls Jira for issue updates, comments, and transitions using
+// an API token + email. Token stays local, never sent to GATE.
+//
+// Usage:
+//   const { GateJiraWatcher } = require("@anura-gate/watcher-jira");
+//   const watcher = new GateJiraWatcher({
+//     gateKey: "gk-xxx",
+//     integrationId: "int_xxx",
+//     jiraDomain: "yourcompany.atlassian.net",
+//     jiraEmail: "you@company.com",
+//     jiraToken: "ATATT3x...",
+//     projects: ["PROJ", "ENG"],   // optional -- watch specific projects
+//   });
+//   watcher.on("ready", (user) => console.log("Connected:", user));
+//   await watcher.start();
+// -----------------------------------------------------------------
+
+const { EventEmitter } = require("events");
+
+class GateJiraWatcher extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.gateKey              -- Virtual key (gk-xxx)
+   * @param {string} opts.integrationId        -- Integration ID (int_xxx)
+   * @param {string} opts.jiraDomain           -- e.g. "yourcompany.atlassian.net"
+   * @param {string} opts.jiraEmail            -- Atlassian account email
+   * @param {string} opts.jiraToken            -- Jira API token (stays local, NEVER sent to GATE)
+   * @param {string[]} [opts.projects]         -- Project keys to watch. Empty = all.
+   * @param {string} [opts.gateUrl]            -- GATE URL (default: "https://anuragate.com")
+   * @param {number} [opts.pollInterval]       -- ms between Jira polls (default: 30000)
+   * @param {number} [opts.heartbeatInterval]  -- ms between heartbeats (default: 30000)
+   * @param {string} [opts.sessionId]          -- Session ID for multi-tenant
+   * @param {string} [opts.sessionLabel]       -- Human-readable label
+   * @param {object} [opts.sessionMetadata]    -- Arbitrary metadata
+   */
+  constructor(opts) {
+    super();
+
+    if (!opts.gateKey) throw new Error("gateKey is required");
+    if (!opts.integrationId) throw new Error("integrationId is required");
+    if (!opts.jiraDomain) throw new Error("jiraDomain is required");
+    if (!opts.jiraEmail) throw new Error("jiraEmail is required");
+    if (!opts.jiraToken) throw new Error("jiraToken is required");
+
+    this.gateUrl = (opts.gateUrl || "https://anuragate.com").replace(/\/$/, "");
+    this.gateKey = opts.gateKey;
+    this.integrationId = opts.integrationId;
+    this.sessionId = opts.sessionId || null;
+    this._sessionLabel = opts.sessionLabel || opts.sessionId || null;
+    this._sessionMetadata = opts.sessionMetadata || {};
+
+    this.jiraDomain = opts.jiraDomain.replace(/\/$/, "");
+    this.jiraEmail = opts.jiraEmail;
+    this.jiraToken = opts.jiraToken;
+    this.projects = opts.projects || [];
+    this.pollInterval = opts.pollInterval || 30_000;
+    this.heartbeatInterval = opts.heartbeatInterval || 30_000;
+    this.timeout = 15_000;
+
+    this._heartbeatTimer = null;
+    this._outboundTimer = null;
+    this._pollTimer = null;
+    this._running = false;
+    this._ready = false;
+    this._panel = null;
+    this._displayName = null;
+
+    // Track last poll time for incremental fetching
+    this._lastPollTime = null;
+    // Seen issue event IDs to prevent duplicates
+    this._seenEventIds = new Set();
+    this._maxSeenIds = 5000;
+
+    this._headers = {
+      "Content-Type": "application/json",
+      "x-gate-key": this.gateKey,
+    };
+
+    // Jira Cloud uses Basic auth: email:token base64-encoded
+    const authStr = Buffer.from(`${this.jiraEmail}:${this.jiraToken}`).toString("base64");
+    this._jiraHeaders = {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      Authorization: `Basic ${authStr}`,
+    };
+  }
+
+  // -- Public API ---------------------------------------------------
+
+  async start() {
+    if (this._running) throw new Error("Watcher is already running");
+    this._running = true;
+
+    if (this.sessionId) {
+      await this._registerSession();
+    }
+
+    // Verify credentials by fetching current user
+    const userRes = await this._jiraGet("/rest/api/3/myself");
+    if (!userRes.ok) {
+      this._running = false;
+      this._updateSessionStatus("error");
+      throw new Error(
+        `Jira auth failed (${userRes.status}): ${userRes.data?.message || userRes.data?.errorMessages?.[0] || "invalid credentials"}`
+      );
+    }
+
+    this._displayName = userRes.data.displayName || userRes.data.emailAddress || "unknown";
+    this._ready = true;
+    this._updateSessionStatus("connected");
+    this.emit("ready", this._displayName);
+
+    // Set initial poll time to now minus 5 minutes (catch recent activity on first run)
+    this._lastPollTime = new Date(Date.now() - 5 * 60_000).toISOString().replace("Z", "+0000");
+
+    // Start Jira polling loop
+    this._pollJira();
+    this._pollTimer = setInterval(() => this._pollJira(), this.pollInterval);
+
+    // Start GATE heartbeat
+    this._sendHeartbeat();
+    this._heartbeatTimer = setInterval(() => this._sendHeartbeat(), this.heartbeatInterval);
+
+    // Start GATE outbound poll
+    this._pollOutbound();
+    this._outboundTimer = setInterval(() => this._pollOutbound(), 3_000);
+  }
+
+  async stop() {
+    this._running = false;
+    this._ready = false;
+
+    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
+    if (this._outboundTimer) clearInterval(this._outboundTimer);
+    if (this._pollTimer) clearInterval(this._pollTimer);
+    this._heartbeatTimer = null;
+    this._outboundTimer = null;
+    this._pollTimer = null;
+
+    await this._updateSessionStatus("disconnected");
+
+    if (this._panel) {
+      this._panel.close();
+      this._panel = null;
+    }
+
+    this.emit("stopped");
+  }
+
+  attach(server, path = "/ws/jira") {
+    const { PanelServer } = require("./panel-server");
+    this._panel = new PanelServer(this);
+    this._panel.attachTo(server, path);
+    return this._panel;
+  }
+
+  startPanel(port = 3001) {
+    const { PanelServer } = require("./panel-server");
+    this._panel = new PanelServer(this);
+    this._panel.listen(port);
+    return this._panel;
+  }
+
+  getStatus() {
+    if (!this._running) return "disconnected";
+    if (this._ready) return "connected";
+    return "connecting";
+  }
+
+  getQR() {
+    return null; // Jira uses token auth
+  }
+
+  // -- Internal: Jira API -------------------------------------------
+
+  _jiraUrl(path) {
+    const domain = this.jiraDomain.includes("://")
+      ? this.jiraDomain
+      : `https://${this.jiraDomain}`;
+    return `${domain}${path}`;
+  }
+
+  async _jiraGet(path) {
+    const url = this._jiraUrl(path);
+    try {
+      const res = await fetch(url, {
+        method: "GET",
+        headers: this._jiraHeaders,
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      if (res.status === 204) return { ok: true, status: 204, data: {} };
+      const data = await res.json();
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("jira_error", { path, error: err.message });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  async _jiraPost(path, body) {
+    const url = this._jiraUrl(path);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this._jiraHeaders,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      if (res.status === 204) return { ok: true, status: 204, data: {} };
+      const data = await res.json();
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("jira_error", { path, error: err.message });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  async _jiraPut(path, body) {
+    const url = this._jiraUrl(path);
+    try {
+      const res = await fetch(url, {
+        method: "PUT",
+        headers: this._jiraHeaders,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      if (res.status === 204) return { ok: true, status: 204, data: {} };
+      const data = await res.json().catch(() => ({}));
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("jira_error", { path, error: err.message });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  // -- Internal: Jira Polling ----------------------------------------
+
+  async _pollJira() {
+    if (!this._running) return;
+
+    try {
+      // Poll recently updated issues via JQL search
+      await this._pollUpdatedIssues();
+    } catch (err) {
+      this._updateSessionStatus("error");
+      this.emit("jira_error", { path: "poll", error: err.message });
+    }
+  }
+
+  async _pollUpdatedIssues() {
+    // Build JQL: recently updated issues, optionally scoped to projects
+    let jql = `updated >= "${this._lastPollTime}"`;
+    if (this.projects.length > 0) {
+      const projectList = this.projects.map((p) => `"${p}"`).join(", ");
+      jql += ` AND project IN (${projectList})`;
+    }
+    jql += " ORDER BY updated ASC";
+
+    const params = new URLSearchParams({
+      jql,
+      maxResults: "50",
+      fields: "summary,status,assignee,reporter,priority,issuetype,project,comment,updated,created,labels,description",
+      expand: "changelog",
+    });
+
+    const res = await this._jiraGet(`/rest/api/3/search?${params.toString()}`);
+    if (!res.ok || !res.data?.issues) return;
+
+    // Update poll time for next cycle
+    this._lastPollTime = new Date().toISOString().replace("Z", "+0000");
+
+    for (const issue of res.data.issues) {
+      // Process changelog entries (status transitions, field changes)
+      if (issue.changelog?.histories) {
+        for (const history of issue.changelog.histories) {
+          await this._processChangelog(issue, history);
+        }
+      }
+
+      // Process new comments
+      if (issue.fields?.comment?.comments) {
+        for (const comment of issue.fields.comment.comments) {
+          await this._processComment(issue, comment);
+        }
+      }
+    }
+  }
+
+  async _processChangelog(issue, history) {
+    const eventId = `changelog_${history.id}`;
+    if (this._seenEventIds.has(eventId)) return;
+    this._markSeen(eventId);
+
+    const author = history.author?.displayName || history.author?.emailAddress || "unknown";
+
+    for (const item of history.items || []) {
+      const eventType = this._mapChangeType(item.field);
+      const text = this._formatChangeText(issue, author, item);
+
+      const normalized = {
+        id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        tool: "jira",
+        eventType,
+        timestamp: history.created || new Date().toISOString(),
+        source: {
+          id: author,
+          type: "user",
+          name: author,
+        },
+        content: {
+          text,
+          metadata: {
+            issueKey: issue.key,
+            issueId: issue.id,
+            summary: issue.fields?.summary || "",
+            project: issue.fields?.project?.key || "",
+            field: item.field,
+            fieldType: item.fieldtype,
+            from: item.fromString,
+            to: item.toString,
+            issueType: issue.fields?.issuetype?.name || "",
+            priority: issue.fields?.priority?.name || "",
+            status: issue.fields?.status?.name || "",
+            assignee: issue.fields?.assignee?.displayName || null,
+          },
+        },
+        raw: { issue: { key: issue.key, id: issue.id }, history, item },
+      };
+
+      const gateRes = await this._sendToGate(normalized);
+      this.emit("event", normalized, {
+        ok: gateRes.ok,
+        status: gateRes.status,
+        securityActions: gateRes.data?.securityActions || [],
+        blocked: gateRes.data?.blocked || false,
+        rateLimited: gateRes.status === 429,
+      });
+    }
+  }
+
+  async _processComment(issue, comment) {
+    const eventId = `comment_${comment.id}`;
+    if (this._seenEventIds.has(eventId)) return;
+    this._markSeen(eventId);
+
+    const author = comment.author?.displayName || comment.author?.emailAddress || "unknown";
+
+    // Extract text from Atlassian Document Format (ADF)
+    const commentText = this._extractAdfText(comment.body);
+
+    const normalized = {
+      id: `evt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      tool: "jira",
+      eventType: "comment_added",
+      timestamp: comment.created || new Date().toISOString(),
+      source: {
+        id: author,
+        type: "user",
+        name: author,
+      },
+      content: {
+        text: `${author} commented on ${issue.key}: ${commentText.slice(0, 200)}`,
+        metadata: {
+          issueKey: issue.key,
+          issueId: issue.id,
+          summary: issue.fields?.summary || "",
+          project: issue.fields?.project?.key || "",
+          commentId: comment.id,
+          commentBody: commentText,
+          issueType: issue.fields?.issuetype?.name || "",
+          priority: issue.fields?.priority?.name || "",
+          status: issue.fields?.status?.name || "",
+        },
+      },
+      raw: { issue: { key: issue.key, id: issue.id }, comment },
+    };
+
+    const gateRes = await this._sendToGate(normalized);
+    this.emit("event", normalized, {
+      ok: gateRes.ok,
+      status: gateRes.status,
+      securityActions: gateRes.data?.securityActions || [],
+      blocked: gateRes.data?.blocked || false,
+      rateLimited: gateRes.status === 429,
+    });
+  }
+
+  // -- Internal: Event Normalization ---------------------------------
+
+  _mapChangeType(field) {
+    const map = {
+      status: "issue_transitioned",
+      assignee: "issue_assigned",
+      priority: "priority_changed",
+      summary: "issue_updated",
+      description: "issue_updated",
+      labels: "labels_changed",
+      "Fix Version": "fix_version_changed",
+      Sprint: "sprint_changed",
+      resolution: "issue_resolved",
+      issuetype: "issue_type_changed",
+    };
+    return map[field] || "issue_updated";
+  }
+
+  _formatChangeText(issue, author, item) {
+    const key = issue.key;
+
+    switch (item.field) {
+      case "status":
+        return `${author} transitioned ${key} from "${item.fromString}" to "${item.toString}"`;
+      case "assignee":
+        return `${author} assigned ${key} to ${item.toString || "unassigned"}`;
+      case "priority":
+        return `${author} changed priority of ${key} from "${item.fromString}" to "${item.toString}"`;
+      case "resolution":
+        return item.toString
+          ? `${author} resolved ${key} as "${item.toString}"`
+          : `${author} reopened ${key}`;
+      case "summary":
+        return `${author} updated summary of ${key}: "${item.toString}"`;
+      case "labels":
+        return `${author} changed labels on ${key}: ${item.toString || "(none)"}`;
+      case "Sprint":
+        return `${author} moved ${key} to sprint "${item.toString || "(none)"}"`;
+      default:
+        return `${author} changed ${item.field} on ${key}: "${item.fromString || ""}" → "${item.toString || ""}"`;
+    }
+  }
+
+  /**
+   * Extract plain text from Jira's Atlassian Document Format (ADF).
+   * ADF is a nested JSON structure — we walk it to find text nodes.
+   */
+  _extractAdfText(adf) {
+    if (!adf) return "";
+    if (typeof adf === "string") return adf;
+    if (adf.type === "text") return adf.text || "";
+
+    let result = "";
+    if (Array.isArray(adf.content)) {
+      for (const node of adf.content) {
+        const text = this._extractAdfText(node);
+        if (text) {
+          // Add newline between paragraph-level nodes
+          if (node.type === "paragraph" || node.type === "heading" || node.type === "codeBlock") {
+            result += (result ? "\n" : "") + text;
+          } else {
+            result += text;
+          }
+        }
+      }
+    }
+    return result;
+  }
+
+  // -- Internal: Send to GATE ---------------------------------------
+
+  async _sendToGate(normalizedEvent) {
+    return this._gatePost("/v1/tools/watcher/event", {
+      integrationId: this.integrationId,
+      ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+      event: normalizedEvent,
+    });
+  }
+
+  // -- Internal: GATE API -------------------------------------------
+
+  async _gatePost(path, body) {
+    const url = `${this.gateUrl}${path}`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: this._headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        this.emit("gate_error", { path, status: res.status, error: data.error });
+      }
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("gate_error", { path, status: 0, error: { message: err.message } });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  async _gateGet(reqPath) {
+    const url = `${this.gateUrl}${reqPath}`;
+    try {
+      const res = await fetch(url, {
+        method: "GET",
+        headers: this._headers,
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      const data = await res.json();
+      if (!res.ok && res.status !== 404) {
+        this.emit("gate_error", { path: reqPath, status: res.status, error: data.error });
+      }
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("gate_error", { path: reqPath, status: 0, error: { message: err.message } });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  async _gatePatch(path, body) {
+    const url = `${this.gateUrl}${path}`;
+    try {
+      const res = await fetch(url, {
+        method: "PATCH",
+        headers: this._headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeout),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        this.emit("gate_error", { path, status: res.status, error: data.error });
+      }
+      return { ok: res.ok, status: res.status, data };
+    } catch (err) {
+      this.emit("gate_error", { path, status: 0, error: { message: err.message } });
+      return { ok: false, status: 0, data: null };
+    }
+  }
+
+  // -- Internal: Session Management ---------------------------------
+
+  async _registerSession() {
+    if (!this.sessionId) return;
+    await this._gatePost("/v1/tools/watcher/session", {
+      integrationId: this.integrationId,
+      sessionId: this.sessionId,
+      label: this._sessionLabel,
+      metadata: this._sessionMetadata,
+    });
+  }
+
+  async _updateSessionStatus(status) {
+    if (!this.sessionId) return;
+    await this._gatePatch("/v1/tools/watcher/session", {
+      integrationId: this.integrationId,
+      sessionId: this.sessionId,
+      status,
+    }).catch(() => {});
+  }
+
+  // -- Internal: Heartbeat ------------------------------------------
+
+  async _sendHeartbeat() {
+    const body = { integrationId: this.integrationId };
+    if (this.sessionId) { body.sessionIds = [this.sessionId]; }
+    const res = await this._gatePost("/v1/tools/watcher/heartbeat", body);
+    if (res.status === 429) {
+      this.emit("limit_reached", "watcher_agents");
+    }
+  }
+
+  // -- Internal: Outbound Poll --------------------------------------
+
+  async _pollOutbound() {
+    let url = `/v1/tools/watcher/outbound?integrationId=${this.integrationId}`;
+    if (this.sessionId) { url += `&sessionId=${this.sessionId}`; }
+    const res = await this._gateGet(url);
+    if (!res.ok || !res.data?.actions?.length) return;
+
+    for (const action of res.data.actions) {
+      this.emit("action", action);
+      await this._executeAction(action);
+    }
+  }
+
+  async _executeAction(action) {
+    let success = false;
+    let result = null;
+    let error = null;
+
+    try {
+      switch (action.action) {
+        case "create_issue": {
+          const projectKey = action.params.project || action.params.projectKey;
+          const summary = action.params.summary || action.params.title;
+          const description = action.params.description || action.params.body || "";
+          const issueType = action.params.issueType || "Task";
+          if (!projectKey || !summary) throw new Error("Missing 'project' or 'summary' in params");
+
+          const fields = {
+            project: { key: projectKey },
+            summary,
+            issuetype: { name: issueType },
+          };
+
+          // Description as ADF
+          if (description) {
+            fields.description = {
+              type: "doc",
+              version: 1,
+              content: [{ type: "paragraph", content: [{ type: "text", text: description }] }],
+            };
+          }
+
+          if (action.params.assignee) {
+            fields.assignee = { accountId: action.params.assignee };
+          }
+          if (action.params.priority) {
+            fields.priority = { name: action.params.priority };
+          }
+          if (action.params.labels) {
+            fields.labels = action.params.labels;
+          }
+
+          const res = await this._jiraPost("/rest/api/3/issue", { fields });
+          if (!res.ok) throw new Error(res.data?.errorMessages?.[0] || `Jira API error ${res.status}`);
+          result = { created: true, key: res.data.key, id: res.data.id, url: `https://${this.jiraDomain}/browse/${res.data.key}` };
+          success = true;
+          break;
+        }
+
+        case "add_comment": {
+          const issueKey = action.params.issueKey || action.params.issue;
+          const body = action.params.body || action.params.text || action.params.comment;
+          if (!issueKey || !body) throw new Error("Missing 'issueKey' or 'body' in params");
+
+          const commentBody = {
+            body: {
+              type: "doc",
+              version: 1,
+              content: [{ type: "paragraph", content: [{ type: "text", text: body }] }],
+            },
+          };
+
+          const res = await this._jiraPost(`/rest/api/3/issue/${issueKey}/comment`, commentBody);
+          if (!res.ok) throw new Error(res.data?.errorMessages?.[0] || `Jira API error ${res.status}`);
+          result = { created: true, commentId: res.data.id };
+          success = true;
+          break;
+        }
+
+        case "transition_issue": {
+          const issueKey = action.params.issueKey || action.params.issue;
+          const transitionName = action.params.transition || action.params.status;
+          if (!issueKey || !transitionName) throw new Error("Missing 'issueKey' or 'transition' in params");
+
+          // First, get available transitions
+          const transRes = await this._jiraGet(`/rest/api/3/issue/${issueKey}/transitions`);
+          if (!transRes.ok) throw new Error("Failed to fetch transitions");
+
+          const transition = transRes.data.transitions?.find(
+            (t) => t.name.toLowerCase() === transitionName.toLowerCase()
+          );
+          if (!transition) {
+            const available = (transRes.data.transitions || []).map((t) => t.name).join(", ");
+            throw new Error(`Transition "${transitionName}" not found. Available: ${available}`);
+          }
+
+          const res = await this._jiraPost(`/rest/api/3/issue/${issueKey}/transitions`, {
+            transition: { id: transition.id },
+          });
+          if (!res.ok) throw new Error(res.data?.errorMessages?.[0] || `Jira API error ${res.status}`);
+          result = { transitioned: true, from: null, to: transitionName };
+          success = true;
+          break;
+        }
+
+        case "assign_issue": {
+          const issueKey = action.params.issueKey || action.params.issue;
+          const accountId = action.params.accountId || action.params.assignee;
+          if (!issueKey) throw new Error("Missing 'issueKey' in params");
+
+          const res = await this._jiraPut(`/rest/api/3/issue/${issueKey}/assignee`, {
+            accountId: accountId || null, // null = unassign
+          });
+          if (!res.ok) throw new Error(res.data?.errorMessages?.[0] || `Jira API error ${res.status}`);
+          result = { assigned: true, assignee: accountId || null };
+          success = true;
+          break;
+        }
+
+        case "update_issue": {
+          const issueKey = action.params.issueKey || action.params.issue;
+          if (!issueKey) throw new Error("Missing 'issueKey' in params");
+
+          const fields = {};
+          if (action.params.summary) fields.summary = action.params.summary;
+          if (action.params.priority) fields.priority = { name: action.params.priority };
+          if (action.params.labels) fields.labels = action.params.labels;
+          if (action.params.description) {
+            fields.description = {
+              type: "doc",
+              version: 1,
+              content: [{ type: "paragraph", content: [{ type: "text", text: action.params.description }] }],
+            };
+          }
+
+          const res = await this._jiraPut(`/rest/api/3/issue/${issueKey}`, { fields });
+          if (!res.ok) throw new Error(res.data?.errorMessages?.[0] || `Jira API error ${res.status}`);
+          result = { updated: true };
+          success = true;
+          break;
+        }
+
+        default:
+          throw new Error(`Unknown action: ${action.action}`);
+      }
+    } catch (err) {
+      error = err.message;
+    }
+
+    await this._gatePost("/v1/tools/watcher/outbound", {
+      actionId: action.id,
+      integrationId: this.integrationId,
+      ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+      success,
+      result,
+      error,
+    });
+
+    this.emit("action_result", {
+      actionId: action.id,
+      action: action.action,
+      success,
+      result,
+      error,
+    });
+  }
+
+  // -- Internal: Helpers --------------------------------------------
+
+  _markSeen(id) {
+    this._seenEventIds.add(id);
+    if (this._seenEventIds.size > this._maxSeenIds) {
+      const iter = this._seenEventIds.values();
+      for (let i = 0; i < 1000; i++) {
+        const val = iter.next().value;
+        if (val !== undefined) this._seenEventIds.delete(val);
+      }
+    }
+  }
+}
+
+module.exports = { GateJiraWatcher };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@anura-gate/watcher-jira",
+  "version": "0.1.0",
+  "description": "GATE Watcher — Self-hosted Jira event monitor. API token never leaves your machine.",
+  "main": "index.js",
+  "bin": {
+    "gate-watcher-jira": "./cli.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "lib/"
+  ],
+  "scripts": {
+    "start": "node cli.js"
+  },
+  "keywords": [
+    "gate",
+    "watcher",
+    "jira",
+    "monitoring",
+    "self-hosted"
+  ],
+  "license": "MIT",
+  "homepage": "https://anuragate.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ahmad-ajmal/AnuraGate_Sample"
+  },
+  "dependencies": {
+    "dotenv": "^17.3.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}