@superdurable/connector-atlassian-confluence 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Super Durable
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,67 @@
1
- # Temporary Holding Version
1
+ # Atlassian Confluence TypeScript connector
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@superdurable/connector-atlassian-confluence` provides Dex Query and Mutation
4
+ operations for Confluence Cloud pages and footer comments. Its five operations
5
+ are `searchPages`, `getPage`, `createPage`, `updatePage`, and `addComment`.
6
+ The public models, branch definitions, Step factories, connection helpers, and
7
+ mock cases are generated from `../connector.yaml`; OAuth credential refresh
8
+ uses the generated manifest declaration. The provider client and operation
9
+ behavior follow the Go connector, including page title and version read-back
10
+ for writes and an at-most-once checkpoint for footer comments. From 0.2.0 the
11
+ package also implements the `pageChanged` poll Trigger, which starts a Flow
12
+ when a page is created or updated, on `@superdurable/connectors-sdk` 0.12.0's
13
+ poll Trigger kit.
14
+
15
+ A consuming application is checked in at
16
+ [examples/read-page](examples/read-page/README.md). It loads the private Dex
17
+ project connection `confluence-policy`, reads one page inside a Dex Step, and
18
+ returns only its ID, title, and version number. Run its real Dex integration
19
+ test with `DEX_FLOW_SERVICE_ADDRESS` set to the local `dexcli dev` gRPC address.
20
+
21
+ ## pageChanged Trigger
22
+
23
+ `pageChanged` polls Confluence CQL content search, newest modification first,
24
+ at parity with the Go connector, on `@superdurable/connectors-sdk/pollingtrigger`;
25
+ the [connector README](../README.md#pagechanged-trigger) describes the query,
26
+ the ten-minute lookback, the keyed snapshot of seen page versions, paging,
27
+ change kinds, resets, and rate limits. The cursor token and snapshot entries
28
+ match the Go connector's byte for byte, including nanosecond times, which the
29
+ Go-generated fixtures in `test/fixtures/go-page-change-cases.json` check, so a
30
+ Go and a TypeScript replica can share one binding's cursor and inbox.
31
+
32
+ - `newProjectPageTriggerRunner(project, connectionName, routes, options)` opens
33
+ the connection and each route's saved binding and returns a
34
+ `PageTriggerRunner`. Every change is recorded in the binding's project
35
+ Trigger inbox before its project poll cursor commits, so a restarted Worker
36
+ neither misses nor repeats a change. An unsaved binding watches every space
37
+ the connection can view. Await `run(context)` for the life of the Worker;
38
+ `wakePoller(bindingName)` polls now.
39
+ - `newPageTriggerRunner({ connection, pageChangedRoutes })` takes targets and
40
+ cursor stores directly and returns the kit's `Runner`; a route without a
41
+ cursor store keeps it in memory and records a new baseline on every start,
42
+ as `newPageChangedTrigger` always does.
43
+ - Each `PageChangedEvent` carries the site, the derived `changeKind`
44
+ (`PageChangeCreated` for version 1, `PageChangeUpdated` otherwise), and the
45
+ page summary, whose `lastModifiedAt` keeps Confluence's time exactly as Go
46
+ writes it. The event ID hashes the site, page ID, and version, so
47
+ `newDexFlowTriggerTarget` starts one Flow per page version. The event's
48
+ `occurredAt` is a `Date`, at millisecond precision.
49
+ - The connection's `pollInterval` (at least 10 seconds; zero keeps the
50
+ one-minute default) sets the poll delay, and `ConfluenceClientOptions`
51
+ `triggerLogger` receives the runner's records.
52
+ - `definePageChangedTriggerBinding` declares a static binding with the
53
+ `spacePicker` unit from `getConnectorTriggerBindings`.
54
+
55
+ The runnable [page-changed Flow](examples/page-changed/README.md) starts one
56
+ Flow per page version and reads the page back as Markdown. Its integration
57
+ tests run a real Dex Worker and Client against a local Confluence stand-in:
58
+ the baseline starts no Flow, other spaces are ignored, each page version
59
+ starts one Flow across a Trigger restart whose first search answers 429, and a
60
+ changed space records a new baseline. Live Confluence search has not been
61
+ verified.
62
+
63
+ Run `npm ci && npm run check` to build and test the package. The conformance
64
+ suite replays the recorded Go provider scenarios under
65
+ `../../../../conformance/connectors/atlassian/confluence/scenarios.json`.
66
+ Live Atlassian authorization, site selection, writes, and comment delivery
67
+ remain unverified.
@@ -0,0 +1,427 @@
1
+ {
2
+ "connectorId": "confluence",
3
+ "releaseTag": "connectors/atlassian/confluence/go/v0.25.0",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-atlassian-confluence",
7
+ "version": "0.2.0"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newSearchPagesStep",
12
+ "kind": "query",
13
+ "operationId": "searchPages",
14
+ "inputType": "SearchPagesInput",
15
+ "description": "Search one bounded page of Confluence pages with a typed, connector-escaped CQL filter for space, title, label, and modification time plus an optional bounded CQL clause, continuing with the search cursor.",
16
+ "fields": {
17
+ "stepType": "stepType",
18
+ "annotations": "annotations",
19
+ "connectionName": "connectionName",
20
+ "resultAttribute": "resultAttribute"
21
+ },
22
+ "branches": [
23
+ {
24
+ "id": "searched",
25
+ "field": "searched",
26
+ "optional": false
27
+ },
28
+ {
29
+ "id": "providerRejected",
30
+ "field": "providerRejected",
31
+ "optional": true
32
+ },
33
+ {
34
+ "id": "invalidResponse",
35
+ "field": "invalidResponse",
36
+ "optional": true
37
+ },
38
+ {
39
+ "id": "defect",
40
+ "field": "defect",
41
+ "optional": true
42
+ }
43
+ ],
44
+ "inputSchema": {
45
+ "$defs": {
46
+ "PageSearchFilter": {
47
+ "additionalProperties": false,
48
+ "description": "PageSearchFilter is a typed page search that the connector turns into escaped CQL, so no caller text can change the query's structure. The query always starts with type = page, and every set field adds one clause joined with AND.",
49
+ "properties": {
50
+ "additionalCql": {
51
+ "description": "AdditionalCQL is one caller-built clause ANDed inside parentheses, such as ancestor = 123456 OR parent = 123456. It must balance its parentheses and quotes and cannot contain ORDER BY. Quote every value that came from outside the application with QuoteCQLString.",
52
+ "type": "string"
53
+ },
54
+ "labels": {
55
+ "description": "Labels matches pages that carry at least one of these labels, such as policy or in-force.",
56
+ "items": {
57
+ "type": "string"
58
+ },
59
+ "type": "array"
60
+ },
61
+ "modifiedSince": {
62
+ "description": "ModifiedSince keeps only pages last modified at or after this instant. CQL compares dates in the authorizing user's Confluence time zone, so the connector widens the CQL bound by half a day and removes earlier pages from each result page itself.",
63
+ "format": "date-time",
64
+ "type": [
65
+ "string",
66
+ "null"
67
+ ]
68
+ },
69
+ "order": {
70
+ "description": "Order selects the result order; blank uses PageSearchOrderLastModifiedDescending.",
71
+ "enum": [
72
+ "createdDescending",
73
+ "lastModifiedDescending",
74
+ "titleAscending"
75
+ ],
76
+ "type": "string"
77
+ },
78
+ "spaceKeys": {
79
+ "description": "SpaceKeys limits the search to these space keys, such as OPS or ~5b10ac8d82e05b22cc7d4ef5.",
80
+ "items": {
81
+ "type": "string"
82
+ },
83
+ "type": "array"
84
+ },
85
+ "titlePhrase": {
86
+ "description": "TitlePhrase matches pages whose title contains this phrase as Confluence's text search tokenizes it. Text search ignores case and punctuation, so compare the returned titles for an exact match.",
87
+ "type": "string"
88
+ }
89
+ },
90
+ "type": "object"
91
+ }
92
+ },
93
+ "additionalProperties": false,
94
+ "description": "SearchPagesInput selects one page of search results.",
95
+ "properties": {
96
+ "cursor": {
97
+ "description": "Cursor continues a previous search with the same filter; blank reads the first page.",
98
+ "type": "string"
99
+ },
100
+ "filter": {
101
+ "$ref": "#/$defs/PageSearchFilter",
102
+ "description": "Filter is the typed search the connector escapes into CQL."
103
+ },
104
+ "pageSize": {
105
+ "description": "PageSize is the number of pages to request, 1 to 100; zero requests 25. Confluence may return fewer.",
106
+ "type": "integer"
107
+ }
108
+ },
109
+ "required": [
110
+ "filter"
111
+ ],
112
+ "type": "object"
113
+ }
114
+ },
115
+ {
116
+ "name": "newGetPageStep",
117
+ "kind": "query",
118
+ "operationId": "getPage",
119
+ "inputType": "GetPageInput",
120
+ "description": "Read one page by ID with its current version number and its storage or Atlassian Document Format body converted to bounded Markdown or plain text.",
121
+ "fields": {
122
+ "stepType": "stepType",
123
+ "annotations": "annotations",
124
+ "connectionName": "connectionName",
125
+ "resultAttribute": "resultAttribute"
126
+ },
127
+ "branches": [
128
+ {
129
+ "id": "found",
130
+ "field": "found",
131
+ "optional": false
132
+ },
133
+ {
134
+ "id": "notFound",
135
+ "field": "notFound",
136
+ "optional": true
137
+ },
138
+ {
139
+ "id": "providerRejected",
140
+ "field": "providerRejected",
141
+ "optional": true
142
+ },
143
+ {
144
+ "id": "invalidResponse",
145
+ "field": "invalidResponse",
146
+ "optional": true
147
+ },
148
+ {
149
+ "id": "defect",
150
+ "field": "defect",
151
+ "optional": true
152
+ }
153
+ ],
154
+ "inputSchema": {
155
+ "additionalProperties": false,
156
+ "description": "GetPageInput identifies one page and how to return its body.",
157
+ "properties": {
158
+ "bodyFormat": {
159
+ "description": "BodyFormat selects the returned text; blank returns Markdown.",
160
+ "enum": [
161
+ "markdown",
162
+ "plainText"
163
+ ],
164
+ "type": "string"
165
+ },
166
+ "bodyRepresentation": {
167
+ "description": "BodyRepresentation selects the Confluence body to convert; blank reads storage format.",
168
+ "enum": [
169
+ "atlas_doc_format",
170
+ "storage"
171
+ ],
172
+ "type": "string"
173
+ },
174
+ "maxBodyCharacters": {
175
+ "description": "MaxBodyCharacters cuts Body after this many characters, 1 to 131072; zero keeps 32768.",
176
+ "type": "integer"
177
+ },
178
+ "pageId": {
179
+ "description": "PageID is the numeric page ID, such as 123456.",
180
+ "type": "string"
181
+ }
182
+ },
183
+ "required": [
184
+ "pageId"
185
+ ],
186
+ "type": "object"
187
+ }
188
+ },
189
+ {
190
+ "name": "newCreatePageStep",
191
+ "kind": "mutation",
192
+ "operationId": "createPage",
193
+ "inputType": "CreatePageInput",
194
+ "description": "Publish one page in a space, optionally below a parent page, with a Markdown or plain-text body converted to storage format; Confluence allows one page per title in a space, so a repeated create finds the page instead of adding another.",
195
+ "fields": {
196
+ "stepType": "stepType",
197
+ "annotations": "annotations",
198
+ "connectionName": "connectionName",
199
+ "resultAttribute": "resultAttribute"
200
+ },
201
+ "branches": [
202
+ {
203
+ "id": "created",
204
+ "field": "created",
205
+ "optional": false
206
+ },
207
+ {
208
+ "id": "titleConflict",
209
+ "field": "titleConflict",
210
+ "optional": true
211
+ },
212
+ {
213
+ "id": "notFound",
214
+ "field": "notFound",
215
+ "optional": true
216
+ },
217
+ {
218
+ "id": "providerRejected",
219
+ "field": "providerRejected",
220
+ "optional": true
221
+ },
222
+ {
223
+ "id": "defect",
224
+ "field": "defect",
225
+ "optional": true
226
+ }
227
+ ],
228
+ "inputSchema": {
229
+ "additionalProperties": false,
230
+ "description": "CreatePageInput describes one published page. Set exactly one of SpaceID and SpaceKey.",
231
+ "properties": {
232
+ "body": {
233
+ "description": "Body is the page content of at most 262144 characters in BodyFormat.",
234
+ "type": "string"
235
+ },
236
+ "bodyFormat": {
237
+ "description": "BodyFormat is the format of Body; blank reads Markdown.",
238
+ "enum": [
239
+ "markdown",
240
+ "plainText"
241
+ ],
242
+ "type": "string"
243
+ },
244
+ "parentPageId": {
245
+ "description": "ParentPageID places the page below this page in the same space; blank uses the space homepage.",
246
+ "type": "string"
247
+ },
248
+ "spaceId": {
249
+ "description": "SpaceID is the numeric space ID, as the space picker stores it.",
250
+ "type": "string"
251
+ },
252
+ "spaceKey": {
253
+ "description": "SpaceKey is the space key, such as OPS; the connector looks up its ID before creating.",
254
+ "type": "string"
255
+ },
256
+ "title": {
257
+ "description": "Title is the one-line page title, at most 255 characters. Confluence allows one page per title in a space.",
258
+ "type": "string"
259
+ }
260
+ },
261
+ "required": [
262
+ "body",
263
+ "title"
264
+ ],
265
+ "type": "object"
266
+ }
267
+ },
268
+ {
269
+ "name": "newUpdatePageStep",
270
+ "kind": "mutation",
271
+ "operationId": "updatePage",
272
+ "inputType": "UpdatePageInput",
273
+ "description": "Replace one page's title and body as the next version, which the caller names; a repeated update finds its own version instead of failing, and a version another editor made is reported as a conflict.",
274
+ "fields": {
275
+ "stepType": "stepType",
276
+ "annotations": "annotations",
277
+ "connectionName": "connectionName",
278
+ "resultAttribute": "resultAttribute"
279
+ },
280
+ "branches": [
281
+ {
282
+ "id": "updated",
283
+ "field": "updated",
284
+ "optional": false
285
+ },
286
+ {
287
+ "id": "versionConflict",
288
+ "field": "versionConflict",
289
+ "optional": true
290
+ },
291
+ {
292
+ "id": "notFound",
293
+ "field": "notFound",
294
+ "optional": true
295
+ },
296
+ {
297
+ "id": "providerRejected",
298
+ "field": "providerRejected",
299
+ "optional": true
300
+ },
301
+ {
302
+ "id": "defect",
303
+ "field": "defect",
304
+ "optional": true
305
+ }
306
+ ],
307
+ "inputSchema": {
308
+ "additionalProperties": false,
309
+ "description": "UpdatePageInput replaces one page's title and body as the next version.",
310
+ "properties": {
311
+ "body": {
312
+ "description": "Body is the complete new page content of at most 262144 characters in BodyFormat.",
313
+ "type": "string"
314
+ },
315
+ "bodyFormat": {
316
+ "description": "BodyFormat is the format of Body; blank reads Markdown.",
317
+ "enum": [
318
+ "markdown",
319
+ "plainText"
320
+ ],
321
+ "type": "string"
322
+ },
323
+ "nextVersionNumber": {
324
+ "description": "NextVersionNumber is the version this update creates: the version number getPage returned plus one. Confluence refuses it when another edit saved that version first.",
325
+ "type": "integer"
326
+ },
327
+ "pageId": {
328
+ "description": "PageID is the numeric page ID, such as 123456.",
329
+ "type": "string"
330
+ },
331
+ "title": {
332
+ "description": "Title is the page title after the update, one line of at most 255 characters; repeat the current title to keep it.",
333
+ "type": "string"
334
+ },
335
+ "versionMessage": {
336
+ "description": "VersionMessage is an optional one-line change summary of at most 200 characters, shown in page history. The connector appends a marker such as [dex:3f9a2c1b7e04d5a6] to recognize its own update.",
337
+ "type": "string"
338
+ }
339
+ },
340
+ "required": [
341
+ "body",
342
+ "nextVersionNumber",
343
+ "pageId",
344
+ "title"
345
+ ],
346
+ "type": "object"
347
+ }
348
+ },
349
+ {
350
+ "name": "newAddCommentStep",
351
+ "kind": "mutation",
352
+ "operationId": "addComment",
353
+ "inputType": "AddCommentInput",
354
+ "description": "Add one footer comment with a Markdown or plain-text body to a page, sending it at most once per Step execution and confirming an unconfirmed attempt by reading the page's comments.",
355
+ "fields": {
356
+ "stepType": "stepType",
357
+ "annotations": "annotations",
358
+ "connectionName": "connectionName",
359
+ "resultAttribute": "resultAttribute"
360
+ },
361
+ "branches": [
362
+ {
363
+ "id": "added",
364
+ "field": "added",
365
+ "optional": false
366
+ },
367
+ {
368
+ "id": "notFound",
369
+ "field": "notFound",
370
+ "optional": true
371
+ },
372
+ {
373
+ "id": "providerRejected",
374
+ "field": "providerRejected",
375
+ "optional": true
376
+ },
377
+ {
378
+ "id": "uncertain",
379
+ "field": "uncertain",
380
+ "optional": true
381
+ },
382
+ {
383
+ "id": "defect",
384
+ "field": "defect",
385
+ "optional": true
386
+ }
387
+ ],
388
+ "inputSchema": {
389
+ "additionalProperties": false,
390
+ "description": "AddCommentInput describes one footer comment on one page.",
391
+ "properties": {
392
+ "body": {
393
+ "description": "Body is the comment of at most 262144 characters in BodyFormat.",
394
+ "type": "string"
395
+ },
396
+ "bodyFormat": {
397
+ "description": "BodyFormat is the format of Body; blank reads Markdown.",
398
+ "enum": [
399
+ "markdown",
400
+ "plainText"
401
+ ],
402
+ "type": "string"
403
+ },
404
+ "pageId": {
405
+ "description": "PageID is the numeric page ID, such as 123456.",
406
+ "type": "string"
407
+ }
408
+ },
409
+ "required": [
410
+ "body",
411
+ "pageId"
412
+ ],
413
+ "type": "object"
414
+ }
415
+ },
416
+ {
417
+ "name": "definePageChangedTriggerBinding",
418
+ "kind": "trigger",
419
+ "triggerName": "pageChanged",
420
+ "fields": {
421
+ "connectionName": "connectionName",
422
+ "bindingName": "bindingName",
423
+ "configurationUI": "configurationUI"
424
+ }
425
+ }
426
+ ]
427
+ }