@ever-works/jira-connector-plugin 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +81 -0
- package/dist/index.cjs +518 -0
- package/dist/index.d.cts +224 -0
- package/dist/index.d.ts +224 -0
- package/dist/index.js +502 -0
- package/package.json +125 -0
package/dist/index.js
ADDED
|
@@ -0,0 +1,502 @@
|
|
|
1
|
+
import { randomUUID } from 'crypto';
|
|
2
|
+
import { Version3Client } from 'jira.js';
|
|
3
|
+
import '@ever-works/contracts';
|
|
4
|
+
|
|
5
|
+
// src/jira-connector-plugin.ts
|
|
6
|
+
var EVENT_SOURCE_BACKFILL_MAX_DAYS = 90;
|
|
7
|
+
function clampEventSourceBackfillDays(value, max = EVENT_SOURCE_BACKFILL_MAX_DAYS) {
|
|
8
|
+
const num = typeof value === "number" ? value : Number(value);
|
|
9
|
+
if (!Number.isFinite(num) || num <= 0) return 0;
|
|
10
|
+
return Math.min(Math.floor(num), max);
|
|
11
|
+
}
|
|
12
|
+
var EventSourceNotConfiguredError = class extends Error {
|
|
13
|
+
constructor(message) {
|
|
14
|
+
super(message ?? "Event-source plugin is not configured in this runtime.");
|
|
15
|
+
this.name = "EventSourceNotConfiguredError";
|
|
16
|
+
}
|
|
17
|
+
};
|
|
18
|
+
var PLUGIN_CAPABILITIES = {
|
|
19
|
+
// Connectors ("Connector fabric") — first-party BIDIRECTIONAL
|
|
20
|
+
// communication-channel plugins. Each connector declares `CONNECTOR`
|
|
21
|
+
// (umbrella, for discovery/grouping) plus its `CONNECTOR_<provider>`
|
|
22
|
+
// constant. Superset of the outbound-only notification channels; see
|
|
23
|
+
// `capabilities/connector.interface.ts`.
|
|
24
|
+
CONNECTOR: "connector",
|
|
25
|
+
// Event-ingest spine (Wave 6) — plugins that pull/push normalized
|
|
26
|
+
// external events into the platform ingest pipeline. See
|
|
27
|
+
// capabilities/event-source.interface.ts.
|
|
28
|
+
EVENT_SOURCE: "event-source"};
|
|
29
|
+
|
|
30
|
+
// src/jira-connector-plugin.ts
|
|
31
|
+
var JIRA_EVENT_TEXT_MAX_CHARS = 4e3;
|
|
32
|
+
var JIRA_PULL_PAGE_SIZE = 50;
|
|
33
|
+
var JIRA_BACKFILL_MAX_PAGES = 10;
|
|
34
|
+
var JIRA_ISSUE_FIELDS = [
|
|
35
|
+
"summary",
|
|
36
|
+
"description",
|
|
37
|
+
"created",
|
|
38
|
+
"updated",
|
|
39
|
+
"project",
|
|
40
|
+
"status",
|
|
41
|
+
"issuetype",
|
|
42
|
+
"comment"
|
|
43
|
+
];
|
|
44
|
+
function clampBackfillDays(value) {
|
|
45
|
+
return clampEventSourceBackfillDays(value);
|
|
46
|
+
}
|
|
47
|
+
function truncateText(text) {
|
|
48
|
+
return text.length > JIRA_EVENT_TEXT_MAX_CHARS ? text.slice(0, JIRA_EVENT_TEXT_MAX_CHARS) : text;
|
|
49
|
+
}
|
|
50
|
+
var PRIVATE_HOST_PATTERNS = [
|
|
51
|
+
/^localhost$/i,
|
|
52
|
+
/^127(?:\.\d{1,3}){3}$/,
|
|
53
|
+
/^0\.0\.0\.0$/,
|
|
54
|
+
/^10(?:\.\d{1,3}){3}$/,
|
|
55
|
+
/^192\.168(?:\.\d{1,3}){2}$/,
|
|
56
|
+
/^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/,
|
|
57
|
+
/^169\.254(?:\.\d{1,3}){2}$/,
|
|
58
|
+
/^\[?::1\]?$/,
|
|
59
|
+
/\.local$/i,
|
|
60
|
+
/\.internal$/i
|
|
61
|
+
];
|
|
62
|
+
function normalizeBaseUrl(value) {
|
|
63
|
+
if (typeof value !== "string" || value.trim().length === 0) return void 0;
|
|
64
|
+
let url;
|
|
65
|
+
try {
|
|
66
|
+
url = new URL(value.trim());
|
|
67
|
+
} catch {
|
|
68
|
+
return void 0;
|
|
69
|
+
}
|
|
70
|
+
if (url.protocol !== "https:") return void 0;
|
|
71
|
+
if (url.username.length > 0 || url.password.length > 0) return void 0;
|
|
72
|
+
const host = url.hostname;
|
|
73
|
+
if (host.length === 0) return void 0;
|
|
74
|
+
if (PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(host))) return void 0;
|
|
75
|
+
return url.origin;
|
|
76
|
+
}
|
|
77
|
+
function resolveProjectKeys(settings) {
|
|
78
|
+
const raw = settings?.projectKeys;
|
|
79
|
+
if (typeof raw !== "string" || raw.trim().length === 0) return [];
|
|
80
|
+
return raw.split(",").map((key) => key.trim().toUpperCase()).filter((key) => /^[A-Z][A-Z0-9_]{0,63}$/.test(key));
|
|
81
|
+
}
|
|
82
|
+
function jiraErrorMessage(err) {
|
|
83
|
+
const e = err;
|
|
84
|
+
const apiMessage = e.response?.data?.errorMessages?.[0];
|
|
85
|
+
return apiMessage ?? e.message ?? "unknown error";
|
|
86
|
+
}
|
|
87
|
+
function toIso(value) {
|
|
88
|
+
if (value instanceof Date) return value.toISOString();
|
|
89
|
+
if (typeof value === "string") {
|
|
90
|
+
const ms = Date.parse(value);
|
|
91
|
+
if (Number.isFinite(ms)) return new Date(ms).toISOString();
|
|
92
|
+
}
|
|
93
|
+
return (/* @__PURE__ */ new Date(0)).toISOString();
|
|
94
|
+
}
|
|
95
|
+
function toJqlDateTime(iso) {
|
|
96
|
+
const ms = Date.parse(iso);
|
|
97
|
+
const date = new Date(Number.isFinite(ms) ? ms : 0);
|
|
98
|
+
const pad = (n) => String(n).padStart(2, "0");
|
|
99
|
+
return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(
|
|
100
|
+
date.getUTCHours()
|
|
101
|
+
)}:${pad(date.getUTCMinutes())}`;
|
|
102
|
+
}
|
|
103
|
+
function buildJql(since, projectKeys) {
|
|
104
|
+
const clauses = [`updated >= "${toJqlDateTime(since)}"`];
|
|
105
|
+
if (projectKeys.length > 0) {
|
|
106
|
+
clauses.push(`project in (${projectKeys.join(", ")})`);
|
|
107
|
+
}
|
|
108
|
+
return `${clauses.join(" AND ")} ORDER BY updated ASC`;
|
|
109
|
+
}
|
|
110
|
+
function adfToText(value) {
|
|
111
|
+
if (typeof value === "string") return value;
|
|
112
|
+
if (!value || typeof value !== "object") return "";
|
|
113
|
+
const walk = (node) => {
|
|
114
|
+
if (typeof node.text === "string") return node.text;
|
|
115
|
+
const children = Array.isArray(node.content) ? node.content.map(walk) : [];
|
|
116
|
+
const isBlock = node.type === "paragraph" || node.type === "heading" || node.type === "listItem";
|
|
117
|
+
return isBlock ? `${children.join("")}
|
|
118
|
+
` : children.join("");
|
|
119
|
+
};
|
|
120
|
+
return walk(value).replace(/\n{3,}/g, "\n\n").trim();
|
|
121
|
+
}
|
|
122
|
+
function parsePullCursor(cursor) {
|
|
123
|
+
if (!cursor) return void 0;
|
|
124
|
+
try {
|
|
125
|
+
const parsed = JSON.parse(cursor);
|
|
126
|
+
if (parsed && typeof parsed.s === "string") return parsed;
|
|
127
|
+
} catch {
|
|
128
|
+
}
|
|
129
|
+
return void 0;
|
|
130
|
+
}
|
|
131
|
+
function resolveCredentials(config, settings) {
|
|
132
|
+
const baseUrl = normalizeBaseUrl(config?.baseUrl) ?? normalizeBaseUrl(settings?.baseUrl);
|
|
133
|
+
const emailRaw = config?.email ?? settings?.email;
|
|
134
|
+
const tokenRaw = config?.apiToken ?? settings?.apiToken;
|
|
135
|
+
if (baseUrl && typeof emailRaw === "string" && emailRaw.length > 0 && typeof tokenRaw === "string" && tokenRaw.length > 0) {
|
|
136
|
+
return { baseUrl, email: emailRaw, apiToken: tokenRaw };
|
|
137
|
+
}
|
|
138
|
+
return void 0;
|
|
139
|
+
}
|
|
140
|
+
function resolveIssueKey(config, options) {
|
|
141
|
+
const candidates = [
|
|
142
|
+
config.issueKey,
|
|
143
|
+
config.issueIdOrKey,
|
|
144
|
+
config.defaultIssueKey,
|
|
145
|
+
options.settings?.defaultIssueKey
|
|
146
|
+
];
|
|
147
|
+
for (const c of candidates) {
|
|
148
|
+
if (typeof c === "string" && c.length > 0) return c;
|
|
149
|
+
}
|
|
150
|
+
throw new Error("jira-connector: an issue key is required (targetConfig.issueKey or defaultIssueKey)");
|
|
151
|
+
}
|
|
152
|
+
var JiraConnectorPlugin = class {
|
|
153
|
+
constructor() {
|
|
154
|
+
this.id = "jira-connector";
|
|
155
|
+
this.name = "JIRA Connector";
|
|
156
|
+
this.version = "1.0.0";
|
|
157
|
+
this.category = "connector";
|
|
158
|
+
this.capabilities = [PLUGIN_CAPABILITIES.CONNECTOR, PLUGIN_CAPABILITIES.EVENT_SOURCE];
|
|
159
|
+
this.providerName = "jira";
|
|
160
|
+
this.connector = {
|
|
161
|
+
direction: "outbound",
|
|
162
|
+
transport: "poll",
|
|
163
|
+
flags: {
|
|
164
|
+
outboundMessage: true,
|
|
165
|
+
outboundRecord: false,
|
|
166
|
+
inbound: false,
|
|
167
|
+
reply: false,
|
|
168
|
+
pairing: false,
|
|
169
|
+
richOutbound: false
|
|
170
|
+
}
|
|
171
|
+
};
|
|
172
|
+
this.settingsSchema = {
|
|
173
|
+
type: "object",
|
|
174
|
+
required: ["baseUrl", "email", "apiToken"],
|
|
175
|
+
properties: {
|
|
176
|
+
baseUrl: {
|
|
177
|
+
type: "string",
|
|
178
|
+
title: "JIRA site base URL (https://your-site.atlassian.net)",
|
|
179
|
+
"x-envVar": "JIRA_BASE_URL"
|
|
180
|
+
},
|
|
181
|
+
email: {
|
|
182
|
+
type: "string",
|
|
183
|
+
title: "Atlassian account email (API-token basic auth)",
|
|
184
|
+
"x-envVar": "JIRA_EMAIL"
|
|
185
|
+
},
|
|
186
|
+
apiToken: {
|
|
187
|
+
type: "string",
|
|
188
|
+
title: "Atlassian API token",
|
|
189
|
+
"x-secret": true,
|
|
190
|
+
"x-envVar": "JIRA_API_TOKEN"
|
|
191
|
+
},
|
|
192
|
+
projectKeys: {
|
|
193
|
+
type: "string",
|
|
194
|
+
title: "Project keys to ingest events from (comma-separated; all projects when empty)"
|
|
195
|
+
},
|
|
196
|
+
backfillDays: {
|
|
197
|
+
type: "number",
|
|
198
|
+
title: "Historical backfill window in days on first pull (0 = off, max 90)",
|
|
199
|
+
default: 0,
|
|
200
|
+
minimum: 0,
|
|
201
|
+
maximum: 90
|
|
202
|
+
},
|
|
203
|
+
defaultIssueKey: {
|
|
204
|
+
type: "string",
|
|
205
|
+
title: "Default issue key for outbound comments (e.g. ENG-42)"
|
|
206
|
+
},
|
|
207
|
+
webhookSecret: {
|
|
208
|
+
type: "string",
|
|
209
|
+
title: "Webhook secret",
|
|
210
|
+
description: "Secret set on the Jira Cloud webhook that points at the platform ingest receiver (POST /api/ingest/jira/events). Jira signs every delivery with it (X-Hub-Signature, HMAC SHA-256); deliveries with a missing or mismatched signature are rejected, so a webhook created without a secret never files anything. Leave blank to keep the inbound receiver disabled for your account.",
|
|
211
|
+
"x-secret": true,
|
|
212
|
+
"x-scope": "user",
|
|
213
|
+
"x-widget": "password"
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
};
|
|
217
|
+
this.idempotencyCache = /* @__PURE__ */ new Map();
|
|
218
|
+
}
|
|
219
|
+
async onLoad() {
|
|
220
|
+
}
|
|
221
|
+
async onUnload() {
|
|
222
|
+
this.idempotencyCache.clear();
|
|
223
|
+
}
|
|
224
|
+
/** Testable seam — specs stub this; production uses the real SDK. */
|
|
225
|
+
createClient(credentials) {
|
|
226
|
+
const client = new Version3Client({
|
|
227
|
+
host: credentials.baseUrl,
|
|
228
|
+
authentication: { basic: { email: credentials.email, apiToken: credentials.apiToken } }
|
|
229
|
+
});
|
|
230
|
+
return {
|
|
231
|
+
getCurrentUser: () => client.myself.getCurrentUser(),
|
|
232
|
+
searchIssues: async (params) => await client.issueSearch.searchForIssuesUsingJqlEnhancedSearch({
|
|
233
|
+
jql: params.jql,
|
|
234
|
+
maxResults: params.maxResults,
|
|
235
|
+
fields: params.fields,
|
|
236
|
+
...params.nextPageToken ? { nextPageToken: params.nextPageToken } : {}
|
|
237
|
+
}),
|
|
238
|
+
addComment: (params) => client.issueComments.addComment({ issueIdOrKey: params.issueIdOrKey, comment: params.comment })
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
async verifyConnection(config, options) {
|
|
242
|
+
const credentials = resolveCredentials(config, options.settings);
|
|
243
|
+
if (!credentials) {
|
|
244
|
+
return {
|
|
245
|
+
valid: false,
|
|
246
|
+
message: "baseUrl (https site URL), email and apiToken are required"
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
try {
|
|
250
|
+
const user = await this.createClient(credentials).getCurrentUser();
|
|
251
|
+
return {
|
|
252
|
+
valid: true,
|
|
253
|
+
details: {
|
|
254
|
+
site: credentials.baseUrl,
|
|
255
|
+
accountId: user?.accountId,
|
|
256
|
+
displayName: user?.displayName
|
|
257
|
+
}
|
|
258
|
+
};
|
|
259
|
+
} catch (err) {
|
|
260
|
+
return { valid: false, message: `JIRA current-user lookup failed: ${jiraErrorMessage(err)}` };
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
/** Outbound leg — create a comment on a JIRA issue. */
|
|
264
|
+
async send(payload, options) {
|
|
265
|
+
const config = payload.target ?? options.target ?? {};
|
|
266
|
+
const credentials = resolveCredentials(config, options.settings);
|
|
267
|
+
if (!credentials) {
|
|
268
|
+
throw new Error(
|
|
269
|
+
"jira-connector: baseUrl (https site URL), email and apiToken are required to post a comment"
|
|
270
|
+
);
|
|
271
|
+
}
|
|
272
|
+
const issueKey = resolveIssueKey(config, options);
|
|
273
|
+
const cacheKey = `${options.connectorId ?? ""}\0${issueKey}\0${payload.messageRef}`;
|
|
274
|
+
const cached = this.idempotencyCache.get(cacheKey);
|
|
275
|
+
if (cached) return cached;
|
|
276
|
+
let commentId;
|
|
277
|
+
try {
|
|
278
|
+
const res = await this.createClient(credentials).addComment({
|
|
279
|
+
issueIdOrKey: issueKey,
|
|
280
|
+
comment: payload.text
|
|
281
|
+
});
|
|
282
|
+
commentId = typeof res?.id === "string" ? res.id : void 0;
|
|
283
|
+
} catch (err) {
|
|
284
|
+
throw new Error(`JIRA addComment failed: ${jiraErrorMessage(err)}`);
|
|
285
|
+
}
|
|
286
|
+
const result = {
|
|
287
|
+
provider: this.id,
|
|
288
|
+
providerMessageId: commentId ?? `jira-${payload.messageRef}`,
|
|
289
|
+
deliveredAt: /* @__PURE__ */ new Date()
|
|
290
|
+
};
|
|
291
|
+
this.idempotencyCache.set(cacheKey, result);
|
|
292
|
+
if (this.idempotencyCache.size > 500) {
|
|
293
|
+
const firstKey = this.idempotencyCache.keys().next().value;
|
|
294
|
+
if (firstKey) this.idempotencyCache.delete(firstKey);
|
|
295
|
+
}
|
|
296
|
+
return result;
|
|
297
|
+
}
|
|
298
|
+
// ── Event source (pull) ─────────────────────────────────────────────
|
|
299
|
+
/**
|
|
300
|
+
* Pull one JQL page of issues updated since the effective watermark,
|
|
301
|
+
* normalized to `jira.issue` envelopes plus a `jira.comment` envelope
|
|
302
|
+
* per comment that changed inside the same window. The returned
|
|
303
|
+
* cursor resumes the sweep (API page token); no cursor means the
|
|
304
|
+
* sweep is done.
|
|
305
|
+
*
|
|
306
|
+
* First pull (epoch/absent watermark, no cursor): the window is
|
|
307
|
+
* `now - backfillDays` when the opt-in backfill is on, otherwise
|
|
308
|
+
* `now` — history stays untouched unless the user asked for it.
|
|
309
|
+
*/
|
|
310
|
+
async pullEvents(input) {
|
|
311
|
+
const credentials = resolveCredentials(void 0, input.settings);
|
|
312
|
+
if (!credentials) {
|
|
313
|
+
throw new EventSourceNotConfiguredError(
|
|
314
|
+
"jira-connector: settings.baseUrl (https site URL), settings.email and settings.apiToken are required to pull events"
|
|
315
|
+
);
|
|
316
|
+
}
|
|
317
|
+
const cursor = parsePullCursor(input.cursor);
|
|
318
|
+
let pageToken;
|
|
319
|
+
let since;
|
|
320
|
+
let backfill;
|
|
321
|
+
let pagesUsed;
|
|
322
|
+
if (cursor) {
|
|
323
|
+
pageToken = cursor.n;
|
|
324
|
+
since = cursor.s;
|
|
325
|
+
backfill = cursor.f === 1;
|
|
326
|
+
pagesUsed = cursor.b ?? 0;
|
|
327
|
+
} else {
|
|
328
|
+
const sinceMs = Date.parse(input.since);
|
|
329
|
+
const firstPull = !Number.isFinite(sinceMs) || sinceMs <= 0;
|
|
330
|
+
const backfillDays = clampBackfillDays(input.settings?.backfillDays);
|
|
331
|
+
if (firstPull) {
|
|
332
|
+
const start = backfillDays > 0 ? Date.now() - backfillDays * 864e5 : Date.now();
|
|
333
|
+
since = new Date(start).toISOString();
|
|
334
|
+
backfill = backfillDays > 0;
|
|
335
|
+
} else {
|
|
336
|
+
since = new Date(sinceMs).toISOString();
|
|
337
|
+
backfill = false;
|
|
338
|
+
}
|
|
339
|
+
pageToken = void 0;
|
|
340
|
+
pagesUsed = 0;
|
|
341
|
+
}
|
|
342
|
+
const client = this.createClient(credentials);
|
|
343
|
+
const projectKeys = resolveProjectKeys(input.settings);
|
|
344
|
+
const page = await client.searchIssues({
|
|
345
|
+
jql: buildJql(since, projectKeys),
|
|
346
|
+
maxResults: JIRA_PULL_PAGE_SIZE,
|
|
347
|
+
fields: [...JIRA_ISSUE_FIELDS],
|
|
348
|
+
...pageToken ? { nextPageToken: pageToken } : {}
|
|
349
|
+
});
|
|
350
|
+
const events = [];
|
|
351
|
+
for (const issue of page.issues ?? []) {
|
|
352
|
+
const issueEnvelope = this.normalizeIssue(issue, since, credentials.baseUrl);
|
|
353
|
+
if (issueEnvelope) events.push(issueEnvelope);
|
|
354
|
+
for (const comment of issue.fields?.comment?.comments ?? []) {
|
|
355
|
+
const commentEnvelope = this.normalizeComment(issue, comment, since, credentials.baseUrl);
|
|
356
|
+
if (commentEnvelope) events.push(commentEnvelope);
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
pagesUsed += 1;
|
|
360
|
+
const pageBudgetExhausted = backfill && pagesUsed >= JIRA_BACKFILL_MAX_PAGES;
|
|
361
|
+
const nextPageToken = typeof page.nextPageToken === "string" && page.nextPageToken.length > 0 ? page.nextPageToken : void 0;
|
|
362
|
+
const next = nextPageToken && !pageBudgetExhausted ? { n: nextPageToken, s: since, ...backfill ? { f: 1 } : {}, b: pagesUsed } : void 0;
|
|
363
|
+
return next ? { events, nextCursor: JSON.stringify(next) } : { events };
|
|
364
|
+
}
|
|
365
|
+
/**
|
|
366
|
+
* Bounded HISTORICAL sweep from an explicit `since` — the
|
|
367
|
+
* capability's opt-in `backfill()` method.
|
|
368
|
+
*
|
|
369
|
+
* Before this method existed, history was reachable only as a side
|
|
370
|
+
* effect of the FIRST pull (`settings.backfillDays` widening the
|
|
371
|
+
* initial window), so a user who activated the connector without the
|
|
372
|
+
* setting could never go back and fetch it. `backfill()` runs the
|
|
373
|
+
* same JQL sweep out-of-band on a caller-chosen window, as many times
|
|
374
|
+
* as wanted — re-delivery is free because the ingest pipeline dedupes
|
|
375
|
+
* on `(source, sourceEventId)`.
|
|
376
|
+
*
|
|
377
|
+
* `until` is accepted for contract symmetry but NOT applied: the
|
|
378
|
+
* sweep's JQL bounds only the near end (`updated >= since`). An
|
|
379
|
+
* over-wide window costs duplicate deliveries, which the pipeline
|
|
380
|
+
* drops — never wrong data.
|
|
381
|
+
*
|
|
382
|
+
* The page bound (`JIRA_BACKFILL_MAX_PAGES`) applies here too: one
|
|
383
|
+
* call fetches ONE page and hands back a cursor, so a large project
|
|
384
|
+
* can never turn a backfill into an unbounded crawl.
|
|
385
|
+
*/
|
|
386
|
+
async backfill(input) {
|
|
387
|
+
const sinceMs = Date.parse(input.since);
|
|
388
|
+
if (!Number.isFinite(sinceMs)) {
|
|
389
|
+
throw new EventSourceNotConfiguredError(
|
|
390
|
+
`jira-connector: backfill requires a valid ISO 8601 "since" (received ${JSON.stringify(input.since)})`
|
|
391
|
+
);
|
|
392
|
+
}
|
|
393
|
+
const cursor = input.cursor ?? JSON.stringify({
|
|
394
|
+
s: new Date(sinceMs).toISOString(),
|
|
395
|
+
f: 1,
|
|
396
|
+
b: 0
|
|
397
|
+
});
|
|
398
|
+
const page = await this.pullEvents({
|
|
399
|
+
since: input.since,
|
|
400
|
+
cursor,
|
|
401
|
+
...input.settings ? { settings: input.settings } : {}
|
|
402
|
+
});
|
|
403
|
+
return page.nextCursor ? { events: page.events, nextCursor: page.nextCursor } : { events: page.events, complete: true };
|
|
404
|
+
}
|
|
405
|
+
normalizeIssue(issue, since, baseUrl) {
|
|
406
|
+
if (!issue.id) return null;
|
|
407
|
+
const fields = issue.fields ?? {};
|
|
408
|
+
const updatedAt = toIso(fields.updated ?? fields.created);
|
|
409
|
+
const createdAt = toIso(fields.created);
|
|
410
|
+
const changeType = Date.parse(createdAt) >= Date.parse(since) ? "created" : "updated";
|
|
411
|
+
const projectKey = fields.project?.key;
|
|
412
|
+
const description = adfToText(fields.description);
|
|
413
|
+
return {
|
|
414
|
+
id: randomUUID(),
|
|
415
|
+
source: this.id,
|
|
416
|
+
sourceEventId: `${issue.id}:${updatedAt}`,
|
|
417
|
+
kind: "jira.issue",
|
|
418
|
+
occurredAt: updatedAt,
|
|
419
|
+
subject: {
|
|
420
|
+
type: "issue",
|
|
421
|
+
externalId: issue.id,
|
|
422
|
+
...fields.summary ? { title: fields.summary } : {}
|
|
423
|
+
},
|
|
424
|
+
// Work routing: the project is the container an Ever Works Work
|
|
425
|
+
// maps onto. Issues without a project stay user-scoped.
|
|
426
|
+
...projectKey ? {
|
|
427
|
+
workHint: {
|
|
428
|
+
kind: "tracker-team",
|
|
429
|
+
externalId: projectKey,
|
|
430
|
+
...fields.project?.name ? { label: fields.project.name } : {}
|
|
431
|
+
}
|
|
432
|
+
} : {},
|
|
433
|
+
...issue.key ? { sourceUrl: `${baseUrl}/browse/${issue.key}` } : {},
|
|
434
|
+
payload: {
|
|
435
|
+
issueId: issue.id,
|
|
436
|
+
...issue.key ? { issueKey: issue.key } : {},
|
|
437
|
+
...projectKey ? { projectKey } : {},
|
|
438
|
+
...fields.summary ? { summary: truncateText(fields.summary) } : {},
|
|
439
|
+
...description ? { description: truncateText(description) } : {},
|
|
440
|
+
...fields.status?.name ? { status: fields.status.name } : {},
|
|
441
|
+
...fields.issuetype?.name ? { issueType: fields.issuetype.name } : {},
|
|
442
|
+
changeType,
|
|
443
|
+
createdAt,
|
|
444
|
+
updatedAt
|
|
445
|
+
}
|
|
446
|
+
};
|
|
447
|
+
}
|
|
448
|
+
/**
|
|
449
|
+
* Normalize one comment → envelope, or null when the comment did NOT
|
|
450
|
+
* change inside the sweep window. Commenting bumps the parent issue's
|
|
451
|
+
* `updated`, so an issue can arrive with a long comment history of
|
|
452
|
+
* which only the newest entry is actually news.
|
|
453
|
+
*/
|
|
454
|
+
normalizeComment(issue, comment, since, baseUrl) {
|
|
455
|
+
if (!comment.id) return null;
|
|
456
|
+
const updatedAt = toIso(comment.updated ?? comment.created);
|
|
457
|
+
if (Date.parse(updatedAt) < Date.parse(since)) return null;
|
|
458
|
+
const fields = issue.fields ?? {};
|
|
459
|
+
const projectKey = fields.project?.key;
|
|
460
|
+
const body = adfToText(comment.body);
|
|
461
|
+
const sourceUrl = issue.key ? `${baseUrl}/browse/${issue.key}?focusedCommentId=${encodeURIComponent(comment.id)}` : void 0;
|
|
462
|
+
return {
|
|
463
|
+
id: randomUUID(),
|
|
464
|
+
source: this.id,
|
|
465
|
+
sourceEventId: `${comment.id}:${updatedAt}`,
|
|
466
|
+
kind: "jira.comment",
|
|
467
|
+
occurredAt: updatedAt,
|
|
468
|
+
...comment.author?.displayName ? {
|
|
469
|
+
actor: {
|
|
470
|
+
name: comment.author.displayName,
|
|
471
|
+
...comment.author.accountId ? { externalId: comment.author.accountId } : {}
|
|
472
|
+
}
|
|
473
|
+
} : {},
|
|
474
|
+
subject: {
|
|
475
|
+
type: "issue",
|
|
476
|
+
externalId: issue.id ?? "unknown",
|
|
477
|
+
...fields.summary ? { title: fields.summary } : {}
|
|
478
|
+
},
|
|
479
|
+
// Same project-as-container routing as issues.
|
|
480
|
+
...projectKey ? {
|
|
481
|
+
workHint: {
|
|
482
|
+
kind: "tracker-team",
|
|
483
|
+
externalId: projectKey,
|
|
484
|
+
...fields.project?.name ? { label: fields.project.name } : {}
|
|
485
|
+
}
|
|
486
|
+
} : {},
|
|
487
|
+
...sourceUrl ? { sourceUrl } : {},
|
|
488
|
+
payload: {
|
|
489
|
+
commentId: comment.id,
|
|
490
|
+
...issue.id ? { issueId: issue.id } : {},
|
|
491
|
+
...issue.key ? { issueKey: issue.key } : {},
|
|
492
|
+
...projectKey ? { projectKey } : {},
|
|
493
|
+
...body ? { body: truncateText(body) } : {},
|
|
494
|
+
createdAt: toIso(comment.created),
|
|
495
|
+
updatedAt
|
|
496
|
+
}
|
|
497
|
+
};
|
|
498
|
+
}
|
|
499
|
+
};
|
|
500
|
+
var jiraConnectorPlugin = new JiraConnectorPlugin();
|
|
501
|
+
|
|
502
|
+
export { JIRA_BACKFILL_MAX_PAGES, JIRA_EVENT_TEXT_MAX_CHARS, JIRA_ISSUE_FIELDS, JIRA_PULL_PAGE_SIZE, JiraConnectorPlugin, adfToText, buildJql, clampBackfillDays, JiraConnectorPlugin as default, jiraConnectorPlugin, normalizeBaseUrl, resolveProjectKeys, toJqlDateTime };
|
package/package.json
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@ever-works/jira-connector-plugin",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "JIRA connector plugin for Ever Works platform (outbound issue comments via jira.js and event-source pull of issues/comments into the event-ingest pipeline, with opt-in historical backfill)",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "Ever Co. LTD",
|
|
7
|
+
"email": "ever@ever.co",
|
|
8
|
+
"url": "https://ever.co"
|
|
9
|
+
},
|
|
10
|
+
"license": "AGPL-3.0",
|
|
11
|
+
"private": false,
|
|
12
|
+
"type": "module",
|
|
13
|
+
"main": "./dist/index.cjs",
|
|
14
|
+
"module": "./dist/index.js",
|
|
15
|
+
"types": "./dist/index.d.ts",
|
|
16
|
+
"exports": {
|
|
17
|
+
".": {
|
|
18
|
+
"types": "./dist/index.d.ts",
|
|
19
|
+
"import": "./dist/index.js",
|
|
20
|
+
"require": "./dist/index.cjs"
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"files": [
|
|
24
|
+
"dist"
|
|
25
|
+
],
|
|
26
|
+
"scripts": {
|
|
27
|
+
"build": "tsc --noEmit && tsup",
|
|
28
|
+
"dev": "tsup --watch",
|
|
29
|
+
"clean": "rm -rf dist",
|
|
30
|
+
"type-check": "tsc --noEmit",
|
|
31
|
+
"test": "vitest run",
|
|
32
|
+
"test:watch": "vitest"
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"@ever-works/contracts": "^1.0.0",
|
|
36
|
+
"@ever-works/plugin": "^1.2.0",
|
|
37
|
+
"jira.js": "^5.4.0"
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@types/node": "^22.0.0",
|
|
41
|
+
"tsup": "^8.0.0",
|
|
42
|
+
"typescript": "^5.9.3",
|
|
43
|
+
"vitest": "^4.1.0"
|
|
44
|
+
},
|
|
45
|
+
"everworks": {
|
|
46
|
+
"plugin": {
|
|
47
|
+
"id": "jira-connector",
|
|
48
|
+
"name": "JIRA Connector",
|
|
49
|
+
"version": "1.0.0",
|
|
50
|
+
"category": "connector",
|
|
51
|
+
"capabilities": [
|
|
52
|
+
"connector",
|
|
53
|
+
"event-source"
|
|
54
|
+
],
|
|
55
|
+
"description": "JIRA connector. Outbound posts comments on JIRA issues via the jira.js Cloud REST client. Event-source pull ingests issues (created/updated) and comments since the last watermark into the platform event-ingest pipeline, with opt-in historical backfill (backfillDays, max 90).",
|
|
56
|
+
"systemPlugin": false,
|
|
57
|
+
"builtIn": true,
|
|
58
|
+
"isDefault": false,
|
|
59
|
+
"autoEnable": false,
|
|
60
|
+
"settings": {
|
|
61
|
+
"type": "object",
|
|
62
|
+
"required": [
|
|
63
|
+
"baseUrl",
|
|
64
|
+
"email",
|
|
65
|
+
"apiToken"
|
|
66
|
+
],
|
|
67
|
+
"properties": {
|
|
68
|
+
"baseUrl": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"title": "JIRA site base URL (https://your-site.atlassian.net)",
|
|
71
|
+
"x-envVar": "JIRA_BASE_URL"
|
|
72
|
+
},
|
|
73
|
+
"email": {
|
|
74
|
+
"type": "string",
|
|
75
|
+
"title": "Atlassian account email (API-token basic auth)",
|
|
76
|
+
"x-envVar": "JIRA_EMAIL"
|
|
77
|
+
},
|
|
78
|
+
"apiToken": {
|
|
79
|
+
"type": "string",
|
|
80
|
+
"title": "Atlassian API token",
|
|
81
|
+
"x-secret": true,
|
|
82
|
+
"x-envVar": "JIRA_API_TOKEN"
|
|
83
|
+
},
|
|
84
|
+
"projectKeys": {
|
|
85
|
+
"type": "string",
|
|
86
|
+
"title": "Project keys to ingest events from (comma-separated; all projects when empty)"
|
|
87
|
+
},
|
|
88
|
+
"backfillDays": {
|
|
89
|
+
"type": "number",
|
|
90
|
+
"title": "Historical backfill window in days on first pull (0 = off, max 90)",
|
|
91
|
+
"default": 0,
|
|
92
|
+
"minimum": 0,
|
|
93
|
+
"maximum": 90
|
|
94
|
+
},
|
|
95
|
+
"defaultIssueKey": {
|
|
96
|
+
"type": "string",
|
|
97
|
+
"title": "Default issue key for outbound comments (e.g. ENG-42)"
|
|
98
|
+
},
|
|
99
|
+
"webhookSecret": {
|
|
100
|
+
"type": "string",
|
|
101
|
+
"title": "Webhook secret",
|
|
102
|
+
"description": "Secret set on the Jira Cloud webhook that points at the platform ingest receiver (POST /api/ingest/jira/events). Jira signs every delivery with it (X-Hub-Signature, HMAC SHA-256); deliveries with a missing or mismatched signature are rejected, so a webhook created without a secret never files anything. Leave blank to keep the inbound receiver disabled for your account.",
|
|
103
|
+
"x-secret": true,
|
|
104
|
+
"x-scope": "user",
|
|
105
|
+
"x-widget": "password"
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
},
|
|
111
|
+
"repository": {
|
|
112
|
+
"type": "git",
|
|
113
|
+
"url": "git+https://github.com/ever-works/ever-works.git",
|
|
114
|
+
"directory": "packages/plugins/jira-connector"
|
|
115
|
+
},
|
|
116
|
+
"homepage": "https://github.com/ever-works/ever-works/tree/main/packages/plugins/jira-connector#readme",
|
|
117
|
+
"bugs": {
|
|
118
|
+
"url": "https://github.com/ever-works/ever-works/issues"
|
|
119
|
+
},
|
|
120
|
+
"everworksRelease": {
|
|
121
|
+
"contentHash": "sha256:90bee45397aaa182a5d6d78b6766dbeff84fd5c9e0a6efafafad0a7aa8855289",
|
|
122
|
+
"commit": "6628882fbf102716a412f7d9a66d8387bd6a784c",
|
|
123
|
+
"source": "https://github.com/ever-works/ever-works/tree/6628882fbf102716a412f7d9a66d8387bd6a784c/packages/plugins/jira-connector"
|
|
124
|
+
}
|
|
125
|
+
}
|