@superdurable/connector-front 0.0.0-stage → 0.1.1

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,17 @@
1
- # Temporary Holding Version
1
+ # Front 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-front` supplies the five Front conversation and contact operations for Dex TypeScript Flows. Operation-specific Step factories, model validators, connection contracts, and mocks are generated from [`connector.yaml`](../connector.yaml) and the Go model types. Run `go run ./cmd/connectorctl generate connectors/front/connector.yaml` from the repository root after changing either source.
4
+
5
+ Use Node.js 22 or 24 and Dex TypeScript SDK 1.28.0 or newer. Create a secret Front API token in [Front Settings > Developers > API Tokens](https://app.frontapp.com/), grant the read, write, and send permissions needed by your Flow, and save it as the `api_token` credential in a Dex Web Connection. At Worker startup, load the project with `loadFromEnvironment()` and pass the static `ConnectionName` to `newProjectConnection`, as in the [runnable example](examples/find-contact/). Keep the token out of Flow inputs, Attributes, results, Streams, and logs.
6
+
7
+ | Factory | Front operation | Happy branch |
8
+ | --- | --- | --- |
9
+ | `newSearchConversationsStep` | Search one bounded conversation page | `searched` |
10
+ | `newGetConversationStep` | Read one conversation with messages and comments | `found` |
11
+ | `newReplyToConversationStep` | Send a reply or add an internal comment | `replied` |
12
+ | `newUpdateConversationStep` | Set status, assignee, and tags | `updated` |
13
+ | `newFindContactByEmailStep` | Look up a contact email alias | `found` |
14
+
15
+ Every other branch is optional, so an unwired branch fails the Flow. Replies and comments use the SDK single-dispatch fence: Front has no provider idempotency key, so an ambiguous send is resent while the manifest send cap allows and selects `uncertain` at the cap. Updates set absolute values and read back the conversation, so they can retry safely.
16
+
17
+ Run `npm ci`, `npm run check`, and `npm run test:integration` with a local `dexcli dev` address. The package replays the Go-recorded provider scenarios; the integration test runs the checked-in Flow through a real Dex Worker and Client against a local Front-compatible fixture. Live Front authorization, conversation operations, and contact lookup have not been verified.
@@ -0,0 +1,388 @@
1
+ {
2
+ "connectorId": "front",
3
+ "releaseTag": "connectors/front/go/v0.23.1",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-front",
7
+ "version": "0.1.1"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newSearchConversationsStep",
12
+ "kind": "query",
13
+ "operationId": "searchConversations",
14
+ "inputType": "SearchConversationsInput",
15
+ "description": "Search conversations by text, inbox, tag, Front status filters, recipient email, assignee, and recent activity, returning one bounded page newest activity first and a page token for the next.",
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
+ "additionalProperties": false,
46
+ "description": "SearchConversationsInput selects one page of Front's conversation search. Every set field is one filter, and Front combines them with AND. At least one field other than the page fields is required.",
47
+ "properties": {
48
+ "activityAfter": {
49
+ "description": "ActivityAfter keeps conversations with a message or comment created after this time, in whole seconds.",
50
+ "format": "date-time",
51
+ "type": [
52
+ "string",
53
+ "null"
54
+ ]
55
+ },
56
+ "assigneeId": {
57
+ "description": "AssigneeID keeps conversations assigned to one teammate, such as tea_2thf.",
58
+ "type": "string"
59
+ },
60
+ "inboxId": {
61
+ "description": "InboxID keeps conversations in one inbox, such as inb_41w25.",
62
+ "type": "string"
63
+ },
64
+ "pageSize": {
65
+ "description": "PageSize is 1 to MaxSearchPageSize; zero requests DefaultSearchPageSize.",
66
+ "type": "integer"
67
+ },
68
+ "pageToken": {
69
+ "description": "PageToken is a previous Result's NextPageToken; send it with the same filters.",
70
+ "type": "string"
71
+ },
72
+ "recipientEmail": {
73
+ "description": "RecipientEmail keeps conversations where the address is a from, to, cc, or bcc handle of any message.",
74
+ "type": "string"
75
+ },
76
+ "statuses": {
77
+ "description": "Statuses are is: filters such as open and unassigned. Blank omits trashed conversations, Front's default.",
78
+ "items": {
79
+ "enum": [
80
+ "archived",
81
+ "assigned",
82
+ "open",
83
+ "resolved",
84
+ "snoozed",
85
+ "trashed",
86
+ "unassigned",
87
+ "unreplied",
88
+ "waiting"
89
+ ],
90
+ "type": "string"
91
+ },
92
+ "type": "array"
93
+ },
94
+ "tagId": {
95
+ "description": "TagID keeps conversations with one tag, such as tag_13o8r1.",
96
+ "type": "string"
97
+ },
98
+ "text": {
99
+ "description": "Text is Front search text matched in subjects and bodies: words, which all must match, and quoted phrases. It is sent unchanged, so Front also applies any filter it contains; quote user-supplied text.",
100
+ "type": "string"
101
+ }
102
+ },
103
+ "type": "object"
104
+ }
105
+ },
106
+ {
107
+ "name": "newGetConversationStep",
108
+ "kind": "query",
109
+ "operationId": "getConversation",
110
+ "inputType": "GetConversationInput",
111
+ "description": "Read one conversation by ID with a bounded list of its newest messages and newest internal comments.",
112
+ "fields": {
113
+ "stepType": "stepType",
114
+ "annotations": "annotations",
115
+ "connectionName": "connectionName",
116
+ "resultAttribute": "resultAttribute"
117
+ },
118
+ "branches": [
119
+ {
120
+ "id": "found",
121
+ "field": "found",
122
+ "optional": false
123
+ },
124
+ {
125
+ "id": "merged",
126
+ "field": "merged",
127
+ "optional": true
128
+ },
129
+ {
130
+ "id": "notFound",
131
+ "field": "notFound",
132
+ "optional": true
133
+ },
134
+ {
135
+ "id": "providerRejected",
136
+ "field": "providerRejected",
137
+ "optional": true
138
+ },
139
+ {
140
+ "id": "invalidResponse",
141
+ "field": "invalidResponse",
142
+ "optional": true
143
+ },
144
+ {
145
+ "id": "defect",
146
+ "field": "defect",
147
+ "optional": true
148
+ }
149
+ ],
150
+ "inputSchema": {
151
+ "additionalProperties": false,
152
+ "description": "GetConversationInput identifies one conversation and how much of its history to return.",
153
+ "properties": {
154
+ "commentLimit": {
155
+ "description": "CommentLimit is 1 to MaxCommentLimit newest internal comments; zero returns DefaultCommentLimit.",
156
+ "type": "integer"
157
+ },
158
+ "conversationId": {
159
+ "description": "ConversationID is the Front conversation ID, such as cnv_55c8c149.",
160
+ "type": "string"
161
+ },
162
+ "messageLimit": {
163
+ "description": "MessageLimit is 1 to MaxMessageLimit newest messages; zero reads DefaultMessageLimit.",
164
+ "type": "integer"
165
+ }
166
+ },
167
+ "required": [
168
+ "conversationId"
169
+ ],
170
+ "type": "object"
171
+ }
172
+ },
173
+ {
174
+ "name": "newReplyToConversationStep",
175
+ "kind": "mutation",
176
+ "operationId": "replyToConversation",
177
+ "inputType": "ReplyToConversationInput",
178
+ "description": "Send one reply that Front delivers to the conversation's recipients, or add one internal comment that only teammates see. Front has no idempotency key or client-supplied lookup value, so the shared single-dispatch fence needs sync durability for visible heartbeat checkpoints across attempts.",
179
+ "fields": {
180
+ "stepType": "stepType",
181
+ "annotations": "annotations",
182
+ "connectionName": "connectionName",
183
+ "resultAttribute": "resultAttribute"
184
+ },
185
+ "branches": [
186
+ {
187
+ "id": "replied",
188
+ "field": "replied",
189
+ "optional": false
190
+ },
191
+ {
192
+ "id": "notFound",
193
+ "field": "notFound",
194
+ "optional": true
195
+ },
196
+ {
197
+ "id": "providerRejected",
198
+ "field": "providerRejected",
199
+ "optional": true
200
+ },
201
+ {
202
+ "id": "uncertain",
203
+ "field": "uncertain",
204
+ "optional": true
205
+ },
206
+ {
207
+ "id": "defect",
208
+ "field": "defect",
209
+ "optional": true
210
+ }
211
+ ],
212
+ "inputSchema": {
213
+ "additionalProperties": false,
214
+ "description": "ReplyToConversationInput is one reply to the customer or one internal comment.",
215
+ "properties": {
216
+ "authorId": {
217
+ "description": "AuthorID is the teammate the reply is sent on behalf of, or who writes the comment, such as tea_2thf. Blank lets Front choose: a comment is then written as the API token.",
218
+ "type": "string"
219
+ },
220
+ "conversationId": {
221
+ "description": "ConversationID is the Front conversation ID, such as cnv_55c8c149.",
222
+ "type": "string"
223
+ },
224
+ "isInternalNote": {
225
+ "description": "IsInternalNote adds a comment that only teammates see, through POST /conversations/{id}/comments. False sends a reply that Front delivers to the conversation's recipients, through POST /conversations/{id}/messages.",
226
+ "type": "boolean"
227
+ },
228
+ "shouldArchive": {
229
+ "description": "ShouldArchive archives the conversation when the reply is sent. False keeps it open, unlike Front's own default; a comment must leave it false.",
230
+ "type": "boolean"
231
+ },
232
+ "text": {
233
+ "description": "Text is the plain text to send, required and at most MaxReplyTextBytes. A reply sends it as text and as an HTML body with one paragraph per blank-line-separated block; a comment sends it unchanged, and Front renders Markdown in comments.",
234
+ "type": "string"
235
+ }
236
+ },
237
+ "required": [
238
+ "conversationId",
239
+ "text"
240
+ ],
241
+ "type": "object"
242
+ }
243
+ },
244
+ {
245
+ "name": "newUpdateConversationStep",
246
+ "kind": "mutation",
247
+ "operationId": "updateConversation",
248
+ "inputType": "UpdateConversationInput",
249
+ "description": "Set the Front status or ticket status, assignee, and tags of one conversation, then read it back; a repeated attempt finds the values already applied and writes nothing.",
250
+ "fields": {
251
+ "stepType": "stepType",
252
+ "annotations": "annotations",
253
+ "connectionName": "connectionName",
254
+ "resultAttribute": "resultAttribute"
255
+ },
256
+ "branches": [
257
+ {
258
+ "id": "updated",
259
+ "field": "updated",
260
+ "optional": false
261
+ },
262
+ {
263
+ "id": "notFound",
264
+ "field": "notFound",
265
+ "optional": true
266
+ },
267
+ {
268
+ "id": "providerRejected",
269
+ "field": "providerRejected",
270
+ "optional": true
271
+ },
272
+ {
273
+ "id": "invalidResponse",
274
+ "field": "invalidResponse",
275
+ "optional": true
276
+ },
277
+ {
278
+ "id": "defect",
279
+ "field": "defect",
280
+ "optional": true
281
+ }
282
+ ],
283
+ "inputSchema": {
284
+ "additionalProperties": false,
285
+ "description": "UpdateConversationInput sets a conversation's status, assignee, and tags. Every field is optional, but at least one change is required. Unset fields are left as they are.",
286
+ "properties": {
287
+ "addTagIds": {
288
+ "description": "AddTagIDs are tag IDs to add, such as tag_13o8r1; a tag already on the conversation is kept once.",
289
+ "items": {
290
+ "type": "string"
291
+ },
292
+ "type": "array"
293
+ },
294
+ "assigneeId": {
295
+ "description": "AssigneeID assigns the conversation to one teammate, such as tea_2thf.",
296
+ "type": "string"
297
+ },
298
+ "conversationId": {
299
+ "description": "ConversationID is the Front conversation ID, such as cnv_55c8c149.",
300
+ "type": "string"
301
+ },
302
+ "isUnassigned": {
303
+ "description": "IsUnassigned removes the assignee; it cannot be combined with AssigneeID.",
304
+ "type": "boolean"
305
+ },
306
+ "removeTagIds": {
307
+ "description": "RemoveTagIDs are tag IDs to remove; a tag not on the conversation is ignored.",
308
+ "items": {
309
+ "type": "string"
310
+ },
311
+ "type": "array"
312
+ },
313
+ "status": {
314
+ "description": "Status is open, archived, or deleted, in Front's write vocabulary. It cannot be combined with StatusID.",
315
+ "enum": [
316
+ "archived",
317
+ "deleted",
318
+ "open"
319
+ ],
320
+ "type": "string"
321
+ },
322
+ "statusId": {
323
+ "description": "StatusID is a ticket status ID, such as sts_5x, for a company that uses ticketing.",
324
+ "type": "string"
325
+ }
326
+ },
327
+ "required": [
328
+ "conversationId"
329
+ ],
330
+ "type": "object"
331
+ }
332
+ },
333
+ {
334
+ "name": "newFindContactByEmailStep",
335
+ "kind": "query",
336
+ "operationId": "findContactByEmail",
337
+ "inputType": "FindContactByEmailInput",
338
+ "description": "Find the Front contact whose email handle equals one address; Front keeps each handle on at most one contact.",
339
+ "fields": {
340
+ "stepType": "stepType",
341
+ "annotations": "annotations",
342
+ "connectionName": "connectionName",
343
+ "resultAttribute": "resultAttribute"
344
+ },
345
+ "branches": [
346
+ {
347
+ "id": "found",
348
+ "field": "found",
349
+ "optional": false
350
+ },
351
+ {
352
+ "id": "notFound",
353
+ "field": "notFound",
354
+ "optional": true
355
+ },
356
+ {
357
+ "id": "providerRejected",
358
+ "field": "providerRejected",
359
+ "optional": true
360
+ },
361
+ {
362
+ "id": "invalidResponse",
363
+ "field": "invalidResponse",
364
+ "optional": true
365
+ },
366
+ {
367
+ "id": "defect",
368
+ "field": "defect",
369
+ "optional": true
370
+ }
371
+ ],
372
+ "inputSchema": {
373
+ "additionalProperties": false,
374
+ "description": "FindContactByEmailInput is the email handle to look up.",
375
+ "properties": {
376
+ "email": {
377
+ "description": "Email is one bare address, such as jane@acme.example.com, sent as Front's alt:email: contact alias.",
378
+ "type": "string"
379
+ }
380
+ },
381
+ "required": [
382
+ "email"
383
+ ],
384
+ "type": "object"
385
+ }
386
+ }
387
+ ]
388
+ }