@superdurable/connector-hubspot 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,28 @@
1
- # Temporary Holding Version
1
+ # HubSpot 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-hubspot` provides Dex Steps for `searchObjects`, `getObject`, `upsertObject`, and `updateObject`, and, from 0.2.0, the `crmObjectChanged` poll Trigger at parity with the Go connector. It requires `@superdurable/connectors-sdk` 0.12.0 and `@superdurable/dex` 1.45.4 or newer. It supports HubSpot private app tokens and HubSpot OAuth. The connection resolves credentials at dispatch, refreshes OAuth tokens through the generated manifest driver, and retries one request after a rejected OAuth access token. The two writes are repeat-safe: upsert uses a unique HubSpot property and update replaces named property values.
4
+
5
+ The [search deals example](examples/search-deals/README.md) is a runnable Flow with a Worker entrypoint and static `hubspot-crm` connection name. Create that connection in Dex Web **Connections**. For private apps, open [HubSpot](https://app.hubspot.com/), choose **Development > Legacy apps > Create legacy app > Private**, grant the CRM read and write scopes listed in `connector.yaml`, and copy the access token from the app's **Auth** tab. For OAuth, choose a public legacy app or project app, register the redirect URI shown in Dex Web on the app's **Auth** tab, add the manifest scopes, enter the client ID and secret, and complete consent. Dex Web holds the credentials; they never enter Flow input or output.
6
+
7
+ From this directory, run `npm ci`, `npm run check`, `npm run example:search`, and `npm run example:changes`. To submit the sample input, run `npm run example:search:start -- examples/search-deals/input.example.json` in another terminal. Set `DEX_FLOW_SERVICE_ADDRESS` when Dex uses a nondefault port. `npm run test:integration` runs the same Flow through a real Dex Worker and Client against a local provider stand-in.
8
+
9
+ The package exports generated Config, Credentials, operation models, definitions, Step factories, and mock cases. Use `newProjectConnection(project, ConnectionName)` to bind the project connection, or `newConnection(new HubSpotClient(config, credentialSource), reference)` when constructing a client directly. The provider endpoint defaults to HubSpot's public API; `maxResponseBytes` defaults to one MiB; `pollIntervalMs` defaults to 30 seconds and must be at least 5 seconds. A project connection reads the saved `pollInterval` as Go `time.Duration` nanoseconds.
10
+
11
+ ## crmObjectChanged Trigger
12
+
13
+ `crmObjectChanged` polls one object type, `contacts`, `companies`, or `deals`, through HubSpot CRM search and delivers one `CRMObjectChangedEvent` per created or changed record: `objectType`, `changeKind` (`created` or `updated`), `modifiedAt`, and the `object` as search returned it. It is built on the `@superdurable/connectors-sdk/pollingtrigger` kit and follows the Go connector exactly: the first poll records the newest last-modified date as a baseline and delivers no existing record; later polls search ascending on `lastmodifieddate` (contacts) or `hs_lastmodifieddate`, 100 records per page, re-read a two-minute lag window for late-indexed records, and skip versions already delivered. A 429 or 423 pauses every binding of the connection for `Retry-After` or `X-HubSpot-RateLimit-Interval-Milliseconds`, an exhausted daily limit backs off up to 15 minutes, and a rejected paging offset or unusable cursor records a new baseline with a WARN record. The [connector README](../README.md#crmobjectchanged-trigger) describes the behavior in full.
14
+
15
+ The cursor document is the Go connector's JSON byte for byte, and the event ID is the same hash of object type, record ID, and last-modified millisecond, so Go and TypeScript replicas can share one binding's cursor and inbox. A test replays a scenario recorded from the Go fetcher (`test/fixtures/go-crm-object-change-cursors.json`) and compares every cursor token and event ID.
16
+
17
+ `newProjectCRMObjectTriggerRunner(project, connectionName, { crmObjectChangedRoutes }, options)` is the durable path: it loads each binding's saved object type, records every change in the binding's project Trigger inbox, and commits the search position in its project poll cursor only after that. From [`examples/crm-object-changed/app.ts`](examples/crm-object-changed/app.ts):
18
+
19
+ ```ts
20
+ const runner = newProjectCRMObjectTriggerRunner(project, ConnectionName, { crmObjectChangedRoutes: [{
21
+ bindingName: CRMObjectChangedTriggerBinding, properties: DeliveredProperties,
22
+ target: newDexFlowTriggerTarget(client, flow, acceptEveryCRMObjectChange, resolveFlowId, mapToFlowInput, { logger: options.logger }),
23
+ }] }, hubspotOptions);
24
+ ```
25
+
26
+ Run it with `runner.run(newTriggerContext(signal))`; `runner.wakePoller(bindingName)` polls a binding at once. `newCRMObjectTriggerRunner` takes targets and cursor stores directly, and `newCRMObjectChangedTrigger` builds one binding for `newTrigger`; both keep the cursor in memory unless given a store, so a restart records a new baseline. `defineCRMObjectChangedTriggerBinding` declares a Flow's static binding with the `objectTypePicker` unit (`UIUnitObjectTypePicker`, port `objectType`). The `logger` client option receives seed, reseed, failure, pause, and inbox records, which never contain record properties or credentials.
27
+
28
+ The [crm-object-changed example](examples/crm-object-changed/README.md) starts one Flow per change. `npm run test:integration` runs it on a real Dex Worker and Client against a local HubSpot search stand-in, covering the baseline, one Flow per change, changes made while the process was stopped, and a 429 pause. Live HubSpot search has not been verified.
@@ -0,0 +1,426 @@
1
+ {
2
+ "connectorId": "hubspot",
3
+ "releaseTag": "connectors/hubspot/go/v0.25.0",
4
+ "package": {
5
+ "ecosystem": "npm",
6
+ "name": "@superdurable/connector-hubspot",
7
+ "version": "0.2.0"
8
+ },
9
+ "factories": [
10
+ {
11
+ "name": "newSearchObjectsStep",
12
+ "kind": "query",
13
+ "operationId": "searchObjects",
14
+ "inputType": "SearchObjectsInput",
15
+ "description": "Search one bounded page of HubSpot contacts, companies, or deals with typed property filters, one sort, and an after 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
+ "SearchFilter": {
47
+ "additionalProperties": false,
48
+ "description": "SearchFilter is one typed CRM search condition.",
49
+ "properties": {
50
+ "highValue": {
51
+ "description": "HighValue is the inclusive upper bound for BETWEEN.",
52
+ "type": "string"
53
+ },
54
+ "operator": {
55
+ "description": "Operator selects the comparison.",
56
+ "enum": [
57
+ "BETWEEN",
58
+ "CONTAINS_TOKEN",
59
+ "EQ",
60
+ "GT",
61
+ "GTE",
62
+ "HAS_PROPERTY",
63
+ "IN",
64
+ "LT",
65
+ "LTE",
66
+ "NEQ",
67
+ "NOT_CONTAINS_TOKEN",
68
+ "NOT_HAS_PROPERTY",
69
+ "NOT_IN"
70
+ ],
71
+ "type": "string"
72
+ },
73
+ "propertyName": {
74
+ "description": "PropertyName is an internal property name such as email, or an association pseudo-property such as associations.contact.",
75
+ "type": "string"
76
+ },
77
+ "value": {
78
+ "description": "Value is the comparison value for EQ, NEQ, LT, LTE, GT, GTE, BETWEEN, CONTAINS_TOKEN, and NOT_CONTAINS_TOKEN. Dates are Unix milliseconds.",
79
+ "type": "string"
80
+ },
81
+ "values": {
82
+ "description": "Values lists the candidates for IN and NOT_IN. HubSpot requires lowercase values when the property is a string property.",
83
+ "items": {
84
+ "type": "string"
85
+ },
86
+ "type": "array"
87
+ }
88
+ },
89
+ "required": [
90
+ "operator",
91
+ "propertyName"
92
+ ],
93
+ "type": "object"
94
+ },
95
+ "SearchFilterGroup": {
96
+ "additionalProperties": false,
97
+ "description": "SearchFilterGroup AND-s its filters. A search OR-s its groups.",
98
+ "properties": {
99
+ "filters": {
100
+ "description": "Filters are the conditions that must all match.",
101
+ "items": {
102
+ "$ref": "#/$defs/SearchFilter"
103
+ },
104
+ "type": [
105
+ "array",
106
+ "null"
107
+ ]
108
+ }
109
+ },
110
+ "required": [
111
+ "filters"
112
+ ],
113
+ "type": "object"
114
+ },
115
+ "SearchSort": {
116
+ "additionalProperties": false,
117
+ "description": "SearchSort orders search results by one property.",
118
+ "properties": {
119
+ "direction": {
120
+ "description": "Direction is ascending or descending.",
121
+ "enum": [
122
+ "ASCENDING",
123
+ "DESCENDING"
124
+ ],
125
+ "type": "string"
126
+ },
127
+ "propertyName": {
128
+ "description": "PropertyName is the internal property name to sort by.",
129
+ "type": "string"
130
+ }
131
+ },
132
+ "required": [
133
+ "direction",
134
+ "propertyName"
135
+ ],
136
+ "type": "object"
137
+ }
138
+ },
139
+ "additionalProperties": false,
140
+ "description": "SearchObjectsInput selects one bounded page of matching records.",
141
+ "properties": {
142
+ "after": {
143
+ "description": "After is the NextAfter cursor of the previous page; empty starts at the first result. Paging cannot pass HubSpot's 10,000th result.",
144
+ "type": "string"
145
+ },
146
+ "filterGroups": {
147
+ "description": "FilterGroups are OR-ed; empty matches every record. HubSpot allows five groups, six filters per group, and eighteen filters in total.",
148
+ "items": {
149
+ "$ref": "#/$defs/SearchFilterGroup"
150
+ },
151
+ "type": "array"
152
+ },
153
+ "limit": {
154
+ "description": "Limit is the page size from 1 through 200; zero uses 10.",
155
+ "type": "integer"
156
+ },
157
+ "objectType": {
158
+ "description": "ObjectType is the object type to search.",
159
+ "enum": [
160
+ "companies",
161
+ "contacts",
162
+ "deals"
163
+ ],
164
+ "type": "string"
165
+ },
166
+ "properties": {
167
+ "description": "Properties lists the property values to return; empty returns HubSpot's default properties for the object type.",
168
+ "items": {
169
+ "type": "string"
170
+ },
171
+ "type": "array"
172
+ },
173
+ "query": {
174
+ "description": "Query optionally searches the object's default text properties.",
175
+ "type": "string"
176
+ },
177
+ "sort": {
178
+ "$ref": "#/$defs/SearchSort",
179
+ "description": "Sort optionally orders results; without it HubSpot returns oldest records first."
180
+ }
181
+ },
182
+ "required": [
183
+ "objectType"
184
+ ],
185
+ "type": "object"
186
+ }
187
+ },
188
+ {
189
+ "name": "newGetObjectStep",
190
+ "kind": "query",
191
+ "operationId": "getObject",
192
+ "inputType": "GetObjectInput",
193
+ "description": "Read one HubSpot contact, company, or deal by record ID with the requested properties.",
194
+ "fields": {
195
+ "stepType": "stepType",
196
+ "annotations": "annotations",
197
+ "connectionName": "connectionName",
198
+ "resultAttribute": "resultAttribute"
199
+ },
200
+ "branches": [
201
+ {
202
+ "id": "found",
203
+ "field": "found",
204
+ "optional": false
205
+ },
206
+ {
207
+ "id": "notFound",
208
+ "field": "notFound",
209
+ "optional": true
210
+ },
211
+ {
212
+ "id": "providerRejected",
213
+ "field": "providerRejected",
214
+ "optional": true
215
+ },
216
+ {
217
+ "id": "invalidResponse",
218
+ "field": "invalidResponse",
219
+ "optional": true
220
+ },
221
+ {
222
+ "id": "defect",
223
+ "field": "defect",
224
+ "optional": true
225
+ }
226
+ ],
227
+ "inputSchema": {
228
+ "additionalProperties": false,
229
+ "description": "GetObjectInput identifies one record.",
230
+ "properties": {
231
+ "objectId": {
232
+ "description": "ObjectID is HubSpot's decimal record ID.",
233
+ "type": "string"
234
+ },
235
+ "objectType": {
236
+ "description": "ObjectType is the record's object type.",
237
+ "enum": [
238
+ "companies",
239
+ "contacts",
240
+ "deals"
241
+ ],
242
+ "type": "string"
243
+ },
244
+ "properties": {
245
+ "description": "Properties lists the property values to return; empty returns HubSpot's default properties for the object type.",
246
+ "items": {
247
+ "type": "string"
248
+ },
249
+ "type": "array"
250
+ }
251
+ },
252
+ "required": [
253
+ "objectId",
254
+ "objectType"
255
+ ],
256
+ "type": "object"
257
+ }
258
+ },
259
+ {
260
+ "name": "newUpsertObjectStep",
261
+ "kind": "mutation",
262
+ "operationId": "upsertObject",
263
+ "inputType": "UpsertObjectInput",
264
+ "description": "Create or update one HubSpot contact, company, or deal identified by a unique property, such as email for contacts.",
265
+ "fields": {
266
+ "stepType": "stepType",
267
+ "annotations": "annotations",
268
+ "connectionName": "connectionName",
269
+ "resultAttribute": "resultAttribute"
270
+ },
271
+ "branches": [
272
+ {
273
+ "id": "upserted",
274
+ "field": "upserted",
275
+ "optional": false
276
+ },
277
+ {
278
+ "id": "conflict",
279
+ "field": "conflict",
280
+ "optional": true
281
+ },
282
+ {
283
+ "id": "providerRejected",
284
+ "field": "providerRejected",
285
+ "optional": true
286
+ },
287
+ {
288
+ "id": "invalidResponse",
289
+ "field": "invalidResponse",
290
+ "optional": true
291
+ },
292
+ {
293
+ "id": "defect",
294
+ "field": "defect",
295
+ "optional": true
296
+ }
297
+ ],
298
+ "inputSchema": {
299
+ "additionalProperties": false,
300
+ "description": "UpsertObjectInput creates or updates one record identified by a unique property value.",
301
+ "properties": {
302
+ "idProperty": {
303
+ "description": "IDProperty is a unique identifier property: email for contacts, or a custom property created with unique values for any object type.",
304
+ "type": "string"
305
+ },
306
+ "idValue": {
307
+ "description": "IDValue is the unique value that identifies the record, such as the email address.",
308
+ "type": "string"
309
+ },
310
+ "objectType": {
311
+ "description": "ObjectType is the record's object type.",
312
+ "enum": [
313
+ "companies",
314
+ "contacts",
315
+ "deals"
316
+ ],
317
+ "type": "string"
318
+ },
319
+ "properties": {
320
+ "additionalProperties": {
321
+ "type": "string"
322
+ },
323
+ "description": "Properties are the values to set, keyed by internal property name. An empty string clears a value.",
324
+ "type": "object"
325
+ }
326
+ },
327
+ "required": [
328
+ "idProperty",
329
+ "idValue",
330
+ "objectType"
331
+ ],
332
+ "type": "object"
333
+ }
334
+ },
335
+ {
336
+ "name": "newUpdateObjectStep",
337
+ "kind": "mutation",
338
+ "operationId": "updateObject",
339
+ "inputType": "UpdateObjectInput",
340
+ "description": "Update properties of one HubSpot contact, company, or deal by record ID.",
341
+ "fields": {
342
+ "stepType": "stepType",
343
+ "annotations": "annotations",
344
+ "connectionName": "connectionName",
345
+ "resultAttribute": "resultAttribute"
346
+ },
347
+ "branches": [
348
+ {
349
+ "id": "updated",
350
+ "field": "updated",
351
+ "optional": false
352
+ },
353
+ {
354
+ "id": "notFound",
355
+ "field": "notFound",
356
+ "optional": true
357
+ },
358
+ {
359
+ "id": "conflict",
360
+ "field": "conflict",
361
+ "optional": true
362
+ },
363
+ {
364
+ "id": "providerRejected",
365
+ "field": "providerRejected",
366
+ "optional": true
367
+ },
368
+ {
369
+ "id": "invalidResponse",
370
+ "field": "invalidResponse",
371
+ "optional": true
372
+ },
373
+ {
374
+ "id": "defect",
375
+ "field": "defect",
376
+ "optional": true
377
+ }
378
+ ],
379
+ "inputSchema": {
380
+ "additionalProperties": false,
381
+ "description": "UpdateObjectInput replaces property values on one record.",
382
+ "properties": {
383
+ "objectId": {
384
+ "description": "ObjectID is HubSpot's decimal record ID.",
385
+ "type": "string"
386
+ },
387
+ "objectType": {
388
+ "description": "ObjectType is the record's object type.",
389
+ "enum": [
390
+ "companies",
391
+ "contacts",
392
+ "deals"
393
+ ],
394
+ "type": "string"
395
+ },
396
+ "properties": {
397
+ "additionalProperties": {
398
+ "type": "string"
399
+ },
400
+ "description": "Properties are the values to set, keyed by internal property name. At least one is required, and an empty string clears a value.",
401
+ "type": [
402
+ "object",
403
+ "null"
404
+ ]
405
+ }
406
+ },
407
+ "required": [
408
+ "objectId",
409
+ "objectType",
410
+ "properties"
411
+ ],
412
+ "type": "object"
413
+ }
414
+ },
415
+ {
416
+ "name": "defineCRMObjectChangedTriggerBinding",
417
+ "kind": "trigger",
418
+ "triggerName": "crmObjectChanged",
419
+ "fields": {
420
+ "connectionName": "connectionName",
421
+ "bindingName": "bindingName",
422
+ "configurationUI": "configurationUI"
423
+ }
424
+ }
425
+ ]
426
+ }