@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.
@@ -0,0 +1,224 @@
1
+ import { IConnectorPlugin, IEventSourcePlugin, PluginCategory, ConnectorMetadata, JsonSchema, ChannelTargetConfig, ConnectorCallOptions, ChannelVerification, ChannelSendInput, ChannelSendResult, EventSourcePullInput, EventSourcePullResult, EventSourceBackfillInput, EventSourceBackfillResult, PluginSettings } from '@ever-works/plugin';
2
+
3
+ /**
4
+ * Payload text cap for ingested envelopes. Envelope payloads are
5
+ * size-capped platform-side (32 KB serialized); issue descriptions and
6
+ * comment bodies never need more than this to be useful in
7
+ * Memory/Activities.
8
+ */
9
+ declare const JIRA_EVENT_TEXT_MAX_CHARS = 4000;
10
+ /** Issues requested per JQL page. */
11
+ declare const JIRA_PULL_PAGE_SIZE = 50;
12
+ /**
13
+ * Historical backfill bound: at most this many pages during the opt-in
14
+ * first-pull backfill, so a large site can never turn activation into an
15
+ * unbounded crawl.
16
+ */
17
+ declare const JIRA_BACKFILL_MAX_PAGES = 10;
18
+ /** Fields requested per issue — comments ride along (see the class doc). */
19
+ declare const JIRA_ISSUE_FIELDS: readonly ["summary", "description", "created", "updated", "project", "status", "issuetype", "comment"];
20
+ /**
21
+ * Clamp the opt-in backfill window to the supported 0–90 day range.
22
+ *
23
+ * Delegates to the shared capability helper so the bound is stated once
24
+ * for the whole connector fabric; the local export stays because it is
25
+ * part of this plugin's published surface.
26
+ */
27
+ declare function clampBackfillDays(value: unknown): number;
28
+ /**
29
+ * Validate + normalize the configured site URL. Returns the origin (no
30
+ * path, no credentials) or `undefined` when the value is unusable.
31
+ */
32
+ declare function normalizeBaseUrl(value: unknown): string | undefined;
33
+ /**
34
+ * Parse the project filter list. JQL is a query language and these keys
35
+ * are interpolated into it, so each entry is whitelisted against JIRA's
36
+ * own project-key alphabet rather than escaped — anything else is
37
+ * dropped. Splitting is comma-only (NOT whitespace, unlike the sibling
38
+ * connectors whose ids are opaque request parameters): a tampered entry
39
+ * such as `ENG) OR (1=1` must fail validation as a whole rather than
40
+ * shed its punctuation and smuggle a bare `OR` through.
41
+ */
42
+ declare function resolveProjectKeys(settings: PluginSettings | undefined): string[];
43
+ /**
44
+ * ISO instant → the `yyyy-MM-dd HH:mm` literal JQL accepts.
45
+ *
46
+ * JQL evaluates bare date literals in the SITE's timezone while the
47
+ * platform watermark is UTC, so the rendered window can be off by the
48
+ * site's UTC offset. That is deliberate and safe in both directions:
49
+ * dedupe is `(source, sourceEventId)`, so an over-wide window costs one
50
+ * extra page and drops nothing, and each envelope re-checks `since`
51
+ * itself before a comment is emitted.
52
+ */
53
+ declare function toJqlDateTime(iso: string): string;
54
+ /** Build the bounded, ordered JQL the sweep runs. */
55
+ declare function buildJql(since: string, projectKeys: string[]): string;
56
+ /**
57
+ * ADF document → plain text. JIRA Cloud's v3 API returns rich text as
58
+ * an Atlassian Document Format tree; envelopes carry plain text so
59
+ * Memory/Activity rows stay readable. Block nodes are newline-joined,
60
+ * inline nodes space-free-concatenated.
61
+ */
62
+ declare function adfToText(value: unknown): string;
63
+ /** Minimal scalar shape of a comment node we consume. */
64
+ interface JiraCommentNode {
65
+ id?: string;
66
+ body?: unknown;
67
+ created?: string;
68
+ updated?: string;
69
+ author?: {
70
+ displayName?: string;
71
+ accountId?: string;
72
+ };
73
+ }
74
+ /** Minimal scalar shape of an issue node we consume. */
75
+ interface JiraIssueNode {
76
+ id?: string;
77
+ key?: string;
78
+ fields?: {
79
+ summary?: string;
80
+ description?: unknown;
81
+ created?: string;
82
+ updated?: string;
83
+ project?: {
84
+ key?: string;
85
+ name?: string;
86
+ id?: string;
87
+ };
88
+ status?: {
89
+ name?: string;
90
+ };
91
+ issuetype?: {
92
+ name?: string;
93
+ };
94
+ comment?: {
95
+ comments?: JiraCommentNode[];
96
+ };
97
+ };
98
+ }
99
+ interface JiraSearchPage {
100
+ issues?: JiraIssueNode[];
101
+ nextPageToken?: string;
102
+ }
103
+ /** The subset of the `jira.js` surface this plugin calls (testable seam). */
104
+ interface JiraClientLike {
105
+ getCurrentUser(): Promise<{
106
+ accountId?: string;
107
+ displayName?: string;
108
+ emailAddress?: string;
109
+ }>;
110
+ searchIssues(params: {
111
+ jql: string;
112
+ maxResults: number;
113
+ fields: string[];
114
+ nextPageToken?: string;
115
+ }): Promise<JiraSearchPage>;
116
+ addComment(params: {
117
+ issueIdOrKey: string;
118
+ comment: string;
119
+ }): Promise<{
120
+ id?: string;
121
+ }>;
122
+ }
123
+ interface JiraCredentials {
124
+ baseUrl: string;
125
+ email: string;
126
+ apiToken: string;
127
+ }
128
+ /**
129
+ * JIRA connector (Wave 8) — first-party native connector.
130
+ *
131
+ * Outbound: posts comments on JIRA Cloud issues via `addComment` on the
132
+ * `jira.js` client (API-token basic auth; the SDK renders a plain-text
133
+ * comment into Atlassian Document Format for the v3 API).
134
+ *
135
+ * Vendor-SDK note: Atlassian publishes **no** maintained first-party
136
+ * Node client for the Jira Cloud REST API — the Atlassian Labs
137
+ * `@atlassian/jira` package stopped at `0.1.0` and has had no release
138
+ * since 2018, and `@forge/api` only works inside a Forge app runtime.
139
+ * `jira.js` is the actively maintained (released weekly), TypeScript-
140
+ * native Jira Cloud client and is what this connector builds on.
141
+ *
142
+ * Event source: `pullEvents` sweeps issues updated since the watermark
143
+ * with one bounded JQL query per page, normalized into
144
+ * `IngestedEventEnvelope`s (`jira.issue` / `jira.comment`, the issue's
145
+ * browse URL as `sourceUrl`). Unlike the sibling trackers, JIRA has no
146
+ * "all comments" endpoint — comments only exist under an issue — so the
147
+ * sweep requests the `comment` field alongside the issue and emits a
148
+ * `jira.comment` envelope for every comment that itself changed inside
149
+ * the window. That keeps a page at ONE API call instead of one per
150
+ * issue, and an issue whose only change is a new comment is already in
151
+ * the result set because commenting bumps `updated`.
152
+ *
153
+ * Work routing: the project is the container an Ever Works Work maps
154
+ * onto, emitted as a `tracker-team` `workHint` keyed on the project key.
155
+ *
156
+ * The opt-in historical backfill (`backfillDays`, default 0 = off, max
157
+ * 90) widens the FIRST pull's window only, with a page bound so
158
+ * activation never becomes an unbounded crawl. Re-delivery across
159
+ * overlapping windows is fine — the ingest pipeline dedupes on
160
+ * `(source, sourceEventId)`.
161
+ */
162
+ declare class JiraConnectorPlugin implements IConnectorPlugin, IEventSourcePlugin {
163
+ readonly id = "jira-connector";
164
+ readonly name = "JIRA Connector";
165
+ readonly version = "1.0.0";
166
+ readonly category: PluginCategory;
167
+ readonly capabilities: readonly ["connector", "event-source"];
168
+ readonly providerName = "jira";
169
+ readonly connector: ConnectorMetadata;
170
+ readonly settingsSchema: JsonSchema;
171
+ private readonly idempotencyCache;
172
+ onLoad(): Promise<void>;
173
+ onUnload(): Promise<void>;
174
+ /** Testable seam — specs stub this; production uses the real SDK. */
175
+ protected createClient(credentials: JiraCredentials): JiraClientLike;
176
+ verifyConnection(config: ChannelTargetConfig, options: ConnectorCallOptions): Promise<ChannelVerification>;
177
+ /** Outbound leg — create a comment on a JIRA issue. */
178
+ send(payload: ChannelSendInput, options: ConnectorCallOptions): Promise<ChannelSendResult>;
179
+ /**
180
+ * Pull one JQL page of issues updated since the effective watermark,
181
+ * normalized to `jira.issue` envelopes plus a `jira.comment` envelope
182
+ * per comment that changed inside the same window. The returned
183
+ * cursor resumes the sweep (API page token); no cursor means the
184
+ * sweep is done.
185
+ *
186
+ * First pull (epoch/absent watermark, no cursor): the window is
187
+ * `now - backfillDays` when the opt-in backfill is on, otherwise
188
+ * `now` — history stays untouched unless the user asked for it.
189
+ */
190
+ pullEvents(input: EventSourcePullInput): Promise<EventSourcePullResult>;
191
+ /**
192
+ * Bounded HISTORICAL sweep from an explicit `since` — the
193
+ * capability's opt-in `backfill()` method.
194
+ *
195
+ * Before this method existed, history was reachable only as a side
196
+ * effect of the FIRST pull (`settings.backfillDays` widening the
197
+ * initial window), so a user who activated the connector without the
198
+ * setting could never go back and fetch it. `backfill()` runs the
199
+ * same JQL sweep out-of-band on a caller-chosen window, as many times
200
+ * as wanted — re-delivery is free because the ingest pipeline dedupes
201
+ * on `(source, sourceEventId)`.
202
+ *
203
+ * `until` is accepted for contract symmetry but NOT applied: the
204
+ * sweep's JQL bounds only the near end (`updated >= since`). An
205
+ * over-wide window costs duplicate deliveries, which the pipeline
206
+ * drops — never wrong data.
207
+ *
208
+ * The page bound (`JIRA_BACKFILL_MAX_PAGES`) applies here too: one
209
+ * call fetches ONE page and hands back a cursor, so a large project
210
+ * can never turn a backfill into an unbounded crawl.
211
+ */
212
+ backfill(input: EventSourceBackfillInput): Promise<EventSourceBackfillResult>;
213
+ private normalizeIssue;
214
+ /**
215
+ * Normalize one comment → envelope, or null when the comment did NOT
216
+ * change inside the sweep window. Commenting bumps the parent issue's
217
+ * `updated`, so an issue can arrive with a long comment history of
218
+ * which only the newest entry is actually news.
219
+ */
220
+ private normalizeComment;
221
+ }
222
+ declare const jiraConnectorPlugin: JiraConnectorPlugin;
223
+
224
+ 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 };
@@ -0,0 +1,224 @@
1
+ import { IConnectorPlugin, IEventSourcePlugin, PluginCategory, ConnectorMetadata, JsonSchema, ChannelTargetConfig, ConnectorCallOptions, ChannelVerification, ChannelSendInput, ChannelSendResult, EventSourcePullInput, EventSourcePullResult, EventSourceBackfillInput, EventSourceBackfillResult, PluginSettings } from '@ever-works/plugin';
2
+
3
+ /**
4
+ * Payload text cap for ingested envelopes. Envelope payloads are
5
+ * size-capped platform-side (32 KB serialized); issue descriptions and
6
+ * comment bodies never need more than this to be useful in
7
+ * Memory/Activities.
8
+ */
9
+ declare const JIRA_EVENT_TEXT_MAX_CHARS = 4000;
10
+ /** Issues requested per JQL page. */
11
+ declare const JIRA_PULL_PAGE_SIZE = 50;
12
+ /**
13
+ * Historical backfill bound: at most this many pages during the opt-in
14
+ * first-pull backfill, so a large site can never turn activation into an
15
+ * unbounded crawl.
16
+ */
17
+ declare const JIRA_BACKFILL_MAX_PAGES = 10;
18
+ /** Fields requested per issue — comments ride along (see the class doc). */
19
+ declare const JIRA_ISSUE_FIELDS: readonly ["summary", "description", "created", "updated", "project", "status", "issuetype", "comment"];
20
+ /**
21
+ * Clamp the opt-in backfill window to the supported 0–90 day range.
22
+ *
23
+ * Delegates to the shared capability helper so the bound is stated once
24
+ * for the whole connector fabric; the local export stays because it is
25
+ * part of this plugin's published surface.
26
+ */
27
+ declare function clampBackfillDays(value: unknown): number;
28
+ /**
29
+ * Validate + normalize the configured site URL. Returns the origin (no
30
+ * path, no credentials) or `undefined` when the value is unusable.
31
+ */
32
+ declare function normalizeBaseUrl(value: unknown): string | undefined;
33
+ /**
34
+ * Parse the project filter list. JQL is a query language and these keys
35
+ * are interpolated into it, so each entry is whitelisted against JIRA's
36
+ * own project-key alphabet rather than escaped — anything else is
37
+ * dropped. Splitting is comma-only (NOT whitespace, unlike the sibling
38
+ * connectors whose ids are opaque request parameters): a tampered entry
39
+ * such as `ENG) OR (1=1` must fail validation as a whole rather than
40
+ * shed its punctuation and smuggle a bare `OR` through.
41
+ */
42
+ declare function resolveProjectKeys(settings: PluginSettings | undefined): string[];
43
+ /**
44
+ * ISO instant → the `yyyy-MM-dd HH:mm` literal JQL accepts.
45
+ *
46
+ * JQL evaluates bare date literals in the SITE's timezone while the
47
+ * platform watermark is UTC, so the rendered window can be off by the
48
+ * site's UTC offset. That is deliberate and safe in both directions:
49
+ * dedupe is `(source, sourceEventId)`, so an over-wide window costs one
50
+ * extra page and drops nothing, and each envelope re-checks `since`
51
+ * itself before a comment is emitted.
52
+ */
53
+ declare function toJqlDateTime(iso: string): string;
54
+ /** Build the bounded, ordered JQL the sweep runs. */
55
+ declare function buildJql(since: string, projectKeys: string[]): string;
56
+ /**
57
+ * ADF document → plain text. JIRA Cloud's v3 API returns rich text as
58
+ * an Atlassian Document Format tree; envelopes carry plain text so
59
+ * Memory/Activity rows stay readable. Block nodes are newline-joined,
60
+ * inline nodes space-free-concatenated.
61
+ */
62
+ declare function adfToText(value: unknown): string;
63
+ /** Minimal scalar shape of a comment node we consume. */
64
+ interface JiraCommentNode {
65
+ id?: string;
66
+ body?: unknown;
67
+ created?: string;
68
+ updated?: string;
69
+ author?: {
70
+ displayName?: string;
71
+ accountId?: string;
72
+ };
73
+ }
74
+ /** Minimal scalar shape of an issue node we consume. */
75
+ interface JiraIssueNode {
76
+ id?: string;
77
+ key?: string;
78
+ fields?: {
79
+ summary?: string;
80
+ description?: unknown;
81
+ created?: string;
82
+ updated?: string;
83
+ project?: {
84
+ key?: string;
85
+ name?: string;
86
+ id?: string;
87
+ };
88
+ status?: {
89
+ name?: string;
90
+ };
91
+ issuetype?: {
92
+ name?: string;
93
+ };
94
+ comment?: {
95
+ comments?: JiraCommentNode[];
96
+ };
97
+ };
98
+ }
99
+ interface JiraSearchPage {
100
+ issues?: JiraIssueNode[];
101
+ nextPageToken?: string;
102
+ }
103
+ /** The subset of the `jira.js` surface this plugin calls (testable seam). */
104
+ interface JiraClientLike {
105
+ getCurrentUser(): Promise<{
106
+ accountId?: string;
107
+ displayName?: string;
108
+ emailAddress?: string;
109
+ }>;
110
+ searchIssues(params: {
111
+ jql: string;
112
+ maxResults: number;
113
+ fields: string[];
114
+ nextPageToken?: string;
115
+ }): Promise<JiraSearchPage>;
116
+ addComment(params: {
117
+ issueIdOrKey: string;
118
+ comment: string;
119
+ }): Promise<{
120
+ id?: string;
121
+ }>;
122
+ }
123
+ interface JiraCredentials {
124
+ baseUrl: string;
125
+ email: string;
126
+ apiToken: string;
127
+ }
128
+ /**
129
+ * JIRA connector (Wave 8) — first-party native connector.
130
+ *
131
+ * Outbound: posts comments on JIRA Cloud issues via `addComment` on the
132
+ * `jira.js` client (API-token basic auth; the SDK renders a plain-text
133
+ * comment into Atlassian Document Format for the v3 API).
134
+ *
135
+ * Vendor-SDK note: Atlassian publishes **no** maintained first-party
136
+ * Node client for the Jira Cloud REST API — the Atlassian Labs
137
+ * `@atlassian/jira` package stopped at `0.1.0` and has had no release
138
+ * since 2018, and `@forge/api` only works inside a Forge app runtime.
139
+ * `jira.js` is the actively maintained (released weekly), TypeScript-
140
+ * native Jira Cloud client and is what this connector builds on.
141
+ *
142
+ * Event source: `pullEvents` sweeps issues updated since the watermark
143
+ * with one bounded JQL query per page, normalized into
144
+ * `IngestedEventEnvelope`s (`jira.issue` / `jira.comment`, the issue's
145
+ * browse URL as `sourceUrl`). Unlike the sibling trackers, JIRA has no
146
+ * "all comments" endpoint — comments only exist under an issue — so the
147
+ * sweep requests the `comment` field alongside the issue and emits a
148
+ * `jira.comment` envelope for every comment that itself changed inside
149
+ * the window. That keeps a page at ONE API call instead of one per
150
+ * issue, and an issue whose only change is a new comment is already in
151
+ * the result set because commenting bumps `updated`.
152
+ *
153
+ * Work routing: the project is the container an Ever Works Work maps
154
+ * onto, emitted as a `tracker-team` `workHint` keyed on the project key.
155
+ *
156
+ * The opt-in historical backfill (`backfillDays`, default 0 = off, max
157
+ * 90) widens the FIRST pull's window only, with a page bound so
158
+ * activation never becomes an unbounded crawl. Re-delivery across
159
+ * overlapping windows is fine — the ingest pipeline dedupes on
160
+ * `(source, sourceEventId)`.
161
+ */
162
+ declare class JiraConnectorPlugin implements IConnectorPlugin, IEventSourcePlugin {
163
+ readonly id = "jira-connector";
164
+ readonly name = "JIRA Connector";
165
+ readonly version = "1.0.0";
166
+ readonly category: PluginCategory;
167
+ readonly capabilities: readonly ["connector", "event-source"];
168
+ readonly providerName = "jira";
169
+ readonly connector: ConnectorMetadata;
170
+ readonly settingsSchema: JsonSchema;
171
+ private readonly idempotencyCache;
172
+ onLoad(): Promise<void>;
173
+ onUnload(): Promise<void>;
174
+ /** Testable seam — specs stub this; production uses the real SDK. */
175
+ protected createClient(credentials: JiraCredentials): JiraClientLike;
176
+ verifyConnection(config: ChannelTargetConfig, options: ConnectorCallOptions): Promise<ChannelVerification>;
177
+ /** Outbound leg — create a comment on a JIRA issue. */
178
+ send(payload: ChannelSendInput, options: ConnectorCallOptions): Promise<ChannelSendResult>;
179
+ /**
180
+ * Pull one JQL page of issues updated since the effective watermark,
181
+ * normalized to `jira.issue` envelopes plus a `jira.comment` envelope
182
+ * per comment that changed inside the same window. The returned
183
+ * cursor resumes the sweep (API page token); no cursor means the
184
+ * sweep is done.
185
+ *
186
+ * First pull (epoch/absent watermark, no cursor): the window is
187
+ * `now - backfillDays` when the opt-in backfill is on, otherwise
188
+ * `now` — history stays untouched unless the user asked for it.
189
+ */
190
+ pullEvents(input: EventSourcePullInput): Promise<EventSourcePullResult>;
191
+ /**
192
+ * Bounded HISTORICAL sweep from an explicit `since` — the
193
+ * capability's opt-in `backfill()` method.
194
+ *
195
+ * Before this method existed, history was reachable only as a side
196
+ * effect of the FIRST pull (`settings.backfillDays` widening the
197
+ * initial window), so a user who activated the connector without the
198
+ * setting could never go back and fetch it. `backfill()` runs the
199
+ * same JQL sweep out-of-band on a caller-chosen window, as many times
200
+ * as wanted — re-delivery is free because the ingest pipeline dedupes
201
+ * on `(source, sourceEventId)`.
202
+ *
203
+ * `until` is accepted for contract symmetry but NOT applied: the
204
+ * sweep's JQL bounds only the near end (`updated >= since`). An
205
+ * over-wide window costs duplicate deliveries, which the pipeline
206
+ * drops — never wrong data.
207
+ *
208
+ * The page bound (`JIRA_BACKFILL_MAX_PAGES`) applies here too: one
209
+ * call fetches ONE page and hands back a cursor, so a large project
210
+ * can never turn a backfill into an unbounded crawl.
211
+ */
212
+ backfill(input: EventSourceBackfillInput): Promise<EventSourceBackfillResult>;
213
+ private normalizeIssue;
214
+ /**
215
+ * Normalize one comment → envelope, or null when the comment did NOT
216
+ * change inside the sweep window. Commenting bumps the parent issue's
217
+ * `updated`, so an issue can arrive with a long comment history of
218
+ * which only the newest entry is actually news.
219
+ */
220
+ private normalizeComment;
221
+ }
222
+ declare const jiraConnectorPlugin: JiraConnectorPlugin;
223
+
224
+ 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 };