@memberjunction/integration-connectors 5.13.0 → 5.14.0

package/dist/HubSpotConnector.d.ts

@@ -1,6 +1,6 @@
 import { type UserInfo } from '@memberjunction/core';
 import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
-import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type DefaultFieldMapping, type DefaultIntegrationConfig } from '@memberjunction/integration-engine';
+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';
 /** Connection configuration parsed from CompanyIntegration.Configuration JSON */
 export interface HubSpotConnectionConfig {
     /** HubSpot access token (private app key or OAuth token) */
@@ -46,7 +46,8 @@ interface HubSpotPropertyDef {
  *   "MinRequestIntervalMs": 100   // optional, default: 100
  * }
  *
- * DATA SAFETY: This connector is READ-ONLY. It never writes data back to HubSpot.
+ * Supports full CRUD: Get, Create, Update, Delete, Search, and List operations
+ * on all HubSpot CRM object types.
  */
 export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
     /** Timestamp of the last API request, used for throttling */
@@ -56,9 +57,47 @@ export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
     private get effectiveMaxRetries();
     private get effectiveRequestTimeoutMs();
     private get effectiveMinRequestIntervalMs();
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    get SupportsSearch(): boolean;
+    get SupportsListing(): boolean;
+    get IntegrationName(): string;
+    GetIntegrationObjects(): IntegrationObjectInfo[];
+    GetActionGeneratorConfig(): ActionGeneratorConfig | null;
+    /**
+     * Retrieves a single record by ExternalID (HubSpot object ID).
+     */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    /**
+     * Creates a new record in HubSpot.
+     */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /**
+     * Updates an existing record in HubSpot by ExternalID.
+     */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * Deletes (archives) a record in HubSpot by ExternalID.
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Searches HubSpot objects using the CRM search API.
+     */
+    SearchRecords(ctx: SearchContext): Promise<SearchResult>;
+    /**
+     * Lists records from a HubSpot object with cursor-based pagination.
+     */
+    ListRecords(ctx: ListContext): Promise<ListResult>;
+    /** Converts a raw HubSpot API object to an ExternalRecord. */
+    private RawToExternalRecord;
+    /** Validates a CRUD response and throws on non-2xx status. */
+    private ValidateCRUDResponse;
+    /** Builds a CRUDResult for error responses. */
+    private BuildCRUDErrorResult;
     protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
     protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
-    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, _body?: unknown): Promise<RESTResponse>;
+    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
     protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
     protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
     protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, _auth: RESTAuthContext): string;
@@ -109,17 +148,56 @@ export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
      * plus system fields (hs_object_id, createdAt, updatedAt, archived).
      */
     private FlattenHubSpotRecord;
+    /**
+     * Overrides FetchChanges to intercept association objects (Category === 'Association')
+     * and route them through the v4 per-object associations endpoint instead of the
+     * non-existent flat list endpoint stored in APIPath.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Fetches association records in batches by iterating over synced parent (from-side)
+     * objects and calling HubSpot's v4 per-object associations endpoint.
+     *
+     * Uses ctx.CurrentOffset to track parent position across batch calls, so the engine
+     * can page through all parents without truncating records.
+     */
+    private FetchAssociationChanges;
+    /**
+     * Paginates through all pages of a HubSpot v4 per-object association endpoint,
+     * returning the raw result items (each with toObjectId + associationTypes).
+     */
+    private FetchAllAssociationPages;
+    /**
+     * Converts a HubSpot v4 association result item into a flat record suitable for storage.
+     * v4 format: { toObjectId: number, associationTypes: [{ label, typeId, category }] }
+     */
+    private FlattenAssociationRecord;
+    /**
+     * Parses a v4 associations APIPath to extract from/to object type names.
+     * E.g., "/crm/v4/associations/contacts/companies" → { fromType: "contacts", toType: "companies" }
+     */
+    private ParseAssociationPath;
+    /**
+     * Loads hs_object_id values for all synced records of a given HubSpot object type
+     * by finding its entity map and querying the local MJ entity.
+     */
+    private LoadAssociationParentIDs;
     /**
      * Extracts the HubSpot object name from an API path.
      * E.g., "/crm/v3/objects/contacts" -> "contacts"
      */
     private ExtractObjectNameFromPath;
+    /**
+     * Returns the known field names for a HubSpot object type, derived from
+     * the HUBSPOT_OBJECTS metadata (single source of truth).
+     */
+    private GetObjectFieldNames;
     /**
      * Builds the `properties` query parameter for a HubSpot object type.
      * Returns empty string if no properties are configured for the object.
      */
     private BuildPropertiesParam;
-    /** Executes an HTTP request with a timeout. */
+    /** Executes an HTTP request with a timeout and optional JSON body. */
     private FetchWithTimeout;
     /** Calculates retry delay from Retry-After header or exponential backoff. */
     private CalculateRetryDelay;

package/dist/HubSpotConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"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"}