@memberjunction/integration-engine 0.0.1 → 5.9.0

package/dist/FieldMappingEngine.d.ts

@@ -0,0 +1,94 @@
+import type { ICompanyIntegrationFieldMap } from './entity-types.js';
+import type { ExternalRecord, MappedRecord } from './types.js';
+/**
+ * Engine responsible for applying field-level mappings and transformations
+ * from external records to MJ entity fields.
+ */
+export declare class FieldMappingEngine {
+    /**
+     * Applies field mappings to a batch of external records, producing mapped records
+     * ready for match resolution and persistence.
+     *
+     * @param records - External records to map
+     * @param fieldMaps - Active field map entities defining source→destination mappings
+     * @param entityName - Target MJ entity name
+     * @returns Array of mapped records with transformed field values
+     */
+    Apply(records: ExternalRecord[], fieldMaps: ICompanyIntegrationFieldMap[], entityName: string): MappedRecord[];
+    /**
+     * Maps a single external record through all active field mappings.
+     */
+    private MapSingleRecord;
+    /**
+     * Applies a single field mapping, including the full transform pipeline.
+     * Returns undefined if the field should be skipped (OnError: Skip).
+     */
+    private ApplyFieldMapping;
+    /**
+     * Parses the JSON transform pipeline string into typed TransformStep objects.
+     */
+    private ParseTransformPipeline;
+    /**
+     * Executes a single transform step, applying the configured transformation
+     * and handling errors according to the step's OnError strategy.
+     */
+    private ExecuteTransformStep;
+    /**
+     * Dispatches to the appropriate transform handler based on step type.
+     */
+    private DispatchTransform;
+    /**
+     * Handles a transform error according to the OnError strategy.
+     */
+    private HandleTransformError;
+    /**
+     * Direct pass-through, applying default value if source is null/undefined.
+     */
+    private ApplyDirect;
+    /**
+     * Applies a regex replacement to a string value.
+     */
+    private ApplyRegex;
+    /**
+     * Splits a string value and extracts a part by index.
+     */
+    private ApplySplit;
+    /**
+     * Combines multiple source fields with a separator.
+     */
+    private ApplyCombine;
+    /**
+     * Performs a case-insensitive value lookup/mapping.
+     */
+    private ApplyLookup;
+    /**
+     * Applies date/number/string formatting.
+     */
+    private ApplyFormat;
+    /**
+     * Basic date formatting supporting ISO and common format tokens.
+     */
+    private FormatDate;
+    /**
+     * Coerces a value to the specified target type.
+     */
+    private ApplyCoerce;
+    /**
+     * Coerces a value to a number, throwing on NaN.
+     */
+    private CoerceToNumber;
+    /**
+     * Coerces a value to boolean, supporting common truthy/falsy strings.
+     */
+    private CoerceToBoolean;
+    /**
+     * Extracts a substring from a string value.
+     */
+    private ApplySubstring;
+    /**
+     * Evaluates a custom JavaScript expression.
+     * The expression has access to `value` (current field value) and `fields` (all record fields).
+     */
+    private ApplyCustom;
+}
+//# sourceMappingURL=FieldMappingEngine.d.ts.map

package/dist/FieldMappingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMappingEngine.d.ts","sourceRoot":"","sources":["../src/FieldMappingEngine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAe/D;;;GAGG;AACH,qBAAa,kBAAkB;IAC3B;;;;;;;;OAQG;IACI,KAAK,CACR,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,EAAE,2BAA2B,EAAE,EACxC,UAAU,EAAE,MAAM,GACnB,YAAY,EAAE;IAKjB;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAY9B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAe5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAYnB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;;OAGG;IACH,OAAO,CAAC,WAAW;CActB"}

package/dist/FieldMappingEngine.js

@@ -0,0 +1,250 @@
+/**
+ * Engine responsible for applying field-level mappings and transformations
+ * from external records to MJ entity fields.
+ */
+export class FieldMappingEngine {
+    /**
+     * Applies field mappings to a batch of external records, producing mapped records
+     * ready for match resolution and persistence.
+     *
+     * @param records - External records to map
+     * @param fieldMaps - Active field map entities defining source→destination mappings
+     * @param entityName - Target MJ entity name
+     * @returns Array of mapped records with transformed field values
+     */
+    Apply(records, fieldMaps, entityName) {
+        const activeMaps = fieldMaps.filter(fm => fm.Status === 'Active');
+        return records.map(record => this.MapSingleRecord(record, activeMaps, entityName));
+    }
+    /**
+     * Maps a single external record through all active field mappings.
+     */
+    MapSingleRecord(record, fieldMaps, entityName) {
+        const mappedFields = {};
+        for (const fieldMap of fieldMaps) {
+            const value = this.ApplyFieldMapping(record, fieldMap);
+            if (value !== undefined) {
+                mappedFields[fieldMap.DestinationFieldName] = value;
+            }
+        }
+        return {
+            ExternalRecord: record,
+            MJEntityName: entityName,
+            MappedFields: mappedFields,
+            ChangeType: record.IsDeleted ? 'Delete' : 'Create',
+        };
+    }
+    /**
+     * Applies a single field mapping, including the full transform pipeline.
+     * Returns undefined if the field should be skipped (OnError: Skip).
+     */
+    ApplyFieldMapping(record, fieldMap) {
+        let value = record.Fields[fieldMap.SourceFieldName];
+        const pipeline = this.ParseTransformPipeline(fieldMap.TransformPipeline);
+        for (const step of pipeline) {
+            const result = this.ExecuteTransformStep(step, value, record.Fields);
+            if (result.Skipped)
+                return undefined;
+            value = result.Value;
+        }
+        return value;
+    }
+    /**
+     * Parses the JSON transform pipeline string into typed TransformStep objects.
+     */
+    ParseTransformPipeline(pipelineJson) {
+        if (!pipelineJson || pipelineJson.trim() === '')
+            return [];
+        try {
+            const parsed = JSON.parse(pipelineJson);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Executes a single transform step, applying the configured transformation
+     * and handling errors according to the step's OnError strategy.
+     */
+    ExecuteTransformStep(step, value, allFields) {
+        const onError = step.OnError ?? 'Fail';
+        try {
+            const transformed = this.DispatchTransform(step, value, allFields);
+            return { Value: transformed, Skipped: false };
+        }
+        catch (err) {
+            return this.HandleTransformError(onError, err);
+        }
+    }
+    /**
+     * Dispatches to the appropriate transform handler based on step type.
+     */
+    DispatchTransform(step, value, allFields) {
+        switch (step.Type) {
+            case 'direct':
+                return this.ApplyDirect(value, step.Config);
+            case 'regex':
+                return this.ApplyRegex(value, step.Config);
+            case 'split':
+                return this.ApplySplit(value, step.Config);
+            case 'combine':
+                return this.ApplyCombine(allFields, step.Config);
+            case 'lookup':
+                return this.ApplyLookup(value, step.Config);
+            case 'format':
+                return this.ApplyFormat(value, step.Config);
+            case 'coerce':
+                return this.ApplyCoerce(value, step.Config);
+            case 'substring':
+                return this.ApplySubstring(value, step.Config);
+            case 'custom':
+                return this.ApplyCustom(value, allFields, step.Config);
+            default:
+                throw new Error(`Unknown transform type: ${step.Type}`);
+        }
+    }
+    /**
+     * Handles a transform error according to the OnError strategy.
+     */
+    HandleTransformError(onError, err) {
+        switch (onError) {
+            case 'Skip':
+                return { Value: undefined, Skipped: true };
+            case 'Null':
+                return { Value: null, Skipped: false };
+            case 'Fail':
+                throw err;
+        }
+    }
+    /**
+     * Direct pass-through, applying default value if source is null/undefined.
+     */
+    ApplyDirect(value, config) {
+        if (value == null && config.DefaultValue !== undefined) {
+            return config.DefaultValue;
+        }
+        return value;
+    }
+    /**
+     * Applies a regex replacement to a string value.
+     */
+    ApplyRegex(value, config) {
+        const strValue = String(value ?? '');
+        const regex = new RegExp(config.Pattern, config.Flags ?? '');
+        return strValue.replace(regex, config.Replacement);
+    }
+    /**
+     * Splits a string value and extracts a part by index.
+     */
+    ApplySplit(value, config) {
+        const strValue = String(value ?? '');
+        const parts = strValue.split(config.Delimiter);
+        return parts[config.Index] ?? null;
+    }
+    /**
+     * Combines multiple source fields with a separator.
+     */
+    ApplyCombine(allFields, config) {
+        const values = config.SourceFields.map(f => String(allFields[f] ?? ''));
+        return values.join(config.Separator);
+    }
+    /**
+     * Performs a case-insensitive value lookup/mapping.
+     */
+    ApplyLookup(value, config) {
+        const strValue = String(value ?? '');
+        const lowerKey = strValue.toLowerCase();
+        const entry = Object.entries(config.Map).find(([key]) => key.toLowerCase() === lowerKey);
+        return entry ? entry[1] : (config.Default ?? null);
+    }
+    /**
+     * Applies date/number/string formatting.
+     */
+    ApplyFormat(value, config) {
+        if (config.FormatType === 'date') {
+            const dateVal = value instanceof Date ? value : new Date(String(value));
+            return this.FormatDate(dateVal, config.FormatString);
+        }
+        if (config.FormatType === 'number') {
+            const numVal = Number(value);
+            return numVal.toFixed(Number(config.FormatString) || 0);
+        }
+        return String(value ?? '');
+    }
+    /**
+     * Basic date formatting supporting ISO and common format tokens.
+     */
+    FormatDate(date, formatString) {
+        if (formatString.toLowerCase() === 'iso' || formatString === 'ISO8601') {
+            return date.toISOString();
+        }
+        return date.toLocaleDateString('en-US');
+    }
+    /**
+     * Coerces a value to the specified target type.
+     */
+    ApplyCoerce(value, config) {
+        switch (config.TargetType) {
+            case 'string':
+                return String(value ?? '');
+            case 'number':
+                return this.CoerceToNumber(value);
+            case 'boolean':
+                return this.CoerceToBoolean(value);
+            case 'date':
+                return new Date(String(value));
+            default:
+                throw new Error(`Unknown coerce target type: ${config.TargetType}`);
+        }
+    }
+    /**
+     * Coerces a value to a number, throwing on NaN.
+     */
+    CoerceToNumber(value) {
+        const num = Number(value);
+        if (isNaN(num)) {
+            throw new Error(`Cannot coerce "${String(value)}" to number`);
+        }
+        return num;
+    }
+    /**
+     * Coerces a value to boolean, supporting common truthy/falsy strings.
+     */
+    CoerceToBoolean(value) {
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number')
+            return value !== 0;
+        const strVal = String(value).toLowerCase().trim();
+        return strVal === 'true' || strVal === '1' || strVal === 'yes';
+    }
+    /**
+     * Extracts a substring from a string value.
+     */
+    ApplySubstring(value, config) {
+        const strValue = String(value ?? '');
+        if (config.Length !== undefined) {
+            return strValue.substring(config.Start, config.Start + config.Length);
+        }
+        return strValue.substring(config.Start);
+    }
+    /**
+     * Evaluates a custom JavaScript expression.
+     * The expression has access to `value` (current field value) and `fields` (all record fields).
+     */
+    ApplyCustom(value, allFields, config) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const fn = new Function('value', 'fields', `return (${config.Expression});`);
+            return fn(value, allFields);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Custom transform expression failed: ${message}`);
+        }
+    }
+}
+//# sourceMappingURL=FieldMappingEngine.js.map

package/dist/FieldMappingEngine.js.map

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

package/dist/IntegrationEngine.d.ts

@@ -0,0 +1,173 @@
+import { IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { BaseSingleton } from '@memberjunction/global';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import type { MJCompanyIntegrationEntity, MJCompanyIntegrationEntityMapEntity, MJCompanyIntegrationFieldMapEntity, MJCompanyIntegrationSyncWatermarkEntity, MJIntegrationEntity, MJIntegrationSourceTypeEntity, MJIntegrationObjectEntity, MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
+import type { SyncResult, SyncTriggerType, OnProgressCallback, OnNotificationCallback } from './types.js';
+/**
+ * Server-side Integration Engine.
+ *
+ * Wraps IntegrationEngineBase (cached metadata) via composition and provides
+ * the full sync orchestration pipeline: fetch → map → match → validate → apply.
+ *
+ * Pattern mirrors AIEngine wrapping AIEngineBase.
+ *
+ * Usage:
+ *   await IntegrationEngine.Instance.Config(false, contextUser);
+ *   const result = await IntegrationEngine.Instance.RunSync(companyIntegrationID, contextUser);
+ */
+export declare class IntegrationEngine extends BaseSingleton<IntegrationEngine> {
+    constructor();
+    private readonly fieldMappingEngine;
+    private readonly matchEngine;
+    private readonly watermarkService;
+    /** In-process lock map to prevent concurrent syncs for the same CompanyIntegration */
+    private static readonly activeSyncs;
+    /** Configurable maximum batch size. Connector batches exceeding this are truncated. */
+    MaxBatchSize: number;
+    /**
+     * Executes a full sync run for a company integration.
+     * If a sync is already running for the same integration, waits for it to finish
+     * and returns the existing result (concurrency lock).
+     *
+     * @param companyIntegrationID - ID of the CompanyIntegration to sync
+     * @param contextUser - User context for all data operations
+     * @param triggerType - What triggered this sync (defaults to 'Manual')
+     * @param onProgress - Optional callback invoked with progress updates during sync
+     * @param onNotification - Optional callback invoked with a notification when the sync completes or fails
+     * @returns Aggregate sync result with record counts and errors
+     */
+    RunSync(companyIntegrationID: string, contextUser: UserInfo, triggerType?: SyncTriggerType, onProgress?: OnProgressCallback, onNotification?: OnNotificationCallback): Promise<SyncResult>;
+    /**
+     * Internal sync execution method. Contains the full orchestration logic.
+     */
+    private executeSyncInternal;
+    /**
+     * Loads all configuration needed for a sync run.
+     */
+    private LoadRunConfiguration;
+    /**
+     * Creates a new CompanyIntegrationRun record to track this sync.
+     */
+    private CreateRunRecord;
+    /**
+     * Processes all entity maps, aggregating results with progress tracking.
+     */
+    private ExecuteEntityMaps;
+    /**
+     * Processes a single entity map: fetch → map → match → validate → apply.
+     */
+    private ProcessSingleEntityMap;
+    /**
+     * Emits a progress update via the callback.
+     */
+    private emitProgress;
+    /**
+     * Loads active field maps for a given entity map.
+     */
+    private LoadFieldMaps;
+    /**
+     * Applies resolved records to MJ, handling each individually for error isolation.
+     */
+    private ApplyRecords;
+    /**
+     * Applies a single record change (Create, Update, Delete, or Skip).
+     */
+    private ApplySingleRecord;
+    /**
+     * Creates a new MJ record with pre-write validation and saves a record map entry.
+     */
+    private CreateRecord;
+    /**
+     * Updates an existing MJ record with pre-write validation.
+     */
+    private UpdateRecord;
+    /**
+     * Runs Validate() on an entity if the method exists.
+     * Throws a validation error with details if validation fails.
+     */
+    private validateEntity;
+    /**
+     * Deletes (or soft-deletes) an MJ record based on the entity map's DeleteBehavior.
+     */
+    private DeleteRecord;
+    /**
+     * Builds a CompositeKey for a record lookup.
+     * Integration tables use the natural PK field from the source system.
+     */
+    private BuildCompositeKey;
+    /**
+     * Sets fields on a BaseEntity instance from a field value map.
+     */
+    private SetEntityFields;
+    /**
+     * Sets standard integration columns (__mj_integration_*) on target entities.
+     * Silently skips if the entity doesn't have these columns (e.g., __mj targets).
+     */
+    private SetStandardIntegrationFields;
+    /**
+     * Creates or updates a CompanyIntegrationRecordMap entry to track the external↔MJ mapping.
+     */
+    private SaveRecordMap;
+    /**
+     * Creates a CompanyIntegrationRunDetail record for audit/reporting.
+     */
+    private CreateRunDetail;
+    /**
+     * Merges an entity-map-level result into the aggregate result.
+     */
+    private MergeResult;
+    /**
+     * Finalizes a successful run with aggregate totals and emits a completion notification.
+     */
+    private FinalizeRun;
+    /**
+     * Marks a run as failed after an unrecoverable error and emits a failure notification.
+     */
+    private FailRun;
+    /**
+     * Builds a SyncNotification for a completed run (success or completed-with-errors).
+     */
+    private buildCompletionNotification;
+    /**
+     * Builds a SyncNotification for a catastrophically failed run.
+     */
+    private buildFailureNotification;
+    /**
+     * Formats a human-readable sync result body for notification messages.
+     */
+    private buildSyncResultBody;
+    /**
+     * Invokes the notification callback without propagating exceptions.
+     */
+    private safeNotify;
+    protected get Base(): IntegrationEngineBase;
+    /**
+     * Configures the engine by loading all integration metadata.
+     * Delegates to IntegrationEngineBase.Config().
+     */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    get Integrations(): MJIntegrationEntity[];
+    get SourceTypes(): MJIntegrationSourceTypeEntity[];
+    get CompanyIntegrations(): MJCompanyIntegrationEntity[];
+    get EntityMaps(): MJCompanyIntegrationEntityMapEntity[];
+    get FieldMaps(): MJCompanyIntegrationFieldMapEntity[];
+    get Watermarks(): MJCompanyIntegrationSyncWatermarkEntity[];
+    GetIntegrationByID(id: string): MJIntegrationEntity | undefined;
+    GetIntegrationByName(name: string): MJIntegrationEntity | undefined;
+    GetCompanyIntegrationByID(id: string): MJCompanyIntegrationEntity | undefined;
+    GetCompanyIntegrationsByIntegrationID(integrationID: string): MJCompanyIntegrationEntity[];
+    GetEntityMapsForCompanyIntegration(companyIntegrationID: string): MJCompanyIntegrationEntityMapEntity[];
+    GetFieldMapsForEntityMap(entityMapID: string): MJCompanyIntegrationFieldMapEntity[];
+    GetEnabledEntityMaps(companyIntegrationID: string): MJCompanyIntegrationEntityMapEntity[];
+    GetIntegrationForCompanyIntegration(companyIntegrationID: string): MJIntegrationEntity | undefined;
+    get IntegrationObjects(): MJIntegrationObjectEntity[];
+    get IntegrationObjectFields(): MJIntegrationObjectFieldEntity[];
+    GetIntegrationObjectsByIntegrationID(integrationID: string): MJIntegrationObjectEntity[];
+    GetIntegrationObject(integrationID: string, objectName: string): MJIntegrationObjectEntity | undefined;
+    GetIntegrationObjectByID(objectID: string): MJIntegrationObjectEntity | undefined;
+    GetIntegrationObjectFields(objectID: string): MJIntegrationObjectFieldEntity[];
+    GetActiveIntegrationObjects(integrationID: string): MJIntegrationObjectEntity[];
+    GetObjectsInDependencyOrder(integrationID: string): MJIntegrationObjectEntity[];
+    static get Instance(): IntegrationEngine;
+}
+//# sourceMappingURL=IntegrationEngine.d.ts.map

package/dist/IntegrationEngine.d.ts.map

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