@memberjunction/actions-apollo 2.78.0 → 2.80.0

package/dist/contacts.js

@@ -32,153 +32,380 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoadApolloContactsEnrichmentAction = exports.ApolloContactsEnrichmentAction = void 0;
+exports.LoadApolloContactsEnrichmentAction = exports.ApolloEnrichmentContactsAction = void 0;
 const actions_1 = require("@memberjunction/actions");
 const global_1 = require("@memberjunction/global");
 const Config = __importStar(require("./config"));
 const core_1 = require("@memberjunction/core");
 const axios_1 = __importDefault(require("axios"));
-// ApolloEnrichContact this Action would use the www.apollo.io enrichment service and enrich a "contact" type of record. The parameters to this Action would be:
-// EntityName - entity in question that contacts "contact" types of records
-// EmailField - string - field name in the target entity that contains the email to be used for lookups
-// FirstNameField - string 
-// LastNameField - string
-// AccountNameField - string
-// EnrichmentFieldMapping - JSON - this JSON string would contain mappings for the wide array of enrichment outputs. The idea is that the outputs could include a wide array of things and this would map any of the scalar values that Apollo.io provides back to entity field names in the target entity
-// EducationHistoryEntityName - string - optional - this would contain the name of the entity that will be used to stored the retrieved education history for each contact
-// EmploymentHistoryEntityName - string - optional - would contain the name of the entity that will be used to store the retrieved employment history for each contact
-// ApolloEnrichAccount - same idea and pattern as above, but would be for Account style entities
-// Would appreciate feedback on (a) the approach to how we package this stuff and (b) the approach to params noted above.
-let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extends actions_1.BaseAction {
+/**
+ * Action that enriches contact records using Apollo.io's people matching and search APIs
+ *
+ * This action performs contact enrichment by:
+ * 1. Bulk matching existing contacts against Apollo's database
+ * 2. Updating contact records with enriched social profiles and company data
+ * 3. Creating employment and education history records
+ * 4. Processing contacts in configurable batch sizes for optimal performance
+ *
+ * @example
+ * ```typescript
+ * // Basic contact enrichment
+ * await runAction({
+ *   ActionName: 'ApolloEnrichmentContactsAction',
+ *   Params: [{
+ *     Name: 'EntityName',
+ *     Value: 'Contacts'
+ *   }, {
+ *     Name: 'EmailField',
+ *     Value: 'Email'
+ *   }, {
+ *     Name: 'FirstNameField',
+ *     Value: 'FirstName'
+ *   }, {
+ *     Name: 'LastNameField',
+ *     Value: 'LastName'
+ *   }, {
+ *     Name: 'TitleField',
+ *     Value: 'Title'
+ *   }, {
+ *     Name: 'EnrichedAtField',
+ *     Value: 'EnrichedAt'
+ *   }, {
+ *     Name: 'Filter',
+ *     Value: 'Email IS NOT NULL AND EnrichedAt IS NULL'
+ *   }]
+ * });
+ *
+ * // Full enrichment with history tracking
+ * await runAction({
+ *   ActionName: 'ApolloEnrichmentContactsAction',
+ *   Params: [
+ *     // ... basic params ...
+ *     {
+ *       Name: 'EmploymentHistoryFieldMappings',
+ *       Value: JSON.stringify({
+ *         EmploymentHistoryEntityName: 'Contact Employment Histories',
+ *         EmploymentHistoryContactIDFieldName: 'ContactID',
+ *         EmploymentHistoryOrganizationFieldName: 'Organization',
+ *         EmploymentHistoryTitleFieldName: 'Title'
+ *       })
+ *     }
+ *   ]
+ * });
+ * ```
+ */
+let ApolloEnrichmentContactsAction = class ApolloEnrichmentContactsAction extends actions_1.BaseAction {
     constructor() {
         super(...arguments);
+        /**
+         * Job titles to exclude when processing contacts
+         * These are typically not business decision-makers
+         */
         this.ExcludeTitles = ['member', 'student member', 'student', 'volunteer'];
     }
+    /**
+     * Main entry point for the Apollo contact enrichment action
+     *
+     * @param params - The action parameters containing:
+     *   - EntityName: Required - Name of the contact entity to enrich
+     *   - EmailField: Required - Field name containing email addresses
+     *   - FirstNameField: Required - Field name containing first names
+     *   - LastNameField: Required - Field name containing last names
+     *   - TitleField: Required - Field name containing job titles
+     *   - EnrichedAtField: Required - Field to track enrichment timestamp
+     *   - Filter: Required - SQL filter to select contacts for enrichment
+     *   - ProfilePictureURLField: Optional - Field for profile picture URLs
+     *   - AccountNameField: Optional - Field for company/account names
+     *   - DomainField: Optional - Field for email domains
+     *   - LinkedInField: Optional - Field for LinkedIn profile URLs
+     *   - TwitterField: Optional - Field for Twitter profile URLs
+     *   - FacebookField: Optional - Field for Facebook profile URLs
+     *   - EmploymentHistoryFieldMappings: Optional - JSON mapping for employment history entity
+     *   - EducationHistoryFieldMappings: Optional - JSON mapping for education history entity
+     *
+     * @returns Promise<ActionResultSimple> indicating success/failure and any error messages
+     */
     async InternalRunAction(params) {
-        if (!Config.ApolloAPIKey) {
-            throw new Error('Apollo.io API key not found');
+        try {
+            // Validate API configuration
+            const configValidation = this.validateConfiguration();
+            if (!configValidation.success) {
+                return configValidation.error;
+            }
+            // Extract and validate parameters
+            const paramValidation = this.extractAndValidateParameters(params);
+            if (!paramValidation.success) {
+                return paramValidation.error;
+            }
+            const { actionParams, historyMappings } = paramValidation.data;
+            // Process all contact records
+            return await this.processAllContactRecords(actionParams, historyMappings, params.ContextUser);
         }
-        const entityNameParam = params.Params.find(p => p.Name === 'EntityName');
-        const emailFieldParam = params.Params.find(p => p.Name === 'EmailField');
-        const firstNameFieldParam = params.Params.find(p => p.Name === 'FirstNameField');
-        const lastNameFieldParam = params.Params.find(p => p.Name === 'LastNameField');
-        const accountNameFieldParam = params.Params.find(p => p.Name === 'FilterParam');
-        const enrichedAtFieldParam = params.Params.find(p => p.Name === 'EnrichedAtField');
-        const filterParam = params.Params.find(p => p.Name === 'FilterParam');
-        const domainParam = params.Params.find(p => p.Name === 'domainParam');
-        const linkedinParam = params.Params.find(p => p.Name === 'linkedinParam');
-        const EnrichmentFieldMappingParam = params.Params.find(p => p.Name === 'EnrichmentFieldMappings');
-        const EducationHistoryEntityNameParam = params.Params.find(p => p.Name === 'EducationHistoryFieldMappings');
-        const EmploymentHistoryEntityNameParam = params.Params.find(p => p.Name === 'EmploymentHistoryFieldMappings');
-        const educationHistoryFieldMappings = EducationHistoryEntityNameParam ? EducationHistoryEntityNameParam.Value : {};
-        const employmentHistoryFieldMappings = EmploymentHistoryEntityNameParam ? EmploymentHistoryEntityNameParam.Value : {};
-        if (!entityNameParam) {
-            throw new Error("EntityName parameter not found");
+        catch (error) {
+            (0, core_1.LogError)('Unexpected error in ApolloContactsEnrichmentAction', undefined, error);
+            return {
+                Success: false,
+                Message: `Unexpected error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                ResultCode: "FAILED"
+            };
         }
-        if (!emailFieldParam) {
-            throw new Error("EmailField parameter not found");
+    }
+    /**
+     * Validates that the Apollo.io API key is configured properly
+     * @returns Validation result with success flag and potential error details
+     */
+    validateConfiguration() {
+        if (!Config.ApolloAPIKey) {
+            return {
+                success: false,
+                error: {
+                    Success: false,
+                    Message: 'Apollo.io API key not found in configuration',
+                    ResultCode: "CONFIGURATION_ERROR"
+                }
+            };
         }
-        if (!firstNameFieldParam) {
-            throw new Error("FirstNameField parameter not found");
+        return { success: true };
+    }
+    /**
+     * Extracts and validates all action parameters from the request
+     * Processes both required and optional parameters for contact enrichment
+     *
+     * @param params - The action parameters containing entity and field configurations
+     * @returns Object with success flag, validated parameters, or error details
+     */
+    extractAndValidateParameters(params) {
+        // Extract required parameters
+        const entityName = this.getParamValue(params, 'EntityName');
+        const emailField = this.getParamValue(params, 'EmailField');
+        const firstNameField = this.getParamValue(params, 'FirstNameField');
+        const lastNameField = this.getParamValue(params, 'LastNameField');
+        const titleField = this.getParamValue(params, 'TitleField');
+        const enrichedAtField = this.getParamValue(params, 'EnrichedAtField');
+        const filter = this.getParamValue(params, 'Filter');
+        // Check for any missing required parameters
+        const missingParams = [];
+        if (!entityName)
+            missingParams.push('EntityName');
+        if (!emailField)
+            missingParams.push('EmailField');
+        if (!firstNameField)
+            missingParams.push('FirstNameField');
+        if (!lastNameField)
+            missingParams.push('LastNameField');
+        if (!titleField)
+            missingParams.push('TitleField');
+        if (!enrichedAtField)
+            missingParams.push('EnrichedAtField');
+        if (!filter)
+            missingParams.push('Filter');
+        if (missingParams.length > 0) {
+            return {
+                success: false,
+                error: {
+                    Success: false,
+                    Message: `Missing required parameters: ${missingParams.join(', ')}`,
+                    ResultCode: "VALIDATION_ERROR"
+                }
+            };
         }
-        if (!lastNameFieldParam) {
-            throw new Error("LastNameField parameter not found");
+        // Extract optional parameters
+        const profilePictureURLField = this.getParamValue(params, 'ProfilePictureURLField');
+        const accountNameField = this.getParamValue(params, 'AccountNameField');
+        const domainField = this.getParamValue(params, 'DomainField');
+        const linkedInField = this.getParamValue(params, 'LinkedInField');
+        const twitterField = this.getParamValue(params, 'TwitterField');
+        const facebookField = this.getParamValue(params, 'FacebookField');
+        // Extract history mappings
+        const educationHistoryMappings = this.parseHistoryMappings(params, 'EducationHistoryFieldMappings');
+        const employmentHistoryMappings = this.parseHistoryMappings(params, 'EmploymentHistoryFieldMappings');
+        const actionParams = {
+            EntityName: entityName,
+            EmailField: emailField,
+            FirstNameField: firstNameField,
+            LastNameField: lastNameField,
+            TitleField: titleField,
+            EnrichedAtField: enrichedAtField,
+            Filter: filter,
+            ProfilePictureURLField: profilePictureURLField,
+            AccountNameField: accountNameField,
+            DomainField: domainField,
+            LinkedInField: linkedInField,
+            TwitterField: twitterField,
+            FacebookField: facebookField
+        };
+        const historyMappings = {
+            education: educationHistoryMappings,
+            employment: employmentHistoryMappings
+        };
+        return { success: true, data: { actionParams, historyMappings } };
+    }
+    /**
+     * Extract parameter value by name (case-insensitive)
+     * Handles special case where 'null' string should be treated as null value
+     *
+     * @param params - The action parameters
+     * @param paramName - Name of the parameter to extract
+     * @returns Parameter value or null if not found or explicitly 'null'
+     */
+    getParamValue(params, paramName) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (param && param.Value && param.Value === 'null') {
+            return null;
         }
-        if (!accountNameFieldParam) {
-            throw new Error("AccountNameField parameter not found");
+        else {
+            return param?.Value;
         }
-        if (!enrichedAtFieldParam) {
-            throw new Error("EnrichedAtField parameter not found");
+    }
+    /**
+     * Parses JSON field mappings for employment/education history entities
+     * Used to configure how history records should be created and updated
+     *
+     * @param params - The action parameters
+     * @param paramName - Name of the history mapping parameter
+     * @returns Parsed field mappings or empty object if invalid/missing
+     */
+    parseHistoryMappings(params, paramName) {
+        const param = params.Params.find(p => p.Name === paramName);
+        if (!param || !param.Value) {
+            return {};
         }
-        if (!filterParam) {
-            throw new Error("filter parameter not found");
+        // If it's already an object, use it directly
+        if (typeof param.Value === 'object' && param.Value !== null) {
+            return param.Value;
         }
-        const md = new core_1.Metadata();
-        const rv = new core_1.RunView();
-        const runViewResult = await rv.RunView({
-            EntityName: entityNameParam.Value,
-            ExtraFilter: filterParam.Value,
-        }, params.ContextUser);
-        if (!runViewResult.Success) {
-            return {
-                Success: false,
-                Message: runViewResult.ErrorMessage,
-                ResultCode: "FAILED"
-            };
+        // If it's a string, try to parse it as JSON
+        if (typeof param.Value === 'string') {
+            try {
+                return JSON.parse(param.Value) || {};
+            }
+            catch (error) {
+                (0, core_1.LogError)(`Error parsing ${paramName}`, undefined, error);
+                return {};
+            }
         }
-        //need a reference to the length because the ProcessPersonRecordGroup function
-        //mutates the results array
-        let resultLength = 0;
+        return {};
+    }
+    /**
+     * Processes all contact records using paginated queries
+     * Continues processing until all matching records have been enriched
+     *
+     * @param actionParams - Configuration parameters for contact enrichment
+     * @param historyMappings - Field mappings for employment/education history
+     * @param contextUser - User context for data access and security
+     * @returns Promise indicating overall success/failure of the enrichment
+     */
+    async processAllContactRecords(actionParams, historyMappings, contextUser) {
         let pageNumber = 0;
         let hasMore = true;
+        const md = new core_1.Metadata();
         while (hasMore) {
             (0, core_1.LogStatus)(`Fetching page ${pageNumber + 1} of records...`);
-            let config = {
-                EntityName: entityNameParam.Value,
-                PageNumber: pageNumber,
-                PageSize: 500,
-                Filter: `ID IN (select RecordID from __mj.vwListDetails WHERE ListID = '4C04EEF4-7970-EF11-BDFD-00224879D6C4')
-                        AND ID NOT IN (SELECT DISTINCT PersonID from ATD.PersonEmploymentHistory)`
-            };
-            const results = await this.PageRecordsByEntityName(config, params.ContextUser);
-            if (!results) {
-                return {
-                    Success: false,
-                    Message: "Error querying entity records",
-                    ResultCode: "FAILED"
-                };
-            }
-            (0, core_1.LogStatus)(`Fetched ${results.length} records with max page size of ${config.PageSize}`);
-            resultLength = results.length;
-            const tasks = []; // to hold promises
-            for (let i = 0; i < results.length; i += Config.GroupSize) {
-                // push the promise into tasks array without awaiting
-                let processParams = {
-                    Records: results,
-                    Startrow: i,
-                    GroupLength: Config.GroupSize,
-                    Md: md,
-                    CurrentUser: params.ContextUser,
-                    EmailField: emailFieldParam.Value,
-                    FirstNameField: firstNameFieldParam.Value,
-                    LastNameField: lastNameFieldParam.Value,
-                    AccountNameField: accountNameFieldParam.Value,
-                    EntityName: entityNameParam.Value,
-                    EnrichedAtField: enrichedAtFieldParam.Value,
-                    DomainField: domainParam?.Value,
-                    LinkedInField: linkedinParam?.Value,
-                    EmploymentHistoryEntityName: employmentHistoryFieldMappings.EmploymentHistoryEntityName,
-                    EmploymentHistoryContactIDFieldName: employmentHistoryFieldMappings.EmploymentHistoryContactIDFieldName,
-                    EmploymentHistoryOrganizationFieldName: employmentHistoryFieldMappings.EmploymentHistoryOrganizationFieldName,
-                    EmploymentHistoryTitleFieldName: employmentHistoryFieldMappings.EmploymentHistoryTitleFieldName,
-                    EducationHistoryEntityName: educationHistoryFieldMappings.EducationHistoryEntityName,
-                    EducationHistoryContactIDFieldName: educationHistoryFieldMappings.EducationtHistoryContactIDFieldName,
-                    EducationHistoryInstitutionFieldName: educationHistoryFieldMappings.EducationtHistoryInstitutionFieldName,
-                    EducationHistoryDegreeFieldName: educationHistoryFieldMappings.EducationtHistoryDegreeFieldName
-                };
-                const task = this.ProcessPersonRecordGroup(processParams);
-                tasks.push(task);
-                if (tasks.length === Config.ConcurrentGroups || i + 1 >= results.length) {
-                    // if we started n tasks or reached the end of the result array, await all started tasks
-                    await Promise.all(tasks);
-                    // clear tasks
-                    tasks.length = 0;
-                }
-            }
-            if (resultLength < config.PageSize) {
-                console.log(results.length, config.PageSize);
-                (0, core_1.LogStatus)(`No more records to process after this page. Total pages: ${pageNumber + 1}`);
-                hasMore = false;
-                break;
+            const pageResult = await this.processContactRecordsPage(actionParams, historyMappings, pageNumber, md, contextUser);
+            if (!pageResult.success) {
+                return pageResult.error;
             }
+            hasMore = pageResult.hasMore;
             pageNumber++;
         }
         return {
             Success: true,
-            Message: "ApolloAccountsEnrichment executed successfully.",
+            Message: "ApolloContactsEnrichment executed successfully.",
             ResultCode: "SUCCESS"
         };
     }
+    /**
+     * Processes a single page of contact records for enrichment
+     * Retrieves records using pagination and processes them in concurrent groups
+     *
+     * @param actionParams - Configuration parameters for contact enrichment
+     * @param historyMappings - Field mappings for employment/education history
+     * @param pageNumber - Current page number (zero-based)
+     * @param md - Metadata instance for entity operations
+     * @param contextUser - User context for data access
+     * @returns Object indicating success, whether more pages exist, and any errors
+     */
+    async processContactRecordsPage(actionParams, historyMappings, pageNumber, md, contextUser) {
+        const pageConfig = {
+            EntityName: actionParams.EntityName,
+            PageNumber: pageNumber,
+            PageSize: 500,
+            Filter: actionParams.Filter
+        };
+        const results = await this.PageRecordsByEntityName(pageConfig, contextUser);
+        if (!results) {
+            return {
+                success: false,
+                hasMore: false,
+                error: {
+                    Success: false,
+                    Message: "Error querying entity records",
+                    ResultCode: "FAILED"
+                }
+            };
+        }
+        (0, core_1.LogStatus)(`Fetched ${results.length} records with max page size of ${pageConfig.PageSize}`);
+        // Process records in concurrent groups
+        await this.processRecordGroups(results, actionParams, historyMappings, md, contextUser);
+        const hasMore = results.length >= pageConfig.PageSize;
+        return { success: true, hasMore };
+    }
+    /**
+     * Processes contact records in concurrent groups for optimal performance
+     * Respects configured group size and concurrency limits
+     *
+     * @param results - Array of contact records to process
+     * @param actionParams - Configuration parameters for enrichment
+     * @param historyMappings - Field mappings for history entities
+     * @param md - Metadata instance for entity operations
+     * @param contextUser - User context for data access
+     */
+    async processRecordGroups(results, actionParams, historyMappings, md, contextUser) {
+        const tasks = [];
+        for (let i = 0; i < results.length; i += Config.GroupSize) {
+            const processParams = {
+                Records: results,
+                Startrow: i,
+                GroupLength: Config.GroupSize,
+                Md: md,
+                CurrentUser: contextUser,
+                EmailField: actionParams.EmailField,
+                FirstNameField: actionParams.FirstNameField,
+                LastNameField: actionParams.LastNameField,
+                TitleField: actionParams.TitleField,
+                EntityName: actionParams.EntityName,
+                EnrichedAtField: actionParams.EnrichedAtField,
+                ProfilePictureURLField: actionParams.ProfilePictureURLField,
+                AccountNameField: actionParams.AccountNameField,
+                DomainField: actionParams.DomainField,
+                LinkedInField: actionParams.LinkedInField,
+                TwitterField: actionParams.TwitterField,
+                FacebookField: actionParams.FacebookField,
+                EmploymentHistoryEntityName: historyMappings.employment.EntityName,
+                EmploymentHistoryContactIDFieldName: historyMappings.employment.ContactIDFieldName,
+                EmploymentHistoryOrganizationFieldName: historyMappings.employment.OrganizationFieldName,
+                EmploymentHistoryTitleFieldName: historyMappings.employment.TitleFieldName,
+                EducationHistoryEntityName: historyMappings.education.EntityName,
+                EducationHistoryContactIDFieldName: historyMappings.education.ContactIDFieldName,
+                EducationHistoryInstitutionFieldName: historyMappings.education.InstitutionFieldName,
+                EducationHistoryDegreeFieldName: historyMappings.education.DegreeFieldName
+            };
+            const task = this.ProcessPersonRecordGroup(processParams);
+            tasks.push(task);
+            if (tasks.length === Config.ConcurrentGroups || i + Config.GroupSize >= results.length) {
+                await Promise.all(tasks);
+                tasks.length = 0;
+            }
+        }
+    }
+    /**
+     * Retrieves a page of records from a specified entity using RunView
+     * Supports pagination with configurable page size and filtering
+     *
+     * @param params - Parameters defining entity, page, and filter criteria
+     * @param currentUser - User context for data access
+     * @returns Array of records or null if query failed
+     */
     async PageRecordsByEntityName(params, currentUser) {
         const rv = new core_1.RunView();
         const rvResult = await rv.RunView({
@@ -193,13 +420,20 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
         }
         return rvResult.Results;
     }
+    /**
+     * Processes a group of contact records using Apollo's bulk people matching API
+     * Enriches contacts with social profiles, company data, and employment history
+     *
+     * @param params - Group processing parameters with contact data and entity mappings
+     * @returns Promise<boolean> indicating success/failure of the group processing
+     */
     async ProcessPersonRecordGroup(params) {
         try {
             const md = params.Md;
             const ApolloParams = {
                 api_key: Config.ApolloAPIKey,
                 reveal_personal_emails: true,
-                details: params.Records.splice(params.Startrow, params.GroupLength).map((record) => {
+                details: params.Records.slice(params.Startrow, params.Startrow + params.GroupLength).map((record) => {
                     const first_name = record[params.FirstNameField];
                     const last_name = record[params.LastNameField];
                     const email = record[params.EmailField];
@@ -226,40 +460,40 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                                 (0, core_1.LogStatus)('No match found for record at index ' + params.Startrow + index);
                                 continue;
                             }
-                            const contactEntity = await md.GetEntityObject(params.EntityName, params.CurrentUser);
                             const email = match.email;
                             if (email && email.trim().length > 0) {
                                 // update the contact record
                                 let entityRecord = params.Records[index + params.Startrow];
                                 if (!entityRecord) {
                                     (0, core_1.LogError)('Error updating contact record with enriched data, entity record not found', undefined, entityRecord);
+                                    bSuccess = false;
                                     continue;
                                 }
-                                contactEntity.SetMany(entityRecord, true);
+                                const contactEntity = await md.GetEntityObject(params.EntityName, core_1.CompositeKey.FromID(entityRecord.ID), params.CurrentUser);
                                 contactEntity.Set(params.EmailField, match.email);
                                 contactEntity.Set(params.EnrichedAtField, new Date());
-                                if (match.organization) {
+                                if (params.TitleField && match.title) {
+                                    contactEntity.Set(params.TitleField, match.title);
+                                }
+                                if (params.AccountNameField && match.organization && match.organization.name) {
                                     contactEntity.Set(params.AccountNameField, match.organization.name);
                                 }
-                                if (params.LinkedInField) {
+                                if (params.ProfilePictureURLField && match.photo_url) {
+                                    contactEntity.Set(params.ProfilePictureURLField, match.photo_url);
+                                }
+                                if (params.LinkedInField && match.linkedin_url) {
                                     contactEntity.Set(params.LinkedInField, match.linkedin_url);
                                 }
-                                if (match.organization && match.organization.name) {
-                                    contactEntity.Set(params.AccountNameField, match.organization.name);
+                                if (params.TwitterField && match.twitter_url) {
+                                    contactEntity.Set(params.TwitterField, match.twitter_url);
+                                }
+                                if (params.FacebookField && match.facebook_url) {
+                                    contactEntity.Set(params.FacebookField, match.facebook_url);
                                 }
                                 bSuccess = bSuccess && (await contactEntity.Save());
                                 if (!bSuccess) {
                                     (0, core_1.LogError)('Error updating contact record with enriched data', undefined, contactEntity.LatestResult);
                                 }
-                                /*
-                                if(match.organization_id){
-                                    LogStatus(`Found organization: ${match.organization?.name}`);
-                                    await this.UpsertContactEmploymentAndEducationHistoryByOrganizationID(match.organization_id, params);
-                                }
-                                else {
-                                    LogStatus('No organization ID found in match');
-                                }
-                                */
                                 if (match.employment_history && params.EmploymentHistoryEntityName) {
                                     (0, core_1.LogStatus)('Upserting contact employment and education history...');
                                     await this.UpsertContactEmploymentAndEducationHistory(match, contactEntity, params);
@@ -296,6 +530,13 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                 return false;
         }
     }
+    /**
+     * Enriches contacts by searching for people at a specific organization domain
+     * Uses Apollo's people search to find contacts and update their employment/education history
+     *
+     * @param domain - Organization domain to search for people
+     * @param params - Processing parameters with entity configurations
+     */
     async UpsertContactEmploymentAndEducationHistoryByOrganizationID(domain, params) {
         try {
             const api_params = {
@@ -363,7 +604,6 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                             continue;
                         }
                         const contactEntity = await params.Md.GetEntityObject(params.EntityName, params.CurrentUser);
-                        contactEntity.SetMany(rvContactResults.Results[0]);
                         await this.UpsertContactEmploymentAndEducationHistory(p, contactEntity, params);
                     }
                     i++;
@@ -378,6 +618,14 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
             (0, core_1.LogError)('Error upserting contact education and employment history by organization ID: ', undefined, ex);
         }
     }
+    /**
+     * Creates or updates employment and education history records for a contact
+     * Processes Apollo employment history data to create both employment and education records
+     *
+     * @param contact - Apollo person data containing employment history
+     * @param contactEntity - Contact entity to create history for
+     * @param params - Processing parameters with history entity configurations
+     */
     async UpsertContactEmploymentAndEducationHistory(contact, contactEntity, params) {
         try {
             // loop through the person.employment_history array and create/update the employment history records
@@ -400,12 +648,13 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                     continue;
                 }
                 const results = rvResults.Results;
-                const historyEntity = await params.Md.GetEntityObject(params.EmploymentHistoryEntityName, params.CurrentUser);
+                let historyEntity = null;
                 if (results.length > 0) {
                     // update the existing record
-                    historyEntity.SetMany(results[0]);
+                    historyEntity = await params.Md.GetEntityObject(params.EmploymentHistoryEntityName, core_1.CompositeKey.FromID(results[0].ID), params.CurrentUser);
                 }
                 else {
+                    historyEntity = await params.Md.GetEntityObject(params.EmploymentHistoryEntityName, params.CurrentUser);
                     historyEntity.NewRecord();
                     historyEntity.Set(params.EmploymentHistoryContactIDFieldName, contactID);
                     historyEntity.Set("CreatedAt", new Date());
@@ -416,7 +665,7 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                     historyEntity.Set('StartedAt', employment.start_date);
                 }
                 if (this.IsValidDate(employment.end_date)) {
-                    historyEntity.Set('EndedAt', employment.start_date);
+                    historyEntity.Set('EndedAt', employment.end_date);
                 }
                 historyEntity.Set("UpdatedAt", new Date());
                 historyEntity.Set("IsCurrent", employment.current);
@@ -440,12 +689,13 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                         continue;
                     }
                     const educationResults = rvEducationResults.Results;
-                    const educationEntity = await params.Md.GetEntityObject(params.EducationHistoryEntityName, params.CurrentUser);
+                    let educationEntity = null;
                     if (educationResults.length > 0) {
                         // update the existing record
-                        educationEntity.SetMany(educationResults[0]);
+                        educationEntity = await params.Md.GetEntityObject(params.EducationHistoryEntityName, core_1.CompositeKey.FromID(educationResults[0].ID), params.CurrentUser);
                     }
                     else {
+                        educationEntity = await params.Md.GetEntityObject(params.EducationHistoryEntityName, params.CurrentUser);
                         educationEntity.NewRecord();
                         educationEntity.Set(params.EducationHistoryContactIDFieldName, contactID);
                         educationEntity.Set("CreatedAt", new Date());
@@ -459,7 +709,7 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                         educationEntity.Set('StartedAt', employment.start_date);
                     }
                     if (this.IsValidDate(employment.end_date)) {
-                        educationEntity.Set('EndedAt', employment.start_date);
+                        educationEntity.Set('EndedAt', employment.end_date);
                     }
                     const saveResult = await educationEntity.Save();
                     if (!saveResult) {
@@ -472,12 +722,26 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
             (0, core_1.LogError)('Error upserting contact education and employment history: ', undefined, ex);
         }
     }
+    /**
+     * Escapes single quotes in strings for SQL query safety
+     * Prevents SQL injection in dynamic filter construction
+     *
+     * @param str - String to escape
+     * @returns Escaped string with doubled single quotes
+     */
     EscapeSingleQuotes(str) {
         if (str) {
             return str.replace(/'/g, "''");
         }
         return '';
     }
+    /**
+     * Validates if a date string represents a valid date
+     * Used for employment/education history date validation
+     *
+     * @param dateString - Date string to validate
+     * @returns boolean - true if valid date
+     */
     IsValidDate(dateString) {
         if (dateString && dateString.length > 0) {
             const date = new Date(dateString);
@@ -485,6 +749,18 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
         }
         return false;
     }
+    /**
+     * Wraps Apollo.io API calls with intelligent retry logic for rate limiting
+     * Handles both per-minute and hourly rate limits with appropriate backoff
+     *
+     * @param method - HTTP method ('get' or 'post')
+     * @param endpoint - Apollo API endpoint path
+     * @param data - Request payload for POST requests
+     * @param config - Axios configuration object
+     * @param retryAttempts - Number of retry attempts remaining (default: 1)
+     * @returns Promise<AxiosResponse> - Apollo API response
+     * @throws Error if rate limit exceeded or other API errors
+     */
     async WrapApolloCall(method, endpoint, data, config, retryAttempts = 1) {
         try {
             const url = `${Config.ApolloAPIEndpoint}/${endpoint}`;
@@ -507,7 +783,9 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
                 let waitTime = 60000; // default to 1 minute
                 //this is a rough guesstimate, check the response headers for more accurate info
                 if (apolloError.response.data) {
-                    const errorMessage = apolloError.response.data;
+                    const errorMessage = typeof apolloError.response.data === 'string'
+                        ? apolloError.response.data
+                        : JSON.stringify(apolloError.response.data);
                     if (errorMessage.includes('times per hour')) {
                         (0, core_1.LogStatus)("   >>> Hourly rate limit reached");
                         //we reached out hourly rate limit, so wait an hour 
@@ -528,9 +806,23 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
             }
         }
     }
+    /**
+     * Utility method for creating delays in async operations
+     * Used for rate limit backoff and API throttling
+     *
+     * @param ms - Number of milliseconds to wait
+     * @returns Promise that resolves after the specified delay
+     */
     async Timeout(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
+    /**
+     * Checks if a job title should be excluded from contact processing
+     * Filters out non-business contacts like students and volunteers
+     *
+     * @param title - Job title to check
+     * @returns boolean - true if title should be excluded
+     */
     IsExcludedTitle(title) {
         if (!title) {
             return false;
@@ -538,11 +830,16 @@ let ApolloContactsEnrichmentAction = class ApolloContactsEnrichmentAction extend
         return this.ExcludeTitles.includes(title.trim().toLowerCase());
     }
 };
-exports.ApolloContactsEnrichmentAction = ApolloContactsEnrichmentAction;
-exports.ApolloContactsEnrichmentAction = ApolloContactsEnrichmentAction = __decorate([
-    (0, global_1.RegisterClass)(actions_1.BaseAction, "Apollo Enrichment - Contacts")
-], ApolloContactsEnrichmentAction);
+exports.ApolloEnrichmentContactsAction = ApolloEnrichmentContactsAction;
+exports.ApolloEnrichmentContactsAction = ApolloEnrichmentContactsAction = __decorate([
+    (0, global_1.RegisterClass)(actions_1.BaseAction, "ApolloEnrichmentContactsAction")
+], ApolloEnrichmentContactsAction);
+/**
+ * Loader function to ensure the ApolloEnrichmentContactsAction class is included in the bundle
+ * Prevents tree shaking from removing this action class
+ */
 function LoadApolloContactsEnrichmentAction() {
+    // Stub function to prevent tree shaking
 }
 exports.LoadApolloContactsEnrichmentAction = LoadApolloContactsEnrichmentAction;
 //# sourceMappingURL=contacts.js.map