@memberjunction/integration-connectors 5.34.1 → 5.36.0

package/dist/MagnetMailConnector.js

@@ -0,0 +1,816 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * ⚠️ NEEDS T10 LIVE VERIFICATION BEFORE PRODUCTION ⚠️
+ *
+ * 2026-05-20 vendor-truth audit (vs public WSDL at hlma-apie1.magnetmail.net/mmapi.asmx?WSDL)
+ * found 8 wire-level mismatches between this connector and the vendor's actual API
+ * surface. **All 8 are now fixed** based on WSDL evidence. T10 sandbox verification
+ * is still needed before customer rollout.
+ *
+ * Fixed in this round:
+ *   ✓ SOAP namespace: changed 'http://api.magnetmail.net/' → 'http://www.magnetmail.net/'
+ *   ✓ Auth placement: moved from operation body to <mmAuthHeader> SOAP HEADER
+ *   ✓ Authenticate field: 'user_id' → 'username'
+ *   ✓ Authenticate response: now reads <sessionId> (with capital S/I) as primary
+ *   ✓ Pagination: 'start_row'/'row_count' → 'pageNumber'/'pageCount' with
+ *     SupportsPagination=false on operations that take no pagination
+ *     (searchForRecipients, getMessagesUTC)
+ *   ✓ getMessagesUTC watermark params in metadata: 'send_date_*' →
+ *     'sentStartDate'/'sentEndDate'
+ *   ✓ addRecipient Groups[] complex array: declared via Recipients DQP hint
+ *   ✓ searchForRecipients <criteria> wrapper: envelope-builder branches via the
+ *     COMPLEX_WRAPPERS map so the filter args nest inside <criteria> for this
+ *     specific operation. Add entries to that map for any future operation the
+ *     WSDL wraps similarly.
+ *
+ * Until T10 (live tenant) confirms this connector now exchanges successful calls,
+ * keep customer-facing rollout gated.
+ */
+import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import { BaseIntegrationConnector, } from '@memberjunction/integration-engine';
+// ─── Constants ───────────────────────────────────────────────────────
+/** Default MagnetMail SOAP endpoint (shared hostname, not per-customer). */
+const DEFAULT_ENDPOINT = 'https://hlma-apie1.magnetmail.net/mmapi.asmx';
+/** Default MagnetMail SOAP namespace (derived from the public WSDL's tns). */
+const DEFAULT_NAMESPACE = 'http://www.magnetmail.net/';
+/** Default request timeout for MagnetMail (slower than typical REST). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+/** Default minimum milliseconds between API calls. */
+const DEFAULT_MIN_REQUEST_INTERVAL_MS = 500;
+/** Default retry count. */
+const DEFAULT_MAX_RETRIES = 4;
+/** Default session TTL — re-authenticate after 30 minutes of use. */
+const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
+/** Keys in DefaultQueryParams JSON that are reserved for connector behavior, not SOAP args. */
+const RESERVED_META_KEYS = new Set([
+    'create_action', 'update_action', 'delete_action', 'detail_action',
+    'count_action', 'run_action', 'enhanced_action',
+    'beta_create_action', 'beta_status_action',
+    'watermark_field', 'watermark_from_param', 'watermark_to_param',
+]);
+// ─── MagnetMail Static Object Metadata for Action Generation ─────────
+const MAGNETMAIL_OBJECTS = [
+    {
+        Name: 'Recipients',
+        DisplayName: 'Recipient',
+        Description: 'An email recipient / contact record in MagnetMail.',
+        SupportsWrite: true,
+        Fields: [
+            { Name: 'recipient_id', DisplayName: 'Recipient ID', Type: 'number', IsRequired: true, IsReadOnly: true, IsPrimaryKey: true, Description: 'MagnetMail recipient identifier (integer).' },
+            { Name: 'email', DisplayName: 'Email', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Primary email address (de-facto natural key).' },
+            { Name: 'first_name', DisplayName: 'First Name', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'First name.' },
+            { Name: 'last_name', DisplayName: 'Last Name', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Last name.' },
+            { Name: 'company', DisplayName: 'Company', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Company name.' },
+            { Name: 'phone', DisplayName: 'Phone', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Phone number.' },
+            { Name: 'unsubscribed', DisplayName: 'Unsubscribed', Type: 'boolean', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'True when the recipient has unsubscribed.' },
+        ],
+    },
+    {
+        Name: 'Groups',
+        DisplayName: 'Group',
+        Description: 'A distribution group in MagnetMail.',
+        SupportsWrite: true,
+        Fields: [
+            { Name: 'group_id', DisplayName: 'Group ID', Type: 'number', IsRequired: true, IsReadOnly: true, IsPrimaryKey: true, Description: 'Group identifier.' },
+            { Name: 'group_name', DisplayName: 'Group Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Group name.' },
+            { Name: 'description', DisplayName: 'Description', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Group description.' },
+            { Name: 'category_id', DisplayName: 'Category ID', Type: 'number', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Associated category.' },
+        ],
+    },
+    {
+        Name: 'Messages',
+        DisplayName: 'Message',
+        Description: 'An email message / template in MagnetMail.',
+        SupportsWrite: true,
+        Fields: [
+            { Name: 'message_id', DisplayName: 'Message ID', Type: 'number', IsRequired: true, IsReadOnly: true, IsPrimaryKey: true, Description: 'Message identifier.' },
+            { Name: 'message_name', DisplayName: 'Message Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Message name.' },
+            { Name: 'subject', DisplayName: 'Subject', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Email subject.' },
+            { Name: 'from_email', DisplayName: 'From Email', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Sender email address.' },
+            { Name: 'createDate', DisplayName: 'Create Date', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Message creation timestamp.' },
+            { Name: 'lastSent', DisplayName: 'Last Sent', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Most recent send timestamp.' },
+        ],
+    },
+    {
+        Name: 'UploadJobs',
+        DisplayName: 'Upload Job',
+        Description: 'An async bulk CSV upload job in MagnetMail.',
+        SupportsWrite: true,
+        Fields: [
+            { Name: 'jobid', DisplayName: 'Job ID', Type: 'number', IsRequired: true, IsReadOnly: true, IsPrimaryKey: true, Description: 'Upload job identifier.' },
+            { Name: 'status', DisplayName: 'Status', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Job status.' },
+            { Name: 'total_rows', DisplayName: 'Total Rows', Type: 'number', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Total rows in CSV.' },
+            { Name: 'processed_rows', DisplayName: 'Processed Rows', Type: 'number', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Number of rows processed.' },
+        ],
+    },
+];
+// ─── Connector Implementation ────────────────────────────────────────
+/**
+ * Connector for Higher Logic MagnetMail (mmapi.asmx SOAP API).
+ *
+ * Extends BaseIntegrationConnector directly because MagnetMail is SOAP/XML.
+ * The generic BaseRESTIntegrationConnector pagination helpers don't apply;
+ * MagnetMail has per-operation offset/row_count pagination, UTC-variant names,
+ * and envelope-wrapped responses that need XML parsing.
+ *
+ * Operations are driven by `IntegrationObject` metadata:
+ *   - `APIPath` holds the SOAP action name for list/read (e.g., `getMessagesUTC`)
+ *   - `ResponseDataKey` holds the response element wrapping the result (e.g., `getMessagesUTCResult`)
+ *   - `DefaultQueryParams` carries additional metadata:
+ *       - `create_action` / `update_action` / `delete_action` / `detail_action` — SOAP action names
+ *       - `watermark_field` / `watermark_from_param` / `watermark_to_param` — incremental sync settings
+ *
+ * Auth flow:
+ *   1. POST `Authenticate` with userId + password -> session token
+ *   2. Attach (user_id, session) to every subsequent SOAP call
+ *   3. Cache session for SESSION_TTL_MS; refresh on expiry or auth failure
+ */
+let MagnetMailConnector = class MagnetMailConnector extends BaseIntegrationConnector {
+    constructor() {
+        // ── State ────────────────────────────────────────────────────────
+        super(...arguments);
+        this.cachedSession = null;
+        this.lastRequestTime = 0;
+    }
+    // ── Capability Getters ───────────────────────────────────────────
+    get SupportsCreate() { return true; }
+    get SupportsUpdate() { return true; }
+    get SupportsDelete() { return true; }
+    get SupportsSearch() { return false; }
+    get SupportsListing() { return false; }
+    get IntegrationName() { return 'MagnetMail'; }
+    // ── Action Generation ────────────────────────────────────────────
+    GetIntegrationObjects() {
+        return MAGNETMAIL_OBJECTS;
+    }
+    GetActionGeneratorConfig() {
+        const objects = this.GetIntegrationObjects();
+        if (objects.length === 0)
+            return null;
+        return {
+            IntegrationName: 'MagnetMail',
+            CategoryName: 'MagnetMail',
+            IconClass: 'fa-solid fa-envelope-circle-check',
+            Objects: objects,
+            IncludeSearch: false,
+            IncludeList: false,
+            CategoryDescription: 'Higher Logic MagnetMail email marketing integration actions',
+            ParentCategoryName: 'Business Apps',
+        };
+    }
+    // ── Default Configuration ────────────────────────────────────────
+    GetDefaultConfiguration() {
+        return {
+            DefaultSchemaName: 'MagnetMail',
+            DefaultObjects: [
+                {
+                    SourceObjectName: 'Recipients',
+                    TargetTableName: 'MagnetMail_Recipient',
+                    TargetEntityName: 'MagnetMail Recipients',
+                    SyncEnabled: true,
+                    FieldMappings: this.GetDefaultFieldMappings('Recipients', 'Contacts'),
+                },
+                {
+                    SourceObjectName: 'Groups',
+                    TargetTableName: 'MagnetMail_Group',
+                    TargetEntityName: 'MagnetMail Groups',
+                    SyncEnabled: true,
+                    FieldMappings: [],
+                },
+                {
+                    SourceObjectName: 'Messages',
+                    TargetTableName: 'MagnetMail_Message',
+                    TargetEntityName: 'MagnetMail Messages',
+                    SyncEnabled: true,
+                    FieldMappings: [],
+                },
+            ],
+        };
+    }
+    GetDefaultFieldMappings(objectName, _entityName) {
+        if (objectName === 'Recipients') {
+            return [
+                { SourceFieldName: 'recipient_id', DestinationFieldName: 'ExternalID', IsKeyField: true },
+                { SourceFieldName: 'email', DestinationFieldName: 'Email' },
+                { SourceFieldName: 'first_name', DestinationFieldName: 'FirstName' },
+                { SourceFieldName: 'last_name', DestinationFieldName: 'LastName' },
+                { SourceFieldName: 'phone', DestinationFieldName: 'Phone' },
+                { SourceFieldName: 'company', DestinationFieldName: 'Company' },
+            ];
+        }
+        return [];
+    }
+    // ── TestConnection ───────────────────────────────────────────────
+    /**
+     * Exercises the Authenticate operation and then calls getUserDetails to
+     * validate the session token is accepted by a regular endpoint.
+     */
+    async TestConnection(companyIntegration, contextUser) {
+        try {
+            const session = await this.GetSession(companyIntegration, contextUser, true);
+            const response = await this.InvokeSoapOperation(session, 'getUserDetails', {});
+            const account = this.ExtractNodeText(response, 'account_name') ?? 'authenticated';
+            return {
+                Success: true,
+                Message: `Successfully authenticated to MagnetMail (user_id=${session.Config.UserId}, account=${account})`,
+                ServerVersion: 'MagnetMail mmapi.asmx (SOAP 1.1/1.2)',
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { Success: false, Message: `Connection failed: ${message}` };
+        }
+    }
+    // ── Discovery ────────────────────────────────────────────────────
+    /**
+     * Returns static metadata — MagnetMail's WSDL is fixed and no runtime
+     * discovery is possible for SOAP operations. Engine's cached IntegrationObjects
+     * are returned when available; otherwise the connector's static list.
+     */
+    async DiscoverObjects(companyIntegration, _contextUser) {
+        const cached = IntegrationEngineBase.Instance.GetActiveIntegrationObjects(companyIntegration.IntegrationID);
+        if (cached && cached.length > 0) {
+            return cached.map(obj => ({
+                ID: obj.ID,
+                Name: obj.Name,
+                Label: obj.DisplayName ?? obj.Name,
+                Description: obj.Description ?? undefined,
+                SupportsIncrementalSync: obj.SupportsIncrementalSync,
+                SupportsWrite: obj.SupportsWrite,
+            }));
+        }
+        return MAGNETMAIL_OBJECTS.map(o => ({
+            Name: o.Name,
+            Label: o.DisplayName,
+            Description: o.Description,
+            SupportsIncrementalSync: o.Name === 'Messages' || o.Name === 'Unsubscribes' || o.Name === 'MessageTrackingDetailed',
+            SupportsWrite: o.SupportsWrite,
+        }));
+    }
+    async DiscoverFields(companyIntegration, objectName, _contextUser) {
+        const cached = IntegrationEngineBase.Instance.GetIntegrationObject(companyIntegration.IntegrationID, objectName);
+        if (cached) {
+            const fields = IntegrationEngineBase.Instance.GetIntegrationObjectFields(cached.ID);
+            return fields.map(f => ({
+                Name: f.Name,
+                Label: f.DisplayName ?? f.Name,
+                Description: f.Description ?? undefined,
+                DataType: f.Type,
+                IsRequired: f.IsRequired,
+                IsUniqueKey: f.IsUniqueKey || f.IsPrimaryKey,
+                IsReadOnly: f.IsReadOnly,
+                IsForeignKey: f.RelatedIntegrationObjectID != null,
+                ForeignKeyTarget: f.RelatedIntegrationObject ?? null,
+            }));
+        }
+        const obj = MAGNETMAIL_OBJECTS.find(o => o.Name === objectName);
+        if (!obj)
+            return [];
+        return obj.Fields.map(f => ({
+            Name: f.Name,
+            Label: f.DisplayName,
+            Description: f.Description,
+            DataType: f.Type,
+            IsRequired: f.IsRequired,
+            IsUniqueKey: f.IsPrimaryKey,
+            IsReadOnly: f.IsReadOnly,
+        }));
+    }
+    // ── FetchChanges ─────────────────────────────────────────────────
+    /**
+     * Drives a list/read SOAP operation using the object's metadata. Pagination
+     * uses MagnetMail's `start_row` / `row_count` convention; incremental sync
+     * passes watermark_from/to parameters when configured on the IntegrationObject.
+     */
+    async FetchChanges(ctx) {
+        const obj = this.ResolveObject(ctx.CompanyIntegration.IntegrationID, ctx.ObjectName);
+        const meta = this.BuildObjectMeta(obj);
+        const session = await this.GetSession(ctx.CompanyIntegration, ctx.ContextUser);
+        const offset = ctx.CurrentOffset ?? 0;
+        const pageSize = ctx.BatchSize || obj.DefaultPageSize || 500;
+        const args = this.BuildFetchArgs(meta, ctx, offset, pageSize);
+        const responseXml = await this.InvokeSoapOperation(session, meta.ListAction, args);
+        const records = this.ParseRecordArray(responseXml, meta.ResultPath);
+        const pkField = this.GetPrimaryKeyField(obj.ID);
+        const externalRecords = records.map(r => this.RawToExternalRecord(r, ctx.ObjectName, pkField));
+        const watermarkAfter = meta.WatermarkField ? this.ComputeWatermark(records, meta.WatermarkField) : undefined;
+        return {
+            Records: externalRecords,
+            HasMore: obj.SupportsPagination && records.length >= pageSize,
+            NewWatermarkValue: watermarkAfter,
+            NextOffset: records.length >= pageSize ? offset + records.length : undefined,
+        };
+    }
+    // ── CRUD operations ──────────────────────────────────────────────
+    async CreateRecord(ctx) {
+        return this.ExecuteMutation(ctx, 'CreateAction', ctx.Attributes, null);
+    }
+    async UpdateRecord(ctx) {
+        return this.ExecuteMutation(ctx, 'UpdateAction', ctx.Attributes, ctx.ExternalID);
+    }
+    async DeleteRecord(ctx) {
+        return this.ExecuteMutation(ctx, 'DeleteAction', {}, ctx.ExternalID);
+    }
+    async GetRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const obj = this.ResolveObject(companyIntegration.IntegrationID, ctx.ObjectName);
+        const meta = this.BuildObjectMeta(obj);
+        const action = meta.DetailAction;
+        if (!action)
+            return null;
+        const session = await this.GetSession(companyIntegration, contextUser);
+        const pkField = this.GetPrimaryKeyField(obj.ID);
+        const args = { ...meta.ExtraArgs, [pkField]: ctx.ExternalID };
+        const responseXml = await this.InvokeSoapOperation(session, action, args);
+        const records = this.ParseRecordArray(responseXml, `${action}Result`);
+        if (records.length === 0)
+            return null;
+        return this.RawToExternalRecord(records[0], ctx.ObjectName, pkField);
+    }
+    // ── Mutation helper ──────────────────────────────────────────────
+    /**
+     * Shared create/update/delete implementation. Reads the mutation SOAP action
+     * name from the IntegrationObject's DefaultQueryParams metadata and POSTs
+     * the given attributes.
+     */
+    async ExecuteMutation(ctx, metaKey, attributes, externalID) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const obj = this.ResolveObject(companyIntegration.IntegrationID, ctx.ObjectName);
+        const meta = this.BuildObjectMeta(obj);
+        const actionName = this.GetMutationActionName(meta, metaKey);
+        if (!actionName) {
+            return {
+                Success: false,
+                ErrorMessage: `${metaKey} is not supported for MagnetMail object ${ctx.ObjectName}`,
+                StatusCode: 400,
+            };
+        }
+        try {
+            const session = await this.GetSession(companyIntegration, contextUser);
+            const args = this.BuildMutationArgs(meta, attributes, externalID, obj);
+            const responseXml = await this.InvokeSoapOperation(session, actionName, args);
+            const returnedId = this.ExtractMutationResultId(responseXml, actionName, obj) ?? externalID ?? '';
+            return { Success: true, ExternalID: returnedId, StatusCode: 200 };
+        }
+        catch (err) {
+            return this.BuildCRUDError(err, metaKey, ctx.ObjectName);
+        }
+    }
+    GetMutationActionName(meta, key) {
+        if (key === 'CreateAction')
+            return meta.CreateAction;
+        if (key === 'UpdateAction')
+            return meta.UpdateAction;
+        return meta.DeleteAction;
+    }
+    BuildMutationArgs(meta, attributes, externalID, obj) {
+        const args = { ...meta.ExtraArgs };
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value == null)
+                continue;
+            args[key] = String(value);
+        }
+        if (externalID != null) {
+            const pkField = this.GetPrimaryKeyField(obj.ID);
+            args[pkField] = externalID;
+        }
+        return args;
+    }
+    /**
+     * Attempts to extract an ID from a create/update response. MagnetMail
+     * conventions vary per operation; this falls back to returning the
+     * external ID already passed in.
+     */
+    ExtractMutationResultId(responseXml, action, obj) {
+        const pkField = this.GetPrimaryKeyField(obj.ID);
+        const direct = this.ExtractNodeText(responseXml, pkField);
+        if (direct)
+            return direct;
+        const resultPath = `${action}Result`;
+        const wrapped = this.ExtractWrappedNodeText(responseXml, resultPath, pkField);
+        if (wrapped)
+            return wrapped;
+        return null;
+    }
+    // ── Session Management ───────────────────────────────────────────
+    async GetSession(companyIntegration, contextUser, forceRefresh = false) {
+        if (!forceRefresh && this.cachedSession && this.IsSessionValid()) {
+            return this.cachedSession;
+        }
+        const config = await this.ParseConfig(companyIntegration, contextUser);
+        const token = await this.Authenticate(config);
+        const session = {
+            SessionToken: token,
+            CreatedAt: Date.now(),
+            Config: config,
+        };
+        this.cachedSession = session;
+        return session;
+    }
+    IsSessionValid() {
+        if (!this.cachedSession)
+            return false;
+        const ttl = this.cachedSession.Config.SessionTTLMs ?? DEFAULT_SESSION_TTL_MS;
+        return Date.now() - this.cachedSession.CreatedAt < ttl;
+    }
+    async Authenticate(config) {
+        // Vendor WSDL: Authenticate accepts {username, password} (NOT user_id).
+        const envelope = this.BuildEnvelope(config, 'Authenticate', {
+            username: config.UserId,
+            password: config.Password,
+        }, /* includeSession */ false);
+        const responseXml = await this.PostSOAP(config, 'Authenticate', envelope);
+        // Vendor returns <sessionId> (capital S, capital I). Try AuthenticateResult
+        // first (some operations wrap in an *Result envelope), then sessionId, and
+        // fall back to lowercase variants for older/forked deployments.
+        const token = this.ExtractNodeText(responseXml, 'AuthenticateResult')
+            ?? this.ExtractNodeText(responseXml, 'sessionId')
+            ?? this.ExtractNodeText(responseXml, 'session')
+            ?? this.ExtractNodeText(responseXml, 'sessionid');
+        if (!token) {
+            throw new Error('MagnetMailConnector: Authenticate did not return a session token');
+        }
+        return token;
+    }
+    // ── Configuration Parsing ────────────────────────────────────────
+    async ParseConfig(companyIntegration, contextUser) {
+        const credentialID = companyIntegration.CredentialID;
+        if (credentialID) {
+            const config = await this.LoadFromCredentialEntity(credentialID, contextUser);
+            if (config)
+                return config;
+        }
+        const configJson = companyIntegration.Configuration;
+        if (configJson) {
+            const parsed = JSON.parse(configJson);
+            return this.ValidateConfig(parsed);
+        }
+        throw new Error('MagnetMailConnector: No credentials or configuration found on CompanyIntegration');
+    }
+    async LoadFromCredentialEntity(credentialID, contextUser, provider) {
+        const md = provider ?? new Metadata();
+        const credential = await md.GetEntityObject('MJ: Credentials', contextUser);
+        const loaded = await credential.Load(credentialID);
+        if (!loaded || !credential.Values)
+            return null;
+        try {
+            const raw = JSON.parse(credential.Values);
+            const parsed = {
+                UserId: raw.userId ?? raw.UserId,
+                Password: raw.password ?? raw.Password,
+                Endpoint: raw.endpoint ?? raw.Endpoint,
+                Namespace: raw.namespace ?? raw.Namespace,
+            };
+            return this.ValidateConfig(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    ValidateConfig(raw) {
+        if (!raw.UserId)
+            throw new Error('MagnetMailConnector: UserId is required');
+        if (!raw.Password)
+            throw new Error('MagnetMailConnector: Password is required');
+        return {
+            UserId: raw.UserId,
+            Password: raw.Password,
+            Endpoint: raw.Endpoint ?? DEFAULT_ENDPOINT,
+            Namespace: raw.Namespace ?? DEFAULT_NAMESPACE,
+            MaxRetries: raw.MaxRetries ?? DEFAULT_MAX_RETRIES,
+            RequestTimeoutMs: raw.RequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            MinRequestIntervalMs: raw.MinRequestIntervalMs ?? DEFAULT_MIN_REQUEST_INTERVAL_MS,
+            SessionTTLMs: raw.SessionTTLMs ?? DEFAULT_SESSION_TTL_MS,
+        };
+    }
+    // ── SOAP helpers ─────────────────────────────────────────────────
+    /**
+     * Invokes a SOAP operation with session authentication. The `args` map is
+     * serialised as child elements of the operation element; complex types
+     * should be pre-serialised to string by callers.
+     */
+    async InvokeSoapOperation(session, action, args) {
+        const envelope = this.BuildEnvelope(session.Config, action, args, /* includeSession */ true, session.SessionToken);
+        return this.PostSOAP(session.Config, action, envelope);
+    }
+    /**
+     * Builds a SOAP 1.1 envelope. Vendor WSDL places authentication in a SOAP
+     * HEADER element <mmAuthHeader> containing <sessionId> + <user_id> — NOT in
+     * the operation body. The operation body carries only operation-specific args.
+     */
+    BuildEnvelope(config, operation, args, includeSession, sessionToken) {
+        const namespace = config.Namespace ?? DEFAULT_NAMESPACE;
+        const headerBlock = includeSession
+            ? `  <soap:Header>\n    <mmAuthHeader xmlns="${namespace}">\n      <sessionId>${this.EscapeXmlValue(sessionToken ?? '')}</sessionId>\n      <user_id>${this.EscapeXmlValue(config.UserId)}</user_id>\n    </mmAuthHeader>\n  </soap:Header>\n`
+            : '';
+        // Operations whose WSDL wraps all arguments in a single complex element.
+        // searchForRecipients is the canonical one: all filter fields go INSIDE
+        // a <criteria> element rather than as flat children of the operation.
+        const COMPLEX_WRAPPERS = {
+            'searchForRecipients': 'criteria',
+        };
+        const wrapper = COMPLEX_WRAPPERS[operation];
+        const renderArgs = (entries) => entries.map(([k, v]) => `<${k}>${this.EscapeXmlValue(v)}</${k}>`).join('\n        ');
+        let body;
+        if (wrapper) {
+            const inner = renderArgs(Object.entries(args));
+            body = `      <${wrapper}>\n        ${inner}\n      </${wrapper}>`;
+        }
+        else {
+            body = `      ${renderArgs(Object.entries(args))}`;
+        }
+        return `<?xml version="1.0" encoding="utf-8"?>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+${headerBlock}  <soap:Body>
+    <${operation} xmlns="${namespace}">
+${body}
+    </${operation}>
+  </soap:Body>
+</soap:Envelope>`;
+    }
+    /**
+     * POSTs a SOAP envelope with throttling, retry, and timeout.
+     */
+    async PostSOAP(config, action, envelope) {
+        const endpoint = config.Endpoint ?? DEFAULT_ENDPOINT;
+        const namespace = config.Namespace ?? DEFAULT_NAMESPACE;
+        const soapAction = `${namespace}${action}`;
+        const maxRetries = config.MaxRetries ?? DEFAULT_MAX_RETRIES;
+        const timeoutMs = config.RequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const minInterval = config.MinRequestIntervalMs ?? DEFAULT_MIN_REQUEST_INTERVAL_MS;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            await this.Throttle(minInterval);
+            const outcome = await this.ExecuteSoapAttempt(endpoint, envelope, soapAction, timeoutMs);
+            if (outcome.retryable && attempt < maxRetries) {
+                const delay = Math.min(Math.pow(2, attempt) * 1000, 15000);
+                await this.Sleep(delay);
+                continue;
+            }
+            if (outcome.error)
+                throw outcome.error;
+            return outcome.xml;
+        }
+        throw new Error(`MagnetMailConnector: exhausted ${maxRetries + 1} attempts for SOAP action "${action}"`);
+    }
+    async ExecuteSoapAttempt(endpoint, envelope, soapAction, timeoutMs) {
+        const controller = new AbortController();
+        const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'text/xml; charset=utf-8',
+                    'SOAPAction': `"${soapAction}"`,
+                    'Accept': 'text/xml',
+                },
+                body: envelope,
+                signal: controller.signal,
+            });
+            this.lastRequestTime = Date.now();
+            const xml = await response.text();
+            if (response.status === 429 || response.status >= 500) {
+                return { error: new Error(`MagnetMail HTTP ${response.status}: ${xml.slice(0, 500)}`), retryable: true };
+            }
+            if (!response.ok) {
+                return { error: new Error(`MagnetMail HTTP ${response.status}: ${xml.slice(0, 500)}`), retryable: false };
+            }
+            this.CheckSoapFault(xml);
+            return { xml, retryable: false };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const retryable = message.includes('abort') || message.includes('timeout') || message.includes('ECONNRESET');
+            return { error: new Error(`MagnetMail SOAP request failed: ${message}`), retryable };
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    // ── XML parsing (regex-based, consistent with SageIntacct approach) ──
+    /**
+     * Throws a descriptive error if the SOAP response contains a fault element.
+     */
+    CheckSoapFault(xml) {
+        const faultMatch = xml.match(/<soap:Fault>([\s\S]*?)<\/soap:Fault>/i);
+        if (!faultMatch)
+            return;
+        const fault = faultMatch[1];
+        const code = this.ExtractNodeText(fault, 'faultcode') ?? 'UNKNOWN';
+        const reason = this.ExtractNodeText(fault, 'faultstring') ?? this.ExtractNodeText(fault, 'Reason') ?? 'unknown';
+        throw new Error(`MagnetMail SOAP Fault ${code}: ${reason}`);
+    }
+    /**
+     * Extracts the text content of the first element with the given tag name.
+     * Namespace-agnostic — matches by local name.
+     */
+    ExtractNodeText(xml, tag) {
+        const regex = new RegExp(`<(?:\\w+:)?${this.EscapeRegex(tag)}[^>]*>([\\s\\S]*?)<\\/(?:\\w+:)?${this.EscapeRegex(tag)}>`, 'i');
+        const match = xml.match(regex);
+        return match ? this.DecodeXmlEntities(match[1].trim()) : null;
+    }
+    /**
+     * Extracts a node nested inside another wrapper node (e.g., `<FooResult><id>42</id></FooResult>`).
+     */
+    ExtractWrappedNodeText(xml, wrapperTag, innerTag) {
+        const wrapperRegex = new RegExp(`<(?:\\w+:)?${this.EscapeRegex(wrapperTag)}[^>]*>([\\s\\S]*?)<\\/(?:\\w+:)?${this.EscapeRegex(wrapperTag)}>`, 'i');
+        const wrapperMatch = xml.match(wrapperRegex);
+        if (!wrapperMatch)
+            return null;
+        return this.ExtractNodeText(wrapperMatch[1], innerTag);
+    }
+    /**
+     * Parses an array of records inside a result wrapper. Returns one plain
+     * object per record element. Works for both singular wrapper responses
+     * (e.g., GetMessageDetails) and array-style (e.g., getMessagesUTC).
+     */
+    ParseRecordArray(xml, resultPath) {
+        const containerXml = resultPath ? this.FindElementContent(xml, resultPath) : xml;
+        if (!containerXml)
+            return [];
+        const childElements = this.ExtractDirectChildElements(containerXml);
+        if (childElements.length === 0)
+            return [];
+        // Group consecutive same-tag elements as a record array
+        const records = [];
+        for (const child of childElements) {
+            records.push(this.ParseElementFields(child.content));
+        }
+        return records;
+    }
+    FindElementContent(xml, tag) {
+        const regex = new RegExp(`<(?:\\w+:)?${this.EscapeRegex(tag)}[^>]*>([\\s\\S]*?)<\\/(?:\\w+:)?${this.EscapeRegex(tag)}>`, 'i');
+        const match = xml.match(regex);
+        return match ? match[1] : null;
+    }
+    ExtractDirectChildElements(xml) {
+        const results = [];
+        const regex = /<(?:\w+:)?(\w+)(?:\s[^>]*)?>([\s\S]*?)<\/(?:\w+:)?\1>/g;
+        let match;
+        while ((match = regex.exec(xml)) !== null) {
+            results.push({ tag: match[1], content: match[2] });
+        }
+        return results;
+    }
+    /**
+     * Parses a record element's children into a flat key-value map. Nested
+     * objects and arrays are returned as raw inner XML strings (caller can
+     * re-parse if needed — simple enough for most MagnetMail fields).
+     */
+    ParseElementFields(xml) {
+        const record = {};
+        const children = this.ExtractDirectChildElements(xml);
+        for (const child of children) {
+            const value = this.CoerceFieldValue(child.content.trim());
+            // Last-write-wins for repeated child elements; MagnetMail rarely emits them in these shapes
+            record[child.tag] = value;
+        }
+        return record;
+    }
+    CoerceFieldValue(raw) {
+        if (raw === '')
+            return null;
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        if (/^-?\d+$/.test(raw))
+            return parseInt(raw, 10);
+        if (/^-?\d+\.\d+$/.test(raw))
+            return parseFloat(raw);
+        return this.DecodeXmlEntities(raw);
+    }
+    // ── Metadata helpers ─────────────────────────────────────────────
+    ResolveObject(integrationID, objectName) {
+        const obj = IntegrationEngineBase.Instance.GetIntegrationObject(integrationID, objectName);
+        if (!obj)
+            throw new Error(`MagnetMailConnector: unknown IntegrationObject "${objectName}"`);
+        return obj;
+    }
+    BuildObjectMeta(obj) {
+        const listAction = obj.APIPath || '';
+        if (!listAction)
+            throw new Error(`MagnetMailConnector: IntegrationObject "${obj.Name}" is missing APIPath (SOAP action)`);
+        const resultPath = obj.ResponseDataKey || `${listAction}Result`;
+        const raw = this.ParseDefaultQueryParams(obj);
+        const extraArgs = {};
+        for (const [k, v] of Object.entries(raw)) {
+            if (RESERVED_META_KEYS.has(k))
+                continue;
+            extraArgs[k] = String(v);
+        }
+        return {
+            ListAction: listAction,
+            ResultPath: resultPath,
+            CreateAction: raw['create_action'],
+            UpdateAction: raw['update_action'],
+            DeleteAction: raw['delete_action'],
+            DetailAction: raw['detail_action'],
+            WatermarkField: raw['watermark_field'],
+            WatermarkFromParam: raw['watermark_from_param'],
+            WatermarkToParam: raw['watermark_to_param'],
+            ExtraArgs: extraArgs,
+        };
+    }
+    ParseDefaultQueryParams(obj) {
+        if (!obj.DefaultQueryParams)
+            return {};
+        try {
+            return JSON.parse(obj.DefaultQueryParams);
+        }
+        catch {
+            console.warn(`[MagnetMailConnector] Invalid DefaultQueryParams JSON for "${obj.Name}"`);
+            return {};
+        }
+    }
+    GetPrimaryKeyField(objectID) {
+        const fields = IntegrationEngineBase.Instance.GetIntegrationObjectFields(objectID);
+        const pk = fields.find(f => f.IsPrimaryKey);
+        return pk ? pk.Name : 'id';
+    }
+    BuildFetchArgs(meta, ctx, offset, pageSize) {
+        const args = { ...meta.ExtraArgs };
+        // Vendor WSDL: pagination uses 1-based pageNumber + pageCount on the
+        // operations that accept pagination. Some operations (searchForRecipients,
+        // getMessagesUTC) accept NO pagination — meta.SupportsPagination guards.
+        if (meta.SupportsPagination !== false) {
+            const pageNumber = Math.floor(offset / Math.max(1, pageSize)) + 1;
+            args['pageNumber'] = String(pageNumber);
+            args['pageCount'] = String(pageSize);
+        }
+        if (ctx.WatermarkValue && meta.WatermarkFromParam) {
+            args[meta.WatermarkFromParam] = ctx.WatermarkValue;
+        }
+        return args;
+    }
+    RawToExternalRecord(raw, objectType, pkField) {
+        const id = raw[pkField];
+        return {
+            ExternalID: id != null ? String(id) : '',
+            ObjectType: objectType,
+            Fields: raw,
+        };
+    }
+    ComputeWatermark(records, field) {
+        let latest;
+        for (const record of records) {
+            const value = record[field];
+            if (value && typeof value === 'string' && (!latest || value > latest)) {
+                latest = value;
+            }
+        }
+        return latest;
+    }
+    // ── Utility helpers ──────────────────────────────────────────────
+    async Throttle(minIntervalMs) {
+        const elapsed = Date.now() - this.lastRequestTime;
+        if (elapsed < minIntervalMs) {
+            await this.Sleep(minIntervalMs - elapsed);
+        }
+    }
+    Sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    EscapeXmlValue(value) {
+        return value
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    EscapeRegex(value) {
+        return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    DecodeXmlEntities(value) {
+        return value
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&apos;/g, "'")
+            .replace(/&amp;/g, '&');
+    }
+    BuildCRUDError(err, operation, objectName) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            Success: false,
+            ErrorMessage: `${operation} failed for ${objectName}: ${message}`,
+            StatusCode: 500,
+        };
+    }
+};
+MagnetMailConnector = __decorate([
+    RegisterClass(BaseIntegrationConnector, 'MagnetMailConnector')
+], MagnetMailConnector);
+export { MagnetMailConnector };
+/** Tree-shaking prevention function — import and call from module entry point. */
+export function LoadMagnetMailConnector() { }
+//# sourceMappingURL=MagnetMailConnector.js.map