@memberjunction/integration-connectors 5.35.0 → 5.37.0

package/dist/IMISConnector.js

@@ -0,0 +1,686 @@
+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;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
+// ─── Constants ─────────────────────────────────────────────────────────
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const DEFAULT_MIN_REQUEST_INTERVAL_MS = 200;
+const TOKEN_REFRESH_BUFFER_MS = 60_000;
+/** iMIS-to-SQL type mapping used when merging live-discovered field metadata. */
+const IMIS_TYPE_MAP = {
+    'string': 'string',
+    'datetime': 'datetime',
+    'date': 'date',
+    'boolean': 'boolean',
+    'int32': 'integer',
+    'int64': 'integer',
+    'integer': 'integer',
+    'long': 'integer',
+    'decimal': 'decimal',
+    'double': 'decimal',
+    'float': 'decimal',
+    'guid': 'uuid',
+    'uuid': 'uuid',
+    'monetaryamountdata': 'decimal',
+};
+// ─── Connector ─────────────────────────────────────────────────────────
+/**
+ * Connector for iMIS EMS (Advanced Solutions International) REST API.
+ *
+ * Extends BaseRESTIntegrationConnector so the generic metadata-driven fetch
+ * loop handles pagination, template variables, and record normalization.
+ * Adds iMIS-specific:
+ *   - OAuth 2.0 Password Grant / SSO refresh-token authentication
+ *   - /{entity}/metadata runtime field discovery (merged with static IntegrationObjectField metadata, IsCustom=true)
+ *   - /BOEntityDefinition runtime object discovery (customer Business Objects, IsCustom=true)
+ *   - PagedResult envelope with Offset/Limit + HasNext flag
+ *   - UpdatedOn=gt:&lt;iso-date&gt; watermark filter for incremental sync
+ *   - PUT (full replace) for updates with automatic read-modify-write merge
+ *
+ * Reference: https://developer.imis.com/docs/imis-rest-api-data-models-and-swagger-json-files
+ */
+let IMISConnector = class IMISConnector extends BaseRESTIntegrationConnector {
+    constructor() {
+        super(...arguments);
+        this.authState = null;
+        this.lastRequestTime = 0;
+        /** Current watermark for the in-flight FetchChanges — used by AppendDefaultQueryParams */
+        this.currentWatermark = null;
+    }
+    // ── Capability flags ────────────────────────────────────────────
+    get SupportsCreate() { return true; }
+    get SupportsUpdate() { return true; }
+    get SupportsDelete() { return true; }
+    get SupportsSearch() { return false; }
+    get SupportsListing() { return false; }
+    get IntegrationName() { return 'iMIS'; }
+    // ── Auth + transport (abstract methods from BaseRESTIntegrationConnector) ────
+    async Authenticate(companyIntegration, contextUser) {
+        return this.GetAuth(companyIntegration, contextUser);
+    }
+    BuildHeaders(auth) {
+        const imisAuth = auth;
+        return {
+            'Authorization': `Bearer ${imisAuth.Token}`,
+            'Accept': 'application/json',
+        };
+    }
+    async MakeHTTPRequest(auth, url, method, headers, body) {
+        const imisAuth = auth;
+        const maxRetries = imisAuth.Config.MaxRetries ?? DEFAULT_MAX_RETRIES;
+        const timeoutMs = imisAuth.Config.RequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const minInterval = imisAuth.Config.MinRequestIntervalMs ?? DEFAULT_MIN_REQUEST_INTERVAL_MS;
+        const effectiveHeaders = { ...headers };
+        if (body !== undefined && !effectiveHeaders['Content-Type']) {
+            effectiveHeaders['Content-Type'] = 'application/json';
+        }
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            await this.Throttle(minInterval);
+            const response = await this.ExecuteFetch(url, method, effectiveHeaders, body, timeoutMs);
+            this.lastRequestTime = Date.now();
+            if (response.status === 401 && attempt < maxRetries) {
+                // Token may have expired mid-request — force refresh and retry once.
+                this.authState = null;
+                const fresh = await this.GetAuth(imisAuth.Config);
+                imisAuth.Token = fresh.Token;
+                imisAuth.ExpiresAt = fresh.ExpiresAt;
+                effectiveHeaders['Authorization'] = `Bearer ${fresh.Token}`;
+                continue;
+            }
+            if (this.ShouldRetry(response.status) && attempt < maxRetries) {
+                const delay = this.ComputeRetryDelay(response, attempt);
+                await this.Sleep(delay);
+                continue;
+            }
+            return this.BuildRESTResponse(response);
+        }
+        throw new Error(`iMIS API request failed after ${maxRetries} attempt(s): ${url}`);
+    }
+    NormalizeResponse(rawBody, responseDataKey) {
+        if (rawBody == null)
+            return [];
+        // PagedResult envelope → Items
+        if (this.IsPagedResult(rawBody)) {
+            return rawBody.Items ?? [];
+        }
+        // Explicit key provided (e.g., "Items")
+        if (responseDataKey) {
+            const record = rawBody;
+            const data = record[responseDataKey];
+            if (Array.isArray(data))
+                return data;
+        }
+        if (Array.isArray(rawBody))
+            return rawBody;
+        // Single-object response (e.g., GET /{Entity}/{id})
+        return [rawBody];
+    }
+    ExtractPaginationInfo(rawBody, paginationType, currentPage, currentOffset, pageSize) {
+        if (paginationType === 'None')
+            return { HasMore: false };
+        const envelope = this.IsPagedResult(rawBody) ? rawBody : null;
+        if (!envelope) {
+            // Fallback: no PagedResult envelope → no more pages
+            return { HasMore: false };
+        }
+        const hasMore = envelope.HasNext ?? false;
+        const returnedCount = envelope.Items?.length ?? 0;
+        const nextOffset = (envelope.Offset ?? currentOffset) + returnedCount;
+        return {
+            HasMore: hasMore,
+            NextOffset: paginationType === 'Offset' ? nextOffset : undefined,
+            NextPage: paginationType === 'PageNumber' ? currentPage + 1 : undefined,
+            TotalRecords: envelope.Count,
+        };
+    }
+    GetBaseURL(_companyIntegration, auth) {
+        return auth.BaseUrl;
+    }
+    /**
+     * iMIS pagination uses `Offset` and `Limit` query parameters (capitalized).
+     * Override the base class helper to match iMIS's param names.
+     */
+    BuildPaginatedURL(basePath, obj, page, offset, cursor, effectivePageSize) {
+        const pageSize = effectivePageSize ?? obj.DefaultPageSize ?? 100;
+        const separator = basePath.includes('?') ? '&' : '?';
+        switch (obj.PaginationType) {
+            case 'PageNumber':
+                return `${basePath}${separator}Page=${page}&Limit=${pageSize}`;
+            case 'Offset':
+                return `${basePath}${separator}Offset=${offset}&Limit=${pageSize}`;
+            case 'Cursor':
+                return cursor
+                    ? `${basePath}${separator}cursor=${encodeURIComponent(cursor)}&Limit=${pageSize}`
+                    : `${basePath}${separator}Limit=${pageSize}`;
+            default:
+                return basePath;
+        }
+    }
+    /**
+     * Inject watermark filter (UpdatedOn=gt:<iso>) when an incremental sync is active.
+     * The iMIS REST API accepts operator-prefixed filter values (`gt:`, `ge:`, `lt:`) on list endpoints.
+     */
+    AppendDefaultQueryParams(url, obj) {
+        let result = super.AppendDefaultQueryParams(url, obj);
+        if (this.currentWatermark && obj.SupportsIncrementalSync) {
+            const separator = result.includes('?') ? '&' : '?';
+            const param = `UpdatedOn=${encodeURIComponent('gt:' + this.currentWatermark)}`;
+            result = `${result}${separator}${param}`;
+        }
+        return result;
+    }
+    // ── Public API: Discovery, FetchChanges, CRUD ───────────────────
+    /**
+     * Test the connection by authenticating and hitting the /Party list endpoint
+     * with a minimal page size. Confirms both auth + data-plane connectivity.
+     */
+    async TestConnection(companyIntegration, contextUser) {
+        try {
+            const auth = await this.GetAuth(companyIntegration, contextUser, true);
+            const url = `${auth.BaseUrl}/Party?Limit=1`;
+            const headers = this.BuildHeaders(auth);
+            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+            if (response.Status >= 200 && response.Status < 300) {
+                return {
+                    Success: true,
+                    Message: `Connected to iMIS EMS at ${auth.BaseUrl}`,
+                    ServerVersion: this.ExtractServerVersion(response.Headers),
+                };
+            }
+            return { Success: false, Message: `iMIS responded HTTP ${response.Status}` };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { Success: false, Message: `Connection failed: ${message}` };
+        }
+    }
+    /**
+     * Discover objects by merging:
+     *   1. Static IntegrationObject metadata (from MJ: Integration Objects table)
+     *   2. Runtime-discovered customer Business Objects via GET /BOEntityDefinition
+     *      — marked with IsCustom=true when not already present in static metadata.
+     */
+    async DiscoverObjects(companyIntegration, contextUser) {
+        const staticObjects = await super.DiscoverObjects(companyIntegration, contextUser);
+        const staticNames = new Set(staticObjects.map(o => o.Name.toLowerCase()));
+        try {
+            const customObjects = await this.DiscoverBusinessObjects(companyIntegration, contextUser);
+            const newCustom = customObjects.filter(co => !staticNames.has(co.Name.toLowerCase()));
+            return [...staticObjects, ...newCustom];
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[iMIS] Business Object discovery failed, returning static objects only: ${message}`);
+            return staticObjects;
+        }
+    }
+    /**
+     * Discover fields by merging:
+     *   1. Static IntegrationObjectField metadata (from MJ: Integration Object Fields table)
+     *   2. Runtime-discovered fields via GET /{entity}/metadata
+     *      — any live field not in the static metadata is appended with IsCustom=true
+     *      (surfaced to callers via the IsForeignKey=false / IsReadOnly mix from the live API).
+     */
+    async DiscoverFields(companyIntegration, objectName, contextUser) {
+        const staticFields = await super.DiscoverFields(companyIntegration, objectName, contextUser);
+        try {
+            const liveFields = await this.DiscoverFieldsFromLiveAPI(companyIntegration, objectName, contextUser);
+            return this.MergeFieldSchemas(staticFields, liveFields);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`[iMIS] Live field discovery failed for "${objectName}", returning static fields: ${message}`);
+            return staticFields;
+        }
+    }
+    /**
+     * Override FetchChanges to stash the current watermark so AppendDefaultQueryParams
+     * can inject the UpdatedOn filter on list requests.
+     */
+    async FetchChanges(ctx) {
+        this.currentWatermark = ctx.WatermarkValue;
+        try {
+            const result = await super.FetchChanges(ctx);
+            result.NewWatermarkValue = this.ComputeNewWatermark(result.Records, ctx.WatermarkValue);
+            return result;
+        }
+        finally {
+            this.currentWatermark = null;
+        }
+    }
+    // ── Write operations ────────────────────────────────────────────
+    async CreateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const url = `${auth.BaseUrl}/${this.NormalizeObjectPath(ctx.ObjectName)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, ctx.Attributes);
+        if (response.Status >= 200 && response.Status < 300) {
+            const body = response.Body;
+            return {
+                Success: true,
+                ExternalID: this.ExtractIdFromRecord(body),
+                StatusCode: response.Status,
+            };
+        }
+        return this.BuildCRUDError(response, 'CreateRecord', ctx.ObjectName);
+    }
+    async UpdateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const objectPath = this.NormalizeObjectPath(ctx.ObjectName);
+        // iMIS PUT is a full replace — do a read-modify-write merge of Attributes
+        // into the current record so callers can supply partial updates.
+        const current = await this.FetchSingleRecord(auth, objectPath, ctx.ExternalID);
+        if (!current) {
+            return { Success: false, ErrorMessage: `Record ${ctx.ExternalID} not found`, StatusCode: 404 };
+        }
+        const merged = { ...current, ...ctx.Attributes };
+        const url = `${auth.BaseUrl}/${objectPath}/${encodeURIComponent(ctx.ExternalID)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'PUT', headers, merged);
+        if (response.Status >= 200 && response.Status < 300) {
+            return { Success: true, ExternalID: ctx.ExternalID, StatusCode: response.Status };
+        }
+        return this.BuildCRUDError(response, 'UpdateRecord', ctx.ObjectName);
+    }
+    async DeleteRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const url = `${auth.BaseUrl}/${this.NormalizeObjectPath(ctx.ObjectName)}/${encodeURIComponent(ctx.ExternalID)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'DELETE', headers);
+        if (response.Status >= 200 && response.Status < 300) {
+            return { Success: true, ExternalID: ctx.ExternalID, StatusCode: response.Status };
+        }
+        return this.BuildCRUDError(response, 'DeleteRecord', ctx.ObjectName);
+    }
+    async GetRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const record = await this.FetchSingleRecord(auth, this.NormalizeObjectPath(ctx.ObjectName), ctx.ExternalID);
+        if (!record)
+            return null;
+        return {
+            ExternalID: ctx.ExternalID,
+            ObjectType: ctx.ObjectName,
+            Fields: record,
+        };
+    }
+    // ── Default configuration / field mappings ──────────────────────
+    GetDefaultConfiguration() {
+        return {
+            DefaultSchemaName: 'iMIS',
+            DefaultObjects: [],
+        };
+    }
+    GetDefaultFieldMappings(objectName, _entityName) {
+        switch (objectName) {
+            case 'Party':
+            case 'Person':
+                return [
+                    { SourceFieldName: 'PartyId', DestinationFieldName: 'ExternalID', IsKeyField: true },
+                    { SourceFieldName: 'FullName', DestinationFieldName: 'Name' },
+                    { SourceFieldName: 'PrimaryEmail', DestinationFieldName: 'Email' },
+                    { SourceFieldName: 'PrimaryPhone', DestinationFieldName: 'Phone' },
+                ];
+            case 'Event':
+                return [
+                    { SourceFieldName: 'EventId', DestinationFieldName: 'ExternalID', IsKeyField: true },
+                    { SourceFieldName: 'Name', DestinationFieldName: 'Name' },
+                    { SourceFieldName: 'StartDate', DestinationFieldName: 'StartDate' },
+                    { SourceFieldName: 'EndDate', DestinationFieldName: 'EndDate' },
+                ];
+            default:
+                return [];
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    //                         Private helpers
+    // ─────────────────────────────────────────────────────────────────
+    // ── Auth helpers ────────────────────────────────────────────────
+    /**
+     * Returns a valid auth context, refreshing the access token as needed.
+     * Accepts either (companyIntegration, contextUser) for the first call
+     * or a pre-parsed config for silent refresh from MakeHTTPRequest.
+     */
+    async GetAuth(source, contextUser, forceRefresh = false) {
+        if (!forceRefresh && this.authState && this.IsTokenValid(this.authState)) {
+            return this.authState;
+        }
+        const config = this.IsConfig(source)
+            ? source
+            : await this.ParseConfig(source, contextUser);
+        this.authState = await this.AcquireToken(config);
+        return this.authState;
+    }
+    IsConfig(source) {
+        return source.BaseUrl !== undefined
+            && source.Username !== undefined;
+    }
+    IsTokenValid(auth) {
+        return auth.ExpiresAt.getTime() > Date.now() + TOKEN_REFRESH_BUFFER_MS;
+    }
+    async AcquireToken(config) {
+        const baseUrl = this.StripTrailingSlash(config.BaseUrl);
+        const tokenUrl = this.ResolveTokenEndpoint(baseUrl);
+        const body = this.BuildTokenRequestBody(config);
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`iMIS token request failed (${response.status}): ${text.slice(0, 300)}`);
+        }
+        const payload = await response.json();
+        const expiresAt = new Date(Date.now() + (payload.expires_in ?? 3600) * 1000);
+        if (payload.refresh_token) {
+            config.RefreshToken = payload.refresh_token;
+        }
+        return {
+            Token: payload.access_token,
+            ExpiresAt: expiresAt,
+            Config: config,
+            BaseUrl: baseUrl,
+        };
+    }
+    /**
+     * iMIS issues tokens at the scheduler path, not under /api/. Strip /api[/]
+     * from the BaseUrl when constructing the token endpoint.
+     */
+    ResolveTokenEndpoint(baseUrl) {
+        const trimmed = baseUrl.replace(/\/api\/?$/i, '');
+        // Vendor-canonical path is lowercase '/token/' per developer.imis.com docs.
+        // IIS is normally case-insensitive on URL paths so '/Token' usually works,
+        // but a few customer reverse-proxies enforce case strictness — match docs.
+        return `${trimmed}/token/`;
+    }
+    BuildTokenRequestBody(config) {
+        const params = new URLSearchParams();
+        if (config.ClientId && config.ClientSecret && config.RefreshToken) {
+            params.set('grant_type', 'refresh_token');
+            params.set('refresh_token', config.RefreshToken);
+            params.set('client_id', config.ClientId);
+            params.set('client_secret', config.ClientSecret);
+            return params.toString();
+        }
+        params.set('grant_type', 'password');
+        params.set('username', config.Username);
+        params.set('password', config.Password);
+        return params.toString();
+    }
+    // ── Configuration parsing ───────────────────────────────────────
+    async ParseConfig(companyIntegration, contextUser) {
+        if (companyIntegration.CredentialID) {
+            const config = await this.ParseConfigFromCredential(companyIntegration.CredentialID, contextUser);
+            if (config)
+                return config;
+        }
+        if (companyIntegration.Configuration) {
+            const parsed = JSON.parse(companyIntegration.Configuration);
+            return this.ExtractConfig(parsed);
+        }
+        throw new Error('iMIS connector requires either CredentialID or Configuration JSON');
+    }
+    async ParseConfigFromCredential(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;
+        const values = JSON.parse(credential.Values);
+        return this.ExtractConfig(values);
+    }
+    ExtractConfig(values) {
+        const get = (...keys) => {
+            for (const key of keys) {
+                const hit = Object.entries(values).find(([k]) => k.toLowerCase() === key.toLowerCase());
+                if (hit)
+                    return String(hit[1] ?? '');
+            }
+            return undefined;
+        };
+        const baseUrl = get('BaseUrl', 'baseUrl', 'base_url');
+        const username = get('Username', 'username', 'user');
+        const password = get('Password', 'password', 'pass');
+        if (!baseUrl)
+            throw new Error('iMIS configuration missing required field: BaseUrl');
+        if (!username)
+            throw new Error('iMIS configuration missing required field: Username');
+        if (!password)
+            throw new Error('iMIS configuration missing required field: Password');
+        return {
+            BaseUrl: this.StripTrailingSlash(baseUrl),
+            Username: username,
+            Password: password,
+            ClientId: get('ClientId', 'clientId', 'client_id'),
+            ClientSecret: get('ClientSecret', 'clientSecret', 'client_secret'),
+            RefreshToken: get('RefreshToken', 'refreshToken', 'refresh_token'),
+        };
+    }
+    // ── Runtime discovery (BOs + field metadata) ────────────────────
+    async DiscoverBusinessObjects(companyIntegration, contextUser) {
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const url = `${auth.BaseUrl}/BOEntityDefinition?Limit=500`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300)
+            return [];
+        const records = this.NormalizeResponse(response.Body, 'Items');
+        return records
+            .filter(bo => !!bo.Name)
+            .map(bo => ({
+            Name: String(bo.Name),
+            Label: bo.DisplayName ?? String(bo.Name),
+            Description: bo.Description ?? `Customer-defined Business Object (runtime-discovered)`,
+            SupportsIncrementalSync: true,
+            SupportsWrite: true,
+        }));
+    }
+    async DiscoverFieldsFromLiveAPI(companyIntegration, objectName, contextUser) {
+        const auth = await this.GetAuth(companyIntegration, contextUser);
+        const path = this.ResolveObjectPath(companyIntegration.IntegrationID, objectName);
+        const url = `${auth.BaseUrl}${path}/metadata`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300)
+            return [];
+        const meta = response.Body;
+        const propDefs = meta?.PropertyDefinitions ?? [];
+        return propDefs
+            .filter(p => !!p.Name)
+            .map(p => this.PropertyDefinitionToFieldSchema(p));
+    }
+    PropertyDefinitionToFieldSchema(prop) {
+        const rawType = (prop.PropertyType ?? prop.PropertyTypeData?.Name ?? 'string').toLowerCase();
+        const genericType = IMIS_TYPE_MAP[rawType] ?? 'string';
+        return {
+            Name: String(prop.Name),
+            Label: prop.DisplayName ?? String(prop.Name),
+            Description: prop.Description,
+            DataType: genericType,
+            IsRequired: !!prop.IsRequired,
+            IsUniqueKey: !!prop.IsPrimaryKey,
+            IsReadOnly: !!prop.IsReadOnly,
+        };
+    }
+    /**
+     * Merge live-discovered fields with static metadata. Live-only fields are
+     * treated as custom — surfaced with whatever properties the live API reports.
+     * Static fields override live fields on matching names (static metadata
+     * reflects the curated MJ schema).
+     */
+    MergeFieldSchemas(staticFields, liveFields) {
+        const staticNames = new Set(staticFields.map(f => f.Name.toLowerCase()));
+        const liveOnly = liveFields.filter(f => !staticNames.has(f.Name.toLowerCase()));
+        return [...staticFields, ...liveOnly];
+    }
+    /**
+     * Resolve an object name to its API path. Prefers the configured APIPath
+     * from IntegrationObject metadata; falls back to `/{ObjectName}` for
+     * runtime-discovered Business Objects.
+     */
+    ResolveObjectPath(integrationID, objectName) {
+        try {
+            const obj = this.GetCachedObject(integrationID, objectName);
+            if (obj.APIPath) {
+                return obj.APIPath.startsWith('/') ? obj.APIPath : `/${obj.APIPath}`;
+            }
+        }
+        catch {
+            // Not in static metadata — this is a runtime-discovered Business Object.
+        }
+        return `/${objectName}`;
+    }
+    /** Derive the URL path segment used by CRUD operations (no leading slash). */
+    NormalizeObjectPath(objectName) {
+        return objectName.startsWith('/') ? objectName.slice(1) : objectName;
+    }
+    // ── Record / watermark helpers ──────────────────────────────────
+    async FetchSingleRecord(auth, objectPath, id) {
+        const url = `${auth.BaseUrl}/${objectPath}/${encodeURIComponent(id)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300)
+            return null;
+        if (response.Body == null || typeof response.Body !== 'object')
+            return null;
+        return response.Body;
+    }
+    ExtractIdFromRecord(body) {
+        const candidates = ['Id', 'ID', 'PartyId', 'UniformId', 'EventId', 'InvoiceId', 'PaymentId'];
+        for (const key of candidates) {
+            const value = body[key];
+            if (value !== undefined && value !== null)
+                return String(value);
+        }
+        return '';
+    }
+    ComputeNewWatermark(records, current) {
+        const candidateKeys = ['UpdatedOn', 'UpdateDate', 'ModifiedOn', 'LastUpdatedAt'];
+        let latest;
+        for (const record of records) {
+            for (const key of candidateKeys) {
+                const value = record.Fields[key];
+                if (typeof value === 'string' && (!latest || value > latest))
+                    latest = value;
+            }
+        }
+        if (!latest)
+            return current ?? undefined;
+        if (current && latest <= current)
+            return current;
+        return latest;
+    }
+    // ── HTTP helpers ────────────────────────────────────────────────
+    async ExecuteFetch(url, method, headers, body, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async BuildRESTResponse(response) {
+        const headers = {};
+        response.headers.forEach((v, k) => { headers[k.toLowerCase()] = v; });
+        const contentType = headers['content-type'] ?? '';
+        let bodyValue;
+        if (contentType.includes('application/json')) {
+            bodyValue = await this.ParseJsonSafely(response);
+        }
+        else {
+            bodyValue = await response.text();
+        }
+        return { Status: response.status, Body: bodyValue, Headers: headers };
+    }
+    async ParseJsonSafely(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    ShouldRetry(status) {
+        return status === 429 || status === 502 || status === 503 || status === 504;
+    }
+    ComputeRetryDelay(response, attempt) {
+        const retryAfter = response.headers.get('retry-after');
+        if (retryAfter) {
+            const seconds = Number.parseInt(retryAfter, 10);
+            if (!Number.isNaN(seconds) && seconds > 0)
+                return seconds * 1000;
+        }
+        return Math.min(Math.pow(2, attempt) * 1000, 15_000);
+    }
+    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));
+    }
+    ExtractServerVersion(headers) {
+        return headers['x-imis-version'] ?? headers['server'] ?? 'iMIS REST API';
+    }
+    IsPagedResult(body) {
+        if (body == null || typeof body !== 'object' || Array.isArray(body))
+            return false;
+        const record = body;
+        return Array.isArray(record['Items']) && ('Offset' in record || 'Limit' in record || 'HasNext' in record);
+    }
+    StripTrailingSlash(url) {
+        return url.endsWith('/') ? url.slice(0, -1) : url;
+    }
+    BuildCRUDError(response, operation, objectName) {
+        const body = response.Body;
+        let detail;
+        if (typeof body === 'string') {
+            detail = body.slice(0, 500);
+        }
+        else if (body && typeof body === 'object') {
+            const asRecord = body;
+            const msg = asRecord['Message'] ?? asRecord['error_description'] ?? asRecord['error'];
+            detail = msg !== undefined ? String(msg) : JSON.stringify(body).slice(0, 500);
+        }
+        else {
+            detail = `HTTP ${response.Status}`;
+        }
+        return {
+            Success: false,
+            ErrorMessage: `iMIS ${operation} failed on ${objectName}: ${detail}`,
+            StatusCode: response.Status,
+        };
+    }
+};
+IMISConnector = __decorate([
+    RegisterClass(BaseIntegrationConnector, 'IMISConnector')
+], IMISConnector);
+export { IMISConnector };
+/** Tree-shaking prevention — import and call from module entry point */
+export function LoadIMISConnector() { }
+//# sourceMappingURL=IMISConnector.js.map