@superdurable/connector-freshdesk 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,31 @@
1
- # Temporary Holding Version
1
+ # Freshdesk 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-freshdesk` supplies Dex Step factories for five Freshdesk API v2 operations: `searchTickets`, `getTicket`, `createTicket`, `updateTicket`, and `addNote`. The package uses the same connection, operation, branch, and Trigger identities as the Go connector, and from 0.2.0 implements the `ticketChanged` poll Trigger on `@superdurable/connectors-sdk` 0.12.0. See the [connector README](../README.md) for Freshdesk setup, statuses, limits, and duplicate safety.
4
+
5
+ Create a Dex Web connection named `freshdesk-helpdesk`. Set `domain` to the lowercase part before `.freshdesk.com`, and save the agent's API key in the secret `api_key` field. Keep the key out of Flow input. `newProjectConnection` loads that static connection at Worker startup and resolves the current credential for each operation.
6
+
7
+ The runnable [ticket search example](examples/search-tickets/README.md) uses `newSearchTicketsStep` inside a Flow. Its `searched` branch is wired; the optional `providerRejected`, `invalidResponse`, and `defect` branches fail the Flow if selected. The other generated factories are `newGetTicketStep`, `newCreateTicketStep`, `newUpdateTicketStep`, and `newAddNoteStep`.
8
+
9
+ ## ticketChanged Trigger
10
+
11
+ `ticketChanged` starts a Flow for each Freshdesk ticket created or updated after the binding first started. It polls List All Tickets, `GET /api/v2/tickets` with `updated_since`, `order_by=updated_at`, `order_type=asc`, and `per_page=100`, on `@superdurable/connectors-sdk/pollingtrigger` at parity with the Go connector; the [connector README](../README.md#ticketchanged-trigger) describes the baseline, the one-minute overlap window, change kinds, paging, rate limits, and the rejected-cursor reseed. Each delivery is a `TriggerEvent<TicketChangedEvent>` whose ID is `freshdesk-ticket-<id>-<updated_at Unix seconds>`; `changeKind` is `created` or `updated`. Read the ticket with `getTicket` for its description, requester, and conversations, which the list omits.
12
+
13
+ The cursor token is the Go connector's JSON document byte for byte, and inbox payloads decode in either language, so Go and TypeScript replicas can share one binding. `test/ticket_change_fetcher.test.ts` replays fetches the Go connector recorded and compares every request, cursor token, and event ID.
14
+
15
+ `newProjectTicketTriggerRunner` loads each saved binding's configuration (an unsaved binding delivers every change kind) and records every change in the binding's project Trigger inbox before its cursor commits. From [`examples/ticket-changed/app.ts`](examples/ticket-changed/app.ts):
16
+
17
+ ```ts
18
+ return newProjectTicketTriggerRunner(project, connection, {
19
+ ticketChangedRoutes: [{ bindingName: TicketChangedTriggerBinding, target: newDexFlowTriggerTarget(client, flow, acceptEveryTicketChange, resolveFlowId, mapToFlowInput) }],
20
+ });
21
+ ```
22
+
23
+ The runner takes the connection from `newProjectConnection`, whose `pollInterval` (at least 10 seconds) sets the delay between polls and whose `logger` client option receives the runner's and inboxes' records. `newTicketTriggerRunner` takes explicit routes and cursor stores; a route without a cursor keeps it in memory. `newTicketChangedTrigger` is the equivalent of Go's generated `NewTicketChangedTrigger`: it keeps its cursor in memory, so it records a new baseline on every start. A Flow declares the binding for Dex Web with `defineTicketChangedTriggerBinding`; the binding's only configuration is the optional `changeKinds` list. Differences from Go: durations are milliseconds (`TicketChangeOverlapMs`, `pollIntervalMs`), the project runner takes an open connection instead of a connection name and options, and timestamps keep JavaScript's millisecond precision.
24
+
25
+ ## Validation
26
+
27
+ `createTicket` requester email and `searchTickets` requester email must be bare addresses with no dot at the start or end of the local part. A refused provider address is retried as an unsent request. `getTicket` and `updateTicket` receipts identify the requested ticket on provider response branches, including `notFound` and `invalidResponse`.
28
+
29
+ Run package checks with `npm ci && npm run check`; until `@superdurable/connectors-sdk` 0.12.0 is published, install a local build of `sdkts` first. The Go-recorded fixture in `../../../../conformance/connectors/freshworks/freshdesk/scenarios.json` covers all five operations, including branches, retry classifications, request shapes, and unkeyed write uncertainty. Run the examples' integration tests with `DEX_FLOW_SERVICE_ADDRESS` set to a local `dexcli dev` gRPC address; the search test's stand-in provider binds a free loopback port, and the [ticket change example](examples/ticket-changed/README.md)'s tests poll a stateful ticket-list fake through the baseline, one Flow per change across a restart, a 429 with `Retry-After`, and a rejected-cursor reseed.
30
+
31
+ Live Freshdesk authorization and provider behavior, including the `ticketChanged` polling behavior the connector README lists, have not been verified. The local integration test uses a Freshdesk-compatible HTTP stand-in through a real Dex Worker and Client.
@@ -0,0 +1,449 @@
1
+ {
2
+ "connectorId": "freshdesk",
3
+ "releaseTag": "connectors/freshworks/freshdesk/go/v0.24.0",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-freshdesk",
7
+ "version": "0.2.0"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newSearchTicketsStep",
12
+ "kind": "query",
13
+ "operationId": "searchTickets",
14
+ "inputType": "SearchTicketsInput",
15
+ "description": "Filter tickets by Freshdesk status, priority, tag, update date, and requester email with Freshdesk's filter query, returning one page of at most 30 tickets.",
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": "SearchTicketsInput selects tickets with typed filters that the connector turns into one Freshdesk filter query. Different filters narrow each other; several statuses, priorities, or tags match any of them. At least one of Statuses, Priorities, Tags, or UpdatedSinceDate is required, because Freshdesk's filter query needs a condition and has no requester field.",
47
+ "properties": {
48
+ "page": {
49
+ "description": "Page is 1 to MaxSearchPage; zero reads the first page.",
50
+ "type": "integer"
51
+ },
52
+ "priorities": {
53
+ "description": "Priorities matches tickets with any of these Freshdesk priorities. Empty matches every priority.",
54
+ "items": {
55
+ "enum": [
56
+ 1,
57
+ 2,
58
+ 3,
59
+ 4
60
+ ],
61
+ "type": "integer"
62
+ },
63
+ "type": "array"
64
+ },
65
+ "requesterEmail": {
66
+ "description": "RequesterEmail keeps only tickets requested by the contact with this email address, such as jane@example.com. The connector looks the contact up first and filters each page itself, so a page can hold fewer than SearchPageSize tickets, even none, while NextPage is set. Blank keeps every requester.",
67
+ "type": "string"
68
+ },
69
+ "statuses": {
70
+ "description": "Statuses matches tickets in any of these Freshdesk statuses, including custom ones. Empty matches every status.",
71
+ "items": {
72
+ "enum": [
73
+ 2,
74
+ 3,
75
+ 4,
76
+ 5,
77
+ 6,
78
+ 7
79
+ ],
80
+ "type": "integer"
81
+ },
82
+ "type": "array"
83
+ },
84
+ "tags": {
85
+ "description": "Tags matches tickets carrying any of these tags.",
86
+ "items": {
87
+ "type": "string"
88
+ },
89
+ "type": "array"
90
+ },
91
+ "updatedSinceDate": {
92
+ "description": "UpdatedSinceDate matches tickets updated on or after this UTC calendar date, written YYYY-MM-DD. Freshdesk's filter query compares dates, not instants. Blank applies no time filter.",
93
+ "type": "string"
94
+ }
95
+ },
96
+ "type": "object"
97
+ }
98
+ },
99
+ {
100
+ "name": "newGetTicketStep",
101
+ "kind": "query",
102
+ "operationId": "getTicket",
103
+ "inputType": "GetTicketInput",
104
+ "description": "Read one ticket by ID with its requester and a bounded list of its first conversations.",
105
+ "fields": {
106
+ "stepType": "stepType",
107
+ "annotations": "annotations",
108
+ "connectionName": "connectionName",
109
+ "resultAttribute": "resultAttribute"
110
+ },
111
+ "branches": [
112
+ {
113
+ "id": "found",
114
+ "field": "found",
115
+ "optional": false
116
+ },
117
+ {
118
+ "id": "notFound",
119
+ "field": "notFound",
120
+ "optional": true
121
+ },
122
+ {
123
+ "id": "providerRejected",
124
+ "field": "providerRejected",
125
+ "optional": true
126
+ },
127
+ {
128
+ "id": "invalidResponse",
129
+ "field": "invalidResponse",
130
+ "optional": true
131
+ },
132
+ {
133
+ "id": "defect",
134
+ "field": "defect",
135
+ "optional": true
136
+ }
137
+ ],
138
+ "inputSchema": {
139
+ "additionalProperties": false,
140
+ "description": "GetTicketInput names one ticket and how many of its first conversations to return.",
141
+ "properties": {
142
+ "conversationLimit": {
143
+ "description": "ConversationLimit is 1 to MaxConversationLimit; zero uses DefaultConversationLimit.",
144
+ "type": "integer"
145
+ },
146
+ "ticketId": {
147
+ "description": "TicketID is the Freshdesk ticket ID.",
148
+ "type": "integer"
149
+ }
150
+ },
151
+ "required": [
152
+ "ticketId"
153
+ ],
154
+ "type": "object"
155
+ }
156
+ },
157
+ {
158
+ "name": "newCreateTicketStep",
159
+ "kind": "mutation",
160
+ "operationId": "createTicket",
161
+ "inputType": "CreateTicketInput",
162
+ "description": "Create one ticket for a requester email. The Step runs with sync durability; 429, 503, and traced pre-connection failures permit one next-attempt resend, while other dispatched outcomes are never resent.",
163
+ "fields": {
164
+ "stepType": "stepType",
165
+ "annotations": "annotations",
166
+ "connectionName": "connectionName",
167
+ "resultAttribute": "resultAttribute"
168
+ },
169
+ "branches": [
170
+ {
171
+ "id": "created",
172
+ "field": "created",
173
+ "optional": false
174
+ },
175
+ {
176
+ "id": "providerRejected",
177
+ "field": "providerRejected",
178
+ "optional": true
179
+ },
180
+ {
181
+ "id": "uncertain",
182
+ "field": "uncertain",
183
+ "optional": true
184
+ },
185
+ {
186
+ "id": "defect",
187
+ "field": "defect",
188
+ "optional": true
189
+ }
190
+ ],
191
+ "inputSchema": {
192
+ "$defs": {
193
+ "TicketRequesterInput": {
194
+ "additionalProperties": false,
195
+ "description": "TicketRequesterInput identifies the requester by email. Freshdesk uses the contact with that address or, when none exists, adds a contact named Name.",
196
+ "properties": {
197
+ "email": {
198
+ "description": "Email is one bare address such as jane@example.com.",
199
+ "type": "string"
200
+ },
201
+ "name": {
202
+ "description": "Name names a contact Freshdesk adds; blank lets Freshdesk derive one.",
203
+ "type": "string"
204
+ }
205
+ },
206
+ "required": [
207
+ "email"
208
+ ],
209
+ "type": "object"
210
+ }
211
+ },
212
+ "additionalProperties": false,
213
+ "description": "CreateTicketInput is one new ticket. Zero values leave a field to Freshdesk's defaults, the account's ticket form, and its automations.",
214
+ "properties": {
215
+ "description": {
216
+ "description": "Description is the ticket's plain-text content. It is required. The connector escapes it into Freshdesk's HTML description, so markup is shown literally and line breaks are kept.",
217
+ "type": "string"
218
+ },
219
+ "groupId": {
220
+ "description": "GroupID assigns the ticket to a group, or zero for Freshdesk's default routing.",
221
+ "type": "integer"
222
+ },
223
+ "priority": {
224
+ "description": "Priority is a Freshdesk priority, or zero for Freshdesk's default, Low (1).",
225
+ "enum": [
226
+ 1,
227
+ 2,
228
+ 3,
229
+ 4
230
+ ],
231
+ "type": "integer"
232
+ },
233
+ "requester": {
234
+ "$ref": "#/$defs/TicketRequesterInput",
235
+ "description": "Requester is the customer asking for help. It is required."
236
+ },
237
+ "responderId": {
238
+ "description": "ResponderID assigns the ticket to an agent, Freshdesk's responder_id, or zero for none.",
239
+ "type": "integer"
240
+ },
241
+ "status": {
242
+ "description": "Status is a Freshdesk status, or zero for Freshdesk's default, Open (2).",
243
+ "enum": [
244
+ 2,
245
+ 3,
246
+ 4,
247
+ 5,
248
+ 6,
249
+ 7
250
+ ],
251
+ "type": "integer"
252
+ },
253
+ "subject": {
254
+ "description": "Subject is the ticket subject. It is required.",
255
+ "type": "string"
256
+ },
257
+ "tags": {
258
+ "description": "Tags are set on the new ticket; account automations may add more.",
259
+ "items": {
260
+ "type": "string"
261
+ },
262
+ "type": "array"
263
+ },
264
+ "type": {
265
+ "description": "Type is one of the account's ticket type labels, such as Question, or empty for none.",
266
+ "type": "string"
267
+ }
268
+ },
269
+ "required": [
270
+ "description",
271
+ "requester",
272
+ "subject"
273
+ ],
274
+ "type": "object"
275
+ }
276
+ },
277
+ {
278
+ "name": "newUpdateTicketStep",
279
+ "kind": "mutation",
280
+ "operationId": "updateTicket",
281
+ "inputType": "UpdateTicketInput",
282
+ "description": "Set the status, priority, group, or agent of one ticket and add or remove tags; a repeated attempt finds the change already applied and writes nothing.",
283
+ "fields": {
284
+ "stepType": "stepType",
285
+ "annotations": "annotations",
286
+ "connectionName": "connectionName",
287
+ "resultAttribute": "resultAttribute"
288
+ },
289
+ "branches": [
290
+ {
291
+ "id": "updated",
292
+ "field": "updated",
293
+ "optional": false
294
+ },
295
+ {
296
+ "id": "notFound",
297
+ "field": "notFound",
298
+ "optional": true
299
+ },
300
+ {
301
+ "id": "providerRejected",
302
+ "field": "providerRejected",
303
+ "optional": true
304
+ },
305
+ {
306
+ "id": "invalidResponse",
307
+ "field": "invalidResponse",
308
+ "optional": true
309
+ },
310
+ {
311
+ "id": "defect",
312
+ "field": "defect",
313
+ "optional": true
314
+ }
315
+ ],
316
+ "inputSchema": {
317
+ "additionalProperties": false,
318
+ "description": "UpdateTicketInput is one change to an existing ticket. Zero and empty fields are left unchanged; this release cannot clear an agent or group.",
319
+ "properties": {
320
+ "addTags": {
321
+ "description": "AddTags adds tags and keeps the ticket's other tags. A tag already present in any letter case is kept as is.",
322
+ "items": {
323
+ "type": "string"
324
+ },
325
+ "type": "array"
326
+ },
327
+ "groupId": {
328
+ "description": "GroupID assigns a group, or zero to keep the group.",
329
+ "type": "integer"
330
+ },
331
+ "priority": {
332
+ "description": "Priority is the new Freshdesk priority, or zero to keep it.",
333
+ "enum": [
334
+ 1,
335
+ 2,
336
+ 3,
337
+ 4
338
+ ],
339
+ "type": "integer"
340
+ },
341
+ "removeTags": {
342
+ "description": "RemoveTags removes tags in any letter case and keeps the ticket's other tags.",
343
+ "items": {
344
+ "type": "string"
345
+ },
346
+ "type": "array"
347
+ },
348
+ "responderId": {
349
+ "description": "ResponderID assigns an agent, Freshdesk's responder_id, or zero to keep the agent.",
350
+ "type": "integer"
351
+ },
352
+ "status": {
353
+ "description": "Status is the new Freshdesk status, including a custom one, or zero to keep it.",
354
+ "enum": [
355
+ 2,
356
+ 3,
357
+ 4,
358
+ 5,
359
+ 6,
360
+ 7
361
+ ],
362
+ "type": "integer"
363
+ },
364
+ "ticketId": {
365
+ "description": "TicketID is the Freshdesk ticket ID.",
366
+ "type": "integer"
367
+ }
368
+ },
369
+ "required": [
370
+ "ticketId"
371
+ ],
372
+ "type": "object"
373
+ }
374
+ },
375
+ {
376
+ "name": "newAddNoteStep",
377
+ "kind": "mutation",
378
+ "operationId": "addNote",
379
+ "inputType": "AddNoteInput",
380
+ "description": "Add one private note or one public reply to a ticket. The Step runs with sync durability; 429, 503, and traced pre-connection failures permit one next-attempt resend, while other dispatched outcomes are never resent.",
381
+ "fields": {
382
+ "stepType": "stepType",
383
+ "annotations": "annotations",
384
+ "connectionName": "connectionName",
385
+ "resultAttribute": "resultAttribute"
386
+ },
387
+ "branches": [
388
+ {
389
+ "id": "added",
390
+ "field": "added",
391
+ "optional": false
392
+ },
393
+ {
394
+ "id": "notFound",
395
+ "field": "notFound",
396
+ "optional": true
397
+ },
398
+ {
399
+ "id": "providerRejected",
400
+ "field": "providerRejected",
401
+ "optional": true
402
+ },
403
+ {
404
+ "id": "uncertain",
405
+ "field": "uncertain",
406
+ "optional": true
407
+ },
408
+ {
409
+ "id": "defect",
410
+ "field": "defect",
411
+ "optional": true
412
+ }
413
+ ],
414
+ "inputSchema": {
415
+ "additionalProperties": false,
416
+ "description": "AddNoteInput is one private note or one public reply to add to a ticket.",
417
+ "properties": {
418
+ "body": {
419
+ "description": "Body is the plain-text note or reply. It is required. The connector escapes it into Freshdesk's HTML body, so markup is shown literally and line breaks are kept.",
420
+ "type": "string"
421
+ },
422
+ "isPublicReply": {
423
+ "description": "IsPublicReply sends the body as a reply that Freshdesk emails to the requester, through POST /api/v2/tickets/{id}/reply. False adds a private note that only agents can see.",
424
+ "type": "boolean"
425
+ },
426
+ "ticketId": {
427
+ "description": "TicketID is the Freshdesk ticket ID.",
428
+ "type": "integer"
429
+ }
430
+ },
431
+ "required": [
432
+ "body",
433
+ "ticketId"
434
+ ],
435
+ "type": "object"
436
+ }
437
+ },
438
+ {
439
+ "name": "defineTicketChangedTriggerBinding",
440
+ "kind": "trigger",
441
+ "triggerName": "ticketChanged",
442
+ "fields": {
443
+ "connectionName": "connectionName",
444
+ "bindingName": "bindingName",
445
+ "configurationUI": "configurationUI"
446
+ }
447
+ }
448
+ ]
449
+ }