@memberjunction/integration-connectors 5.13.0 → 5.15.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/README.md +241 -50
- package/dist/HubSpotConnector.d.ts +82 -4
- package/dist/HubSpotConnector.d.ts.map +1 -1
- package/dist/HubSpotConnector.js +649 -104
- package/dist/HubSpotConnector.js.map +1 -1
- package/dist/QuickBooksConnector.d.ts +92 -0
- package/dist/QuickBooksConnector.d.ts.map +1 -0
- package/dist/QuickBooksConnector.js +693 -0
- package/dist/QuickBooksConnector.js.map +1 -0
- package/dist/RasaConnector.d.ts +4 -19
- package/dist/RasaConnector.d.ts.map +1 -1
- package/dist/RasaConnector.js +74 -0
- package/dist/RasaConnector.js.map +1 -1
- package/dist/SageIntacctConnector.d.ts +179 -0
- package/dist/SageIntacctConnector.d.ts.map +1 -0
- package/dist/SageIntacctConnector.js +1008 -0
- package/dist/SageIntacctConnector.js.map +1 -0
- package/dist/SalesforceConnector.d.ts +233 -18
- package/dist/SalesforceConnector.d.ts.map +1 -1
- package/dist/SalesforceConnector.js +1136 -32
- package/dist/SalesforceConnector.js.map +1 -1
- package/dist/YourMembershipConnector.d.ts +4 -25
- package/dist/YourMembershipConnector.d.ts.map +1 -1
- package/dist/YourMembershipConnector.js +147 -3
- package/dist/YourMembershipConnector.js.map +1 -1
- package/dist/generate-integration-actions.d.ts +23 -0
- package/dist/generate-integration-actions.d.ts.map +1 -0
- package/dist/generate-integration-actions.js +201 -0
- package/dist/generate-integration-actions.js.map +1 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/package.json +7 -5
package/README.md
CHANGED
|
@@ -1,73 +1,250 @@
|
|
|
1
1
|
# @memberjunction/integration-connectors
|
|
2
2
|
|
|
3
|
-
Concrete integration connectors for the MemberJunction Integration Engine. This package provides
|
|
3
|
+
Concrete integration connectors for the MemberJunction Integration Engine. This package provides connectors for CRM, accounting, membership, newsletter, and file-based systems — all implementing `BaseIntegrationConnector` from `@memberjunction/integration-engine`.
|
|
4
4
|
|
|
5
5
|
## Connectors
|
|
6
6
|
|
|
7
|
-
###
|
|
7
|
+
### Production REST API Connectors
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
These connectors call live external APIs and extend `BaseRESTIntegrationConnector`.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
#### SalesforceConnector
|
|
12
|
+
|
|
13
|
+
Production connector for Salesforce CRM using the REST API v61.0 with full bidirectional sync.
|
|
14
|
+
|
|
15
|
+
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'SalesforceConnector')`
|
|
16
|
+
|
|
17
|
+
**Authentication — Two Supported Flows:**
|
|
18
|
+
|
|
19
|
+
The connector auto-detects the auth flow based on the credentials provided.
|
|
20
|
+
|
|
21
|
+
**1. Client Credentials Flow** (recommended for new setups):
|
|
12
22
|
```json
|
|
13
23
|
{
|
|
14
|
-
"
|
|
15
|
-
"
|
|
16
|
-
"
|
|
17
|
-
"
|
|
24
|
+
"authFlow": "client_credentials",
|
|
25
|
+
"loginUrl": "https://myorg.my.salesforce.com",
|
|
26
|
+
"clientId": "3MVG9...your-consumer-key",
|
|
27
|
+
"clientSecret": "D4A28...your-client-secret",
|
|
28
|
+
"apiVersion": "61.0"
|
|
18
29
|
}
|
|
19
30
|
```
|
|
20
31
|
|
|
21
|
-
**
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
32
|
+
**2. JWT Bearer Token Flow** (RS256, certificate-based):
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"authFlow": "jwt_bearer",
|
|
36
|
+
"loginUrl": "https://login.salesforce.com",
|
|
37
|
+
"tokenUrl": "https://myorg.my.salesforce.com",
|
|
38
|
+
"clientId": "3MVG9...your-consumer-key",
|
|
39
|
+
"username": "integration-user@myorg.com",
|
|
40
|
+
"privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
|
|
41
|
+
"apiVersion": "61.0"
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| Field | Required | Description |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `loginUrl` | Yes | Org URL. For Client Credentials: My Domain URL. For JWT: `login.salesforce.com` (prod) or `test.salesforce.com` (sandbox) as the JWT audience. |
|
|
48
|
+
| `clientId` | Yes | Connected App Consumer Key |
|
|
49
|
+
| `clientSecret` | CC only | Client Secret from Connected App |
|
|
50
|
+
| `username` | JWT only | Integration user's Salesforce email |
|
|
51
|
+
| `privateKey` | JWT only | PEM-encoded RSA private key (matching X.509 cert uploaded to Connected App) |
|
|
52
|
+
| `tokenUrl` | No | Token endpoint URL if different from `loginUrl` (e.g., My Domain URL for JWT flow) |
|
|
53
|
+
| `apiVersion` | No | Salesforce REST API version (default: `61.0`) |
|
|
54
|
+
| `authFlow` | No | Explicit flow selection. Auto-detected: `clientSecret` present → `client_credentials`; `privateKey` + `username` present → `jwt_bearer` |
|
|
55
|
+
|
|
56
|
+
**Capabilities:**
|
|
57
|
+
- Full CRUD (Create, Read, Update, Delete)
|
|
58
|
+
- SOQL-based search
|
|
59
|
+
- Live schema discovery via Describe API (standard + custom objects)
|
|
60
|
+
- Incremental sync with `SystemModstamp` watermarks and `queryAll` for deleted records
|
|
61
|
+
- Governor limit tracking (throttles at 80%, pauses at 95%)
|
|
62
|
+
- Automatic token caching and refresh
|
|
63
|
+
|
|
64
|
+
**Standard Objects (9):** Account, Contact, Lead, Opportunity, Task, Event, Case, Campaign, User (read-only)
|
|
65
|
+
|
|
66
|
+
**Default field mappings:**
|
|
67
|
+
| Source Object | Target Entity | Key Mappings |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| Contact | Contacts | Email (key), FirstName, LastName, Phone, MobilePhone, Title, Department, mailing address fields (12 total) |
|
|
70
|
+
| Account | Companies | Name (key), Industry, Phone, Website, billing address fields, Type, AnnualRevenue, NumberOfEmployees (10 total) |
|
|
71
|
+
| Lead | Contacts | Email (key), FirstName, LastName, Company, Phone, Title (6 total) |
|
|
72
|
+
|
|
73
|
+
See also: [Connector usage guide](../docs/salesforce-connector.md) · [Connected App setup guide](../docs/salesforce-connected-app-setup.md)
|
|
27
74
|
|
|
28
|
-
|
|
75
|
+
#### HubSpotConnector
|
|
29
76
|
|
|
30
|
-
|
|
77
|
+
Production connector for HubSpot CRM using the V3 API with full bidirectional sync, including association objects.
|
|
31
78
|
|
|
32
79
|
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'HubSpotConnector')`
|
|
33
80
|
|
|
81
|
+
**Authentication:** OAuth2 Bearer token via HubSpot Private App credentials.
|
|
82
|
+
|
|
83
|
+
**Capabilities:** Full CRUD, search, list, association fetching (v4 per-object associations endpoint)
|
|
84
|
+
|
|
85
|
+
**Objects:** Contacts, Companies, Deals, Owners, Tickets, Line Items, plus association objects (Contact↔Company, Deal↔Company, etc.)
|
|
86
|
+
|
|
34
87
|
**Default field mappings:**
|
|
35
|
-
| Source Object | Target Entity | Mappings |
|
|
88
|
+
| Source Object | Target Entity | Key Mappings |
|
|
36
89
|
|---|---|---|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
| `hs_Deals` | — | No default mappings |
|
|
90
|
+
| Contacts | Contacts | email (key), firstname, lastname, phone, company, lifecyclestage |
|
|
91
|
+
| Companies | Companies | name (key), domain, industry, city, state |
|
|
40
92
|
|
|
41
|
-
|
|
93
|
+
#### RasaConnector
|
|
42
94
|
|
|
43
|
-
|
|
95
|
+
Production connector for Rasa.io newsletter platform. Read-only — pulls newsletter and subscriber data.
|
|
44
96
|
|
|
45
|
-
|
|
97
|
+
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'RasaConnector')`
|
|
46
98
|
|
|
47
|
-
**
|
|
99
|
+
**Authentication:** Basic auth (username/password) to obtain a JWT, scoped to a community ID.
|
|
100
|
+
|
|
101
|
+
**Objects:** Newsletters, Newsletter Sections, Newsletter Section Items, Subscribers
|
|
102
|
+
|
|
103
|
+
#### WicketConnector
|
|
104
|
+
|
|
105
|
+
Production connector for Wicket membership management platform with full bidirectional sync.
|
|
106
|
+
|
|
107
|
+
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'WicketConnector')`
|
|
108
|
+
|
|
109
|
+
**Authentication:** HMAC-SHA256 signed requests.
|
|
110
|
+
|
|
111
|
+
**Capabilities:** Full CRUD, search
|
|
112
|
+
|
|
113
|
+
### Accounting Connectors
|
|
114
|
+
|
|
115
|
+
These connectors integrate with accounting and ERP systems.
|
|
116
|
+
|
|
117
|
+
#### SageIntacctConnector
|
|
118
|
+
|
|
119
|
+
Production connector for Sage Intacct accounting/ERP using the XML Web Services API with full bidirectional sync.
|
|
120
|
+
|
|
121
|
+
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'SageIntacctConnector')`
|
|
122
|
+
|
|
123
|
+
**Authentication:** Session-based — Sender ID/Password (app credentials) + User ID/Password authenticate via `getAPISession`, returning a session ID for subsequent requests.
|
|
124
|
+
|
|
125
|
+
**Credentials JSON:**
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"CompanyId": "your-company-id",
|
|
129
|
+
"SenderId": "your-sender-id",
|
|
130
|
+
"SenderPassword": "your-sender-password",
|
|
131
|
+
"UserId": "your-user-id",
|
|
132
|
+
"UserPassword": "your-user-password",
|
|
133
|
+
"EntityId": "optional-entity-id"
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
| Field | Required | Description |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `CompanyId` | Yes | Sage Intacct Company ID |
|
|
140
|
+
| `SenderId` | Yes | Web Services Sender ID (from Marketplace subscription) |
|
|
141
|
+
| `SenderPassword` | Yes | Web Services Sender Password |
|
|
142
|
+
| `UserId` | Yes | User ID for API authentication |
|
|
143
|
+
| `UserPassword` | Yes | User password |
|
|
144
|
+
| `EntityId` | No | Entity ID for multi-entity shared companies |
|
|
145
|
+
|
|
146
|
+
**Capabilities:**
|
|
147
|
+
- Full CRUD (Create, Read, Update, Delete)
|
|
148
|
+
- Query-based search via `readByQuery`
|
|
149
|
+
- Paginated listing via `readMore`
|
|
150
|
+
- Live schema discovery via `inspect` API
|
|
151
|
+
- Incremental sync with `WHENMODIFIED` watermarks
|
|
152
|
+
- Session caching and automatic refresh
|
|
153
|
+
- Retry with exponential backoff
|
|
154
|
+
|
|
155
|
+
**Objects (9):** Customer, Vendor, GL Account, AP Bill, AR Invoice, Project, Employee, Department, Class
|
|
156
|
+
|
|
157
|
+
**Default field mappings:**
|
|
158
|
+
| Source Object | Target Entity | Key Mappings |
|
|
159
|
+
|---|---|---|
|
|
160
|
+
| CUSTOMER | Contacts | CUSTOMERID (key), NAME, EMAIL, PHONE, STATUS |
|
|
161
|
+
| VENDOR | Companies | VENDORID (key), NAME, EMAIL, PHONE, STATUS |
|
|
162
|
+
|
|
163
|
+
#### QuickBooksConnector
|
|
164
|
+
|
|
165
|
+
Production connector for QuickBooks Online using the REST API v3 with OAuth 2.0 authentication.
|
|
166
|
+
|
|
167
|
+
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'QuickBooksConnector')`
|
|
168
|
+
|
|
169
|
+
**Authentication:** OAuth 2.0 with automatic token refresh. Requires a QuickBooks app with client ID/secret and an initial refresh token obtained through the OAuth consent flow.
|
|
170
|
+
|
|
171
|
+
**Credentials JSON:**
|
|
172
|
+
```json
|
|
173
|
+
{
|
|
174
|
+
"ClientId": "your-client-id",
|
|
175
|
+
"ClientSecret": "your-client-secret",
|
|
176
|
+
"RefreshToken": "your-refresh-token",
|
|
177
|
+
"RealmId": "your-company-realm-id",
|
|
178
|
+
"Environment": "production"
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
| Field | Required | Description |
|
|
183
|
+
|---|---|---|
|
|
184
|
+
| `ClientId` | Yes | OAuth 2.0 Client ID from QuickBooks developer portal |
|
|
185
|
+
| `ClientSecret` | Yes | OAuth 2.0 Client Secret |
|
|
186
|
+
| `RefreshToken` | Yes | OAuth 2.0 refresh token (auto-refreshed on each use) |
|
|
187
|
+
| `RealmId` | Yes | QuickBooks Company ID (Realm ID) |
|
|
188
|
+
| `Environment` | No | `production` (default) or `sandbox` |
|
|
189
|
+
|
|
190
|
+
**Capabilities:**
|
|
191
|
+
- Full CRUD (Create, Read, Update, Delete)
|
|
192
|
+
- SQL-like query via QuickBooks Query Language
|
|
193
|
+
- Paginated listing
|
|
194
|
+
- Live schema discovery
|
|
195
|
+
- Incremental sync with `MetaData.LastUpdatedTime` watermarks
|
|
196
|
+
- Automatic OAuth token refresh
|
|
197
|
+
- Minor version pinning for API stability
|
|
198
|
+
|
|
199
|
+
**Objects (10):** Customer, Vendor, Account, Invoice, Bill, Item, Payment, Employee, Department, Class
|
|
48
200
|
|
|
49
201
|
**Default field mappings:**
|
|
50
|
-
| Source Object | Target Entity | Mappings |
|
|
202
|
+
| Source Object | Target Entity | Key Mappings |
|
|
51
203
|
|---|---|---|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
204
|
+
| Customer | Contacts | Id (key), DisplayName, PrimaryEmailAddr, PrimaryPhone, Active |
|
|
205
|
+
| Vendor | Companies | Id (key), DisplayName, PrimaryEmailAddr, PrimaryPhone, Active |
|
|
54
206
|
|
|
55
|
-
|
|
207
|
+
### SQL-Based Connectors
|
|
56
208
|
|
|
57
|
-
|
|
209
|
+
These connectors read from SQL Server databases and extend `RelationalDBConnector`.
|
|
58
210
|
|
|
59
|
-
|
|
211
|
+
#### RelationalDBConnector (Base Class)
|
|
212
|
+
|
|
213
|
+
Abstract base class for connectors backed by SQL Server via the `mssql` package.
|
|
214
|
+
|
|
215
|
+
**Configuration JSON:**
|
|
216
|
+
```json
|
|
217
|
+
{
|
|
218
|
+
"server": "your-sql-server",
|
|
219
|
+
"database": "YourDatabase",
|
|
220
|
+
"user": "username",
|
|
221
|
+
"password": "password"
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Shared capabilities:**
|
|
226
|
+
- `TestConnection` — runs `SELECT @@VERSION`
|
|
227
|
+
- `DiscoverObjects` — queries `INFORMATION_SCHEMA.TABLES`
|
|
228
|
+
- `DiscoverFields` — queries `INFORMATION_SCHEMA.COLUMNS`
|
|
229
|
+
- `FetchChangesFromTable` — incremental fetch with watermark filtering and batch limiting
|
|
230
|
+
- Connection pool caching per server+database pair
|
|
231
|
+
|
|
232
|
+
#### YourMembershipConnector
|
|
233
|
+
|
|
234
|
+
Reads from YourMembership database tables: `ym_Members`, `ym_Events`, `ym_EventRegistrations`, `ym_Chapters`, `ym_MembershipLevels`.
|
|
60
235
|
|
|
61
236
|
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'YourMembershipConnector')`
|
|
62
237
|
|
|
63
238
|
**Default field mappings:**
|
|
64
|
-
| Source Object | Target Entity | Mappings |
|
|
239
|
+
| Source Object | Target Entity | Key Mappings |
|
|
65
240
|
|---|---|---|
|
|
66
|
-
|
|
|
241
|
+
| ym_Members | Contacts | email (key), first_name, last_name, phone, status |
|
|
242
|
+
|
|
243
|
+
### File-Based Connectors
|
|
67
244
|
|
|
68
|
-
|
|
245
|
+
#### FileFeedConnector
|
|
69
246
|
|
|
70
|
-
Reads data from local CSV files. Always performs a full load (no incremental sync
|
|
247
|
+
Reads data from local CSV files. Always performs a full load (no incremental sync).
|
|
71
248
|
|
|
72
249
|
**Registration:** `@RegisterClass(BaseIntegrationConnector, 'FileFeedConnector')`
|
|
73
250
|
|
|
@@ -83,13 +260,24 @@ Reads data from local CSV files. Always performs a full load (no incremental syn
|
|
|
83
260
|
- `TestConnection` — checks that the file exists on disk
|
|
84
261
|
- `DiscoverObjects` — returns the file name as the single available object
|
|
85
262
|
- `DiscoverFields` — parses the CSV header row
|
|
86
|
-
- `FetchChanges` — parses all
|
|
263
|
+
- `FetchChanges` — parses all rows into `ExternalRecord[]` (watermark ignored)
|
|
264
|
+
|
|
265
|
+
## Action Generation
|
|
87
266
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
267
|
+
Integration connectors can auto-generate MJ Action metadata for use by AI agents and workflow engines. Each connector declares its objects and fields via `GetIntegrationObjects()`, and the CLI generator produces mj-sync compatible JSON files.
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
# Generate actions for all connectors
|
|
271
|
+
npx tsx src/generate-integration-actions.ts
|
|
272
|
+
|
|
273
|
+
# Generate for a specific connector
|
|
274
|
+
npx tsx src/generate-integration-actions.ts salesforce
|
|
275
|
+
npx tsx src/generate-integration-actions.ts hubspot
|
|
276
|
+
npx tsx src/generate-integration-actions.ts sage-intacct
|
|
277
|
+
npx tsx src/generate-integration-actions.ts quickbooks
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
See [INTEGRATION_ACTIONS.md](../INTEGRATION_ACTIONS.md) for full documentation.
|
|
93
281
|
|
|
94
282
|
## Building
|
|
95
283
|
|
|
@@ -100,8 +288,6 @@ npm run build
|
|
|
100
288
|
|
|
101
289
|
## Testing
|
|
102
290
|
|
|
103
|
-
Tests are integration tests that connect to the mock SQL Server databases.
|
|
104
|
-
|
|
105
291
|
```bash
|
|
106
292
|
cd packages/Integration/connectors
|
|
107
293
|
npm run test # single run
|
|
@@ -112,13 +298,18 @@ npm run test:watch # watch mode
|
|
|
112
298
|
|
|
113
299
|
```
|
|
114
300
|
src/
|
|
115
|
-
index.ts
|
|
116
|
-
RelationalDBConnector.ts
|
|
117
|
-
HubSpotConnector.ts
|
|
118
|
-
SalesforceConnector.ts
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
301
|
+
index.ts # Package exports
|
|
302
|
+
RelationalDBConnector.ts # Base class for SQL-based connectors
|
|
303
|
+
HubSpotConnector.ts # HubSpot REST API connector (full CRUD)
|
|
304
|
+
SalesforceConnector.ts # Salesforce REST API connector (full CRUD)
|
|
305
|
+
SageIntacctConnector.ts # Sage Intacct XML API connector (full CRUD)
|
|
306
|
+
QuickBooksConnector.ts # QuickBooks Online REST API connector (full CRUD)
|
|
307
|
+
RasaConnector.ts # Rasa.io REST API connector (read-only)
|
|
308
|
+
WicketConnector.ts # Wicket REST API connector (full CRUD)
|
|
309
|
+
YourMembershipConnector.ts # YourMembership SQL connector
|
|
310
|
+
FileFeedConnector.ts # CSV file connector
|
|
311
|
+
generate-integration-actions.ts # CLI: auto-generate action metadata from connectors
|
|
312
|
+
__tests__/ # Unit and integration tests
|
|
122
313
|
test-fixtures/
|
|
123
|
-
sample-contacts.csv
|
|
314
|
+
sample-contacts.csv # 100-row sample for FileFeed testing
|
|
124
315
|
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type UserInfo } from '@memberjunction/core';
|
|
2
2
|
import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
|
|
3
|
-
import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type DefaultFieldMapping, type DefaultIntegrationConfig } from '@memberjunction/integration-engine';
|
|
3
|
+
import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type DefaultFieldMapping, type DefaultIntegrationConfig, type FetchContext, type FetchBatchResult, type ExternalRecord, type CRUDResult, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type GetRecordContext, type SearchContext, type SearchResult, type ListContext, type ListResult, type IntegrationObjectInfo, type ActionGeneratorConfig } from '@memberjunction/integration-engine';
|
|
4
4
|
/** Connection configuration parsed from CompanyIntegration.Configuration JSON */
|
|
5
5
|
export interface HubSpotConnectionConfig {
|
|
6
6
|
/** HubSpot access token (private app key or OAuth token) */
|
|
@@ -46,7 +46,8 @@ interface HubSpotPropertyDef {
|
|
|
46
46
|
* "MinRequestIntervalMs": 100 // optional, default: 100
|
|
47
47
|
* }
|
|
48
48
|
*
|
|
49
|
-
*
|
|
49
|
+
* Supports full CRUD: Get, Create, Update, Delete, Search, and List operations
|
|
50
|
+
* on all HubSpot CRM object types.
|
|
50
51
|
*/
|
|
51
52
|
export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
|
|
52
53
|
/** Timestamp of the last API request, used for throttling */
|
|
@@ -56,9 +57,47 @@ export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
|
|
|
56
57
|
private get effectiveMaxRetries();
|
|
57
58
|
private get effectiveRequestTimeoutMs();
|
|
58
59
|
private get effectiveMinRequestIntervalMs();
|
|
60
|
+
get SupportsCreate(): boolean;
|
|
61
|
+
get SupportsUpdate(): boolean;
|
|
62
|
+
get SupportsDelete(): boolean;
|
|
63
|
+
get SupportsSearch(): boolean;
|
|
64
|
+
get SupportsListing(): boolean;
|
|
65
|
+
get IntegrationName(): string;
|
|
66
|
+
GetIntegrationObjects(): IntegrationObjectInfo[];
|
|
67
|
+
GetActionGeneratorConfig(): ActionGeneratorConfig | null;
|
|
68
|
+
/**
|
|
69
|
+
* Retrieves a single record by ExternalID (HubSpot object ID).
|
|
70
|
+
*/
|
|
71
|
+
GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
|
|
72
|
+
/**
|
|
73
|
+
* Creates a new record in HubSpot.
|
|
74
|
+
*/
|
|
75
|
+
CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
|
|
76
|
+
/**
|
|
77
|
+
* Updates an existing record in HubSpot by ExternalID.
|
|
78
|
+
*/
|
|
79
|
+
UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
|
|
80
|
+
/**
|
|
81
|
+
* Deletes (archives) a record in HubSpot by ExternalID.
|
|
82
|
+
*/
|
|
83
|
+
DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
|
|
84
|
+
/**
|
|
85
|
+
* Searches HubSpot objects using the CRM search API.
|
|
86
|
+
*/
|
|
87
|
+
SearchRecords(ctx: SearchContext): Promise<SearchResult>;
|
|
88
|
+
/**
|
|
89
|
+
* Lists records from a HubSpot object with cursor-based pagination.
|
|
90
|
+
*/
|
|
91
|
+
ListRecords(ctx: ListContext): Promise<ListResult>;
|
|
92
|
+
/** Converts a raw HubSpot API object to an ExternalRecord. */
|
|
93
|
+
private RawToExternalRecord;
|
|
94
|
+
/** Validates a CRUD response and throws on non-2xx status. */
|
|
95
|
+
private ValidateCRUDResponse;
|
|
96
|
+
/** Builds a CRUDResult for error responses. */
|
|
97
|
+
private BuildCRUDErrorResult;
|
|
59
98
|
protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
|
|
60
99
|
protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
|
|
61
|
-
protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>,
|
|
100
|
+
protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
|
|
62
101
|
protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
|
|
63
102
|
protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
|
|
64
103
|
protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, _auth: RESTAuthContext): string;
|
|
@@ -109,17 +148,56 @@ export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
|
|
|
109
148
|
* plus system fields (hs_object_id, createdAt, updatedAt, archived).
|
|
110
149
|
*/
|
|
111
150
|
private FlattenHubSpotRecord;
|
|
151
|
+
/**
|
|
152
|
+
* Overrides FetchChanges to intercept association objects (Category === 'Association')
|
|
153
|
+
* and route them through the v4 per-object associations endpoint instead of the
|
|
154
|
+
* non-existent flat list endpoint stored in APIPath.
|
|
155
|
+
*/
|
|
156
|
+
FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
|
|
157
|
+
/**
|
|
158
|
+
* Fetches association records in batches by iterating over synced parent (from-side)
|
|
159
|
+
* objects and calling HubSpot's v4 per-object associations endpoint.
|
|
160
|
+
*
|
|
161
|
+
* Uses ctx.CurrentOffset to track parent position across batch calls, so the engine
|
|
162
|
+
* can page through all parents without truncating records.
|
|
163
|
+
*/
|
|
164
|
+
private FetchAssociationChanges;
|
|
165
|
+
/**
|
|
166
|
+
* Paginates through all pages of a HubSpot v4 per-object association endpoint,
|
|
167
|
+
* returning the raw result items (each with toObjectId + associationTypes).
|
|
168
|
+
*/
|
|
169
|
+
private FetchAllAssociationPages;
|
|
170
|
+
/**
|
|
171
|
+
* Converts a HubSpot v4 association result item into a flat record suitable for storage.
|
|
172
|
+
* v4 format: { toObjectId: number, associationTypes: [{ label, typeId, category }] }
|
|
173
|
+
*/
|
|
174
|
+
private FlattenAssociationRecord;
|
|
175
|
+
/**
|
|
176
|
+
* Parses a v4 associations APIPath to extract from/to object type names.
|
|
177
|
+
* E.g., "/crm/v4/associations/contacts/companies" → { fromType: "contacts", toType: "companies" }
|
|
178
|
+
*/
|
|
179
|
+
private ParseAssociationPath;
|
|
180
|
+
/**
|
|
181
|
+
* Loads hs_object_id values for all synced records of a given HubSpot object type
|
|
182
|
+
* by finding its entity map and querying the local MJ entity.
|
|
183
|
+
*/
|
|
184
|
+
private LoadAssociationParentIDs;
|
|
112
185
|
/**
|
|
113
186
|
* Extracts the HubSpot object name from an API path.
|
|
114
187
|
* E.g., "/crm/v3/objects/contacts" -> "contacts"
|
|
115
188
|
*/
|
|
116
189
|
private ExtractObjectNameFromPath;
|
|
190
|
+
/**
|
|
191
|
+
* Returns the known field names for a HubSpot object type, derived from
|
|
192
|
+
* the HUBSPOT_OBJECTS metadata (single source of truth).
|
|
193
|
+
*/
|
|
194
|
+
private GetObjectFieldNames;
|
|
117
195
|
/**
|
|
118
196
|
* Builds the `properties` query parameter for a HubSpot object type.
|
|
119
197
|
* Returns empty string if no properties are configured for the object.
|
|
120
198
|
*/
|
|
121
199
|
private BuildPropertiesParam;
|
|
122
|
-
/** Executes an HTTP request with a timeout. */
|
|
200
|
+
/** Executes an HTTP request with a timeout and optional JSON body. */
|
|
123
201
|
private FetchWithTimeout;
|
|
124
202
|
/** Calculates retry delay from Retry-After header or exponential backoff. */
|
|
125
203
|
private CalculateRetryDelay;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"AACA,OAAO,
|
|
1
|
+
{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"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"}
|