@memberjunction/integration-connectors 5.8.0 → 5.10.0

package/dist/HubSpotConnector.d.ts

@@ -1,41 +1,96 @@
-import { type FetchContext, type FetchBatchResult, type DefaultFieldMapping } from '@memberjunction/integration-engine';
-import { RelationalDBConnector } from './RelationalDBConnector.js';
+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';
+/** HubSpot property definition (from /crm/v3/properties/{objectType}) */
+interface HubSpotPropertyDef {
+    name: string;
+    label: string;
+    type: string;
+    fieldType: string;
+    groupName: string;
+    description: string;
+    hasUniqueValue: boolean;
+    calculated: boolean;
+    externalOptions: boolean;
+    modificationMetadata?: {
+        readOnlyValue: boolean;
+    };
+}
 /**
- * Connector for HubSpot CRM data, backed by the mock_data database (hs schema).
- * Reads from hs.contacts, hs.companies, and hs.deals tables.
- * Provides default field mappings for contacts and companies to MJ entities.
+ * Connector for HubSpot CRM via the HubSpot REST API v3.
+ *
+ * Extends BaseRESTIntegrationConnector to leverage metadata-driven object/field
+ * discovery from IntegrationEngineBase cache and generic pagination handling.
+ *
+ * Uses Bearer token authentication (private app key or OAuth access token).
+ * Supports cursor-based pagination and automatic response flattening.
+ *
+ * DATA SAFETY: This connector is READ-ONLY. It never writes data back to HubSpot.
  */
-export declare class HubSpotConnector extends RelationalDBConnector {
+export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
+    /** Timestamp of the last API request, used for throttling */
+    private lastRequestTime;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity): 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 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): string;
     /**
-     * Fetches a batch of changed records from the specified HubSpot object table.
-     * Uses lastmodifieddate for watermark-based incremental sync.
-     * @param ctx - Fetch context with integration, object, watermark, and batch details
-     * @returns Batch of HubSpot records with pagination info
+     * Overrides base pagination URL building to use HubSpot's parameter names.
+     * HubSpot uses `after` for cursor pagination (not `cursor`), and needs
+     * `limit` instead of `pageSize`. Also appends `properties` query param.
      */
-    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, _offset: number, cursor?: string): string;
+    /** Tests connectivity by authenticating and fetching 1 contact. */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ConnectionTestResult>;
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    /** Converts a HubSpot property definition to ExternalFieldSchema format */
+    MapPropertyToField(prop: HubSpotPropertyDef): {
+        Name: string;
+        Label: string;
+        DataType: string;
+        IsRequired: boolean;
+        IsUniqueKey: boolean;
+        IsReadOnly: boolean;
+    };
+    /** Maps HubSpot type + fieldType to a simplified data type string */
+    MapHubSpotType(type: string, fieldType: string): string;
     /**
-     * Returns suggested default field mappings for known HubSpot objects to MJ entities.
-     * @param objectName - HubSpot object name (e.g., "contacts")
-     * @param entityName - Target MJ entity name (e.g., "Contacts")
-     * @returns Array of default field mappings
+     * Reads credentials from CompanyIntegration.CredentialID -> Credential.Values JSON,
+     * or falls back to CompanyIntegration Configuration JSON for backwards compat.
      */
-    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    private LoadCredentials;
+    /** Loads credentials from a Credential entity by ID. */
+    private LoadFromCredentialEntity;
+    /** Parses a JSON string to extract HubSpot credentials. Returns null if no token found. */
+    private ParseCredentialJson;
+    /**
+     * Flattens a HubSpot CRM record from the nested format:
+     *   { id, properties: { field1, field2 }, createdAt, updatedAt, archived }
+     * into a flat record with all properties at the top level,
+     * plus system fields (hs_object_id, createdAt, updatedAt, archived).
+     */
+    private FlattenHubSpotRecord;
     /**
-     * Gets the primary key column for a HubSpot table.
-     * @param objectName - Table name
-     * @returns Column name for the primary key
+     * Extracts the HubSpot object name from an API path.
+     * E.g., "/crm/v3/objects/contacts" -> "contacts"
      */
-    private getIdField;
+    private ExtractObjectNameFromPath;
     /**
-     * Gets the soft-delete flag column for a HubSpot table, if one exists.
-     * Currently only the contacts table has an is_deleted column.
-     * @param objectName - Table name
-     * @returns Column name for the deleted flag, or undefined if not applicable
+     * Builds the `properties` query parameter for a HubSpot object type.
+     * Returns empty string if no properties are configured for the object.
      */
-    private getDeletedField;
-    /** Default field mappings: hs_Contacts -> Contacts */
-    private getContactMappings;
-    /** Default field mappings: hs_Companies -> Companies */
-    private getCompanyMappings;
+    private BuildPropertiesParam;
+    /** Executes an HTTP request with a timeout. */
+    private FetchWithTimeout;
+    /** Calculates retry delay from Retry-After header or exponential backoff. */
+    private CalculateRetryDelay;
+    /** Converts a fetch Response + parsed body into a RESTResponse. */
+    private BuildRESTResponse;
+    /** Returns a promise that resolves after the specified number of milliseconds. */
+    private Sleep;
 }
+export {};
 //# sourceMappingURL=HubSpotConnector.d.ts.map

package/dist/HubSpotConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAanE;;;;GAIG;AACH,qBACa,gBAAiB,SAAQ,qBAAqB;IACvD;;;;;OAKG;IACU,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAMvE;;;;;OAKG;IACa,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACpB,mBAAmB,EAAE;IAWxB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IASlB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAOvB,sDAAsD;IACtD,OAAO,CAAC,kBAAkB;IAW1B,wDAAwD;IACxD,OAAO,CAAC,kBAAkB;CAS7B"}
+{"version":3,"file":"HubSpotConnector.d.ts","sourceRoot":"","sources":["../src/HubSpotConnector.ts"],"names":[],"mappings":"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"}