@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.
Files changed (34) hide show
  1. package/README.md +241 -50
  2. package/dist/HubSpotConnector.d.ts +82 -4
  3. package/dist/HubSpotConnector.d.ts.map +1 -1
  4. package/dist/HubSpotConnector.js +649 -104
  5. package/dist/HubSpotConnector.js.map +1 -1
  6. package/dist/QuickBooksConnector.d.ts +92 -0
  7. package/dist/QuickBooksConnector.d.ts.map +1 -0
  8. package/dist/QuickBooksConnector.js +693 -0
  9. package/dist/QuickBooksConnector.js.map +1 -0
  10. package/dist/RasaConnector.d.ts +4 -19
  11. package/dist/RasaConnector.d.ts.map +1 -1
  12. package/dist/RasaConnector.js +74 -0
  13. package/dist/RasaConnector.js.map +1 -1
  14. package/dist/SageIntacctConnector.d.ts +179 -0
  15. package/dist/SageIntacctConnector.d.ts.map +1 -0
  16. package/dist/SageIntacctConnector.js +1008 -0
  17. package/dist/SageIntacctConnector.js.map +1 -0
  18. package/dist/SalesforceConnector.d.ts +233 -18
  19. package/dist/SalesforceConnector.d.ts.map +1 -1
  20. package/dist/SalesforceConnector.js +1136 -32
  21. package/dist/SalesforceConnector.js.map +1 -1
  22. package/dist/YourMembershipConnector.d.ts +4 -25
  23. package/dist/YourMembershipConnector.d.ts.map +1 -1
  24. package/dist/YourMembershipConnector.js +147 -3
  25. package/dist/YourMembershipConnector.js.map +1 -1
  26. package/dist/generate-integration-actions.d.ts +23 -0
  27. package/dist/generate-integration-actions.d.ts.map +1 -0
  28. package/dist/generate-integration-actions.js +201 -0
  29. package/dist/generate-integration-actions.js.map +1 -0
  30. package/dist/index.d.ts +3 -1
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +2 -0
  33. package/dist/index.js.map +1 -1
  34. 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 four connectors that implement `BaseIntegrationConnector` from `@memberjunction/integration-engine`.
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
- ### RelationalDBConnector (Base Class)
7
+ ### Production REST API Connectors
8
8
 
9
- Abstract base class for connectors that read from SQL Server databases via the `mssql` package. Provides shared logic for connection management, object/field discovery, and batched record fetching with watermark support.
9
+ These connectors call live external APIs and extend `BaseRESTIntegrationConnector`.
10
10
 
11
- **Configuration JSON:**
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
- "server": "your-sql-server",
15
- "database": "YourDatabase",
16
- "user": "username",
17
- "password": "password"
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
- **Shared capabilities:**
22
- - `TestConnection` — runs `SELECT @@VERSION` to verify connectivity
23
- - `DiscoverObjects` — queries `INFORMATION_SCHEMA.TABLES` for all base tables
24
- - `DiscoverFields` — queries `INFORMATION_SCHEMA.COLUMNS` for a given table
25
- - `FetchChangesFromTable` — parameterized incremental fetch with watermark filtering and batch limiting
26
- - Connection pool caching per server+database pair
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
- ### HubSpotConnector
75
+ #### HubSpotConnector
29
76
 
30
- Reads from MockHubSpot database tables: `hs_Contacts`, `hs_Companies`, `hs_Deals`, `hs_Owners`.
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
- | `hs_Contacts` | Contacts | email→Email (key), firstname→FirstName, lastname→LastName, phone→Phone, company→CompanyName, lifecyclestage→Status |
38
- | `hs_Companies` | Companies | name→Name (key), domain→Website, industry→Industry, city→City, state→State |
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
- **To swap for real HubSpot API:** Replace `RelationalDBConnector` with direct HTTP calls to the HubSpot V3 API. The `FetchChanges` method would use the HubSpot Search API with `lastmodifieddate` filters, and `Configuration` would store an API key or OAuth tokens instead of database credentials.
93
+ #### RasaConnector
42
94
 
43
- ### SalesforceConnector
95
+ Production connector for Rasa.io newsletter platform. Read-only — pulls newsletter and subscriber data.
44
96
 
45
- Reads from MockSalesforce database tables: `sf_Contact`, `sf_Account`, `sf_Opportunity`, `sf_User`.
97
+ **Registration:** `@RegisterClass(BaseIntegrationConnector, 'RasaConnector')`
46
98
 
47
- **Registration:** `@RegisterClass(BaseIntegrationConnector, 'SalesforceConnector')`
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
- | `sf_Contact` | Contacts | Email→Email (key), FirstName→FirstName, LastName→LastName, Phone→Phone, Title→Title, Department→Department |
53
- | `sf_Account` | Companies | Name→Name (key), Industry→Industry, BillingCity→City, BillingState→State, Phone→Phone |
204
+ | Customer | Contacts | Id (key), DisplayName, PrimaryEmailAddr, PrimaryPhone, Active |
205
+ | Vendor | Companies | Id (key), DisplayName, PrimaryEmailAddr, PrimaryPhone, Active |
54
206
 
55
- **To swap for real Salesforce API:** Replace `RelationalDBConnector` with `jsforce` or direct REST calls to the Salesforce SOQL API. Use `SystemModstamp` for watermarks and the Salesforce Bulk API for large datasets.
207
+ ### SQL-Based Connectors
56
208
 
57
- ### YourMembershipConnector
209
+ These connectors read from SQL Server databases and extend `RelationalDBConnector`.
58
210
 
59
- Reads from MockYourMembership database tables: `ym_Members`, `ym_Events`, `ym_EventRegistrations`, `ym_Chapters`, `ym_MembershipLevels`.
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
- | `ym_Members` | Contacts | email→Email (key), first_name→FirstName, last_name→LastName, phone→Phone, status→Status |
241
+ | ym_Members | Contacts | email (key), first_name, last_name, phone, status |
242
+
243
+ ### File-Based Connectors
67
244
 
68
- ### FileFeedConnector
245
+ #### FileFeedConnector
69
246
 
70
- Reads data from local CSV files. Always performs a full load (no incremental sync support).
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 data rows into `ExternalRecord[]` (watermark is ignored)
263
+ - `FetchChanges` — parses all rows into `ExternalRecord[]` (watermark ignored)
264
+
265
+ ## Action Generation
87
266
 
88
- **CSV parsing rules:**
89
- - First row is treated as the header
90
- - Supports quoted fields with commas inside
91
- - Supports escaped quotes (`""`) inside quoted fields
92
- - Empty values are mapped to `null`
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 # Package exports
116
- RelationalDBConnector.ts # Base class for SQL-based connectors
117
- HubSpotConnector.ts # HubSpot mock connector
118
- SalesforceConnector.ts # Salesforce mock connector
119
- YourMembershipConnector.ts # YourMembership mock connector
120
- FileFeedConnector.ts # CSV file connector
121
- __tests__/ # Integration tests
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 # 100-row sample for FileFeed testing
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
- * DATA SAFETY: This connector is READ-ONLY. It never writes data back to HubSpot.
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>, _body?: unknown): Promise<RESTResponse>;
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,EAAY,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,0BAA0B,EAAsB,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC/H,OAAO,EAEH,4BAA4B,EAC5B,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAChC,MAAM,oCAAoC,CAAC;AAU5C,iFAAiF;AACjF,MAAM,WAAW,uBAAuB;IACpC,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IAGnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sGAAsG;IACtG,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAQD,yEAAyE;AACzE,UAAU,kBAAkB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,oBAAoB,CAAC,EAAE;QACnB,aAAa,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAgHD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,gBAAiB,SAAQ,4BAA4B;IAE9D,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAAK;IAE5B,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAwC;IAGvD,OAAO,KAAK,mBAAmB,GAA8D;IAC7F,OAAO,KAAK,yBAAyB,GAA2E;IAChH,OAAO,KAAK,6BAA6B,GAAoF;cAI7G,YAAY,CACxB,kBAAkB,EAAE,0BAA0B,EAC9C,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,eAAe,CAAC;IAc3B,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;cAOrD,eAAe,CAC3B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,YAAY,CAAC;IA8BxB,SAAS,CAAC,iBAAiB,CACvB,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,MAAM,GAAG,IAAI,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAmB5B,SAAS,CAAC,qBAAqB,CAC3B,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,cAAc,EAC/B,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAClB,eAAe;IAYlB,SAAS,CAAC,UAAU,CAAC,mBAAmB,EAAE,0BAA0B,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM;IAMrG;;;;OAIG;cACgB,iBAAiB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,yBAAyB,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAChB,MAAM;IAcT,mEAAmE;IACtD,cAAc,CACvB,kBAAkB,EAAE,0BAA0B,EAC9C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAmChB,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACpB,mBAAmB,EAAE;IAkCR,uBAAuB,IAAI,wBAAwB;IASnE,2EAA2E;IACpE,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG;QACjD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;KACvB;IAWD,qEAAqE;IAC9D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAsB9D;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;OAGG;YACW,eAAe;IAwB7B,wDAAwD;YAC1C,wBAAwB;IAStC,2FAA2F;IAC3F,OAAO,CAAC,mBAAmB;IAkB3B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAsB5B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAU5B,+CAA+C;YACjC,gBAAgB;IAoB9B,6EAA6E;IAC7E,OAAO,CAAC,mBAAmB;IAK3B,mEAAmE;IACnE,OAAO,CAAC,iBAAiB;IAMzB,kFAAkF;IAClF,OAAO,CAAC,KAAK;CAGhB"}
1
+ {"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"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"}