@memberjunction/integration-connectors 5.35.0 → 5.37.0

package/dist/IMISConnector.d.ts

@@ -0,0 +1,155 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type FetchContext, type FetchBatchResult, type ExternalObjectSchema, type ExternalFieldSchema, type DefaultFieldMapping, type DefaultIntegrationConfig, type CRUDResult, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type GetRecordContext, type ExternalRecord } from '@memberjunction/integration-engine';
+/**
+ * iMIS REST API connection configuration. Supports the OAuth 2.0 Password Grant
+ * flow (recommended for server-to-server) and the optional SSO refresh-token
+ * flow (when ClientId + ClientSecret + RefreshToken are supplied).
+ */
+export interface IMISConnectionConfig {
+    /** Full base URL to the customer's iMIS API (no trailing slash) */
+    BaseUrl: string;
+    /** API username (must hold the iMIS RemoteService role) for Password Grant */
+    Username: string;
+    /** API password for Password Grant */
+    Password: string;
+    /** Optional OAuth SSO Client ID (only used when switching to SSO refresh-token flow) */
+    ClientId?: string;
+    /** Optional OAuth SSO Client Secret */
+    ClientSecret?: string;
+    /** Optional SSO refresh token */
+    RefreshToken?: string;
+    /** Maximum retries for rate-limited or failed requests. Default: 3 */
+    MaxRetries?: number;
+    /** HTTP request timeout in milliseconds. Default: 60000 */
+    RequestTimeoutMs?: number;
+    /** Minimum milliseconds between API requests. Default: 200 */
+    MinRequestIntervalMs?: number;
+}
+/**
+ * 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:<iso-date> 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
+ */
+export declare class IMISConnector extends BaseRESTIntegrationConnector {
+    private authState;
+    private lastRequestTime;
+    /** Current watermark for the in-flight FetchChanges — used by AppendDefaultQueryParams */
+    private currentWatermark;
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    get SupportsSearch(): boolean;
+    get SupportsListing(): boolean;
+    get IntegrationName(): string;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    protected ExtractPaginationInfo(rawBody: unknown, paginationType: PaginationType, currentPage: number, currentOffset: number, pageSize: number): PaginationState;
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * iMIS pagination uses `Offset` and `Limit` query parameters (capitalized).
+     * Override the base class helper to match iMIS's param names.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, page: number, offset: number, cursor?: string, effectivePageSize?: number): string;
+    /**
+     * 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.
+     */
+    protected AppendDefaultQueryParams(url: string, obj: MJIntegrationObjectEntity): string;
+    /**
+     * Test the connection by authenticating and hitting the /Party list endpoint
+     * with a minimal page size. Confirms both auth + data-plane connectivity.
+     */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * 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.
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * 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).
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Override FetchChanges to stash the current watermark so AppendDefaultQueryParams
+     * can inject the UpdatedOn filter on list requests.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    /**
+     * 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.
+     */
+    private GetAuth;
+    private IsConfig;
+    private IsTokenValid;
+    private AcquireToken;
+    /**
+     * iMIS issues tokens at the scheduler path, not under /api/. Strip /api[/]
+     * from the BaseUrl when constructing the token endpoint.
+     */
+    private ResolveTokenEndpoint;
+    private BuildTokenRequestBody;
+    private ParseConfig;
+    private ParseConfigFromCredential;
+    private ExtractConfig;
+    private DiscoverBusinessObjects;
+    private DiscoverFieldsFromLiveAPI;
+    private PropertyDefinitionToFieldSchema;
+    /**
+     * 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).
+     */
+    private MergeFieldSchemas;
+    /**
+     * Resolve an object name to its API path. Prefers the configured APIPath
+     * from IntegrationObject metadata; falls back to `/{ObjectName}` for
+     * runtime-discovered Business Objects.
+     */
+    private ResolveObjectPath;
+    /** Derive the URL path segment used by CRUD operations (no leading slash). */
+    private NormalizeObjectPath;
+    private FetchSingleRecord;
+    private ExtractIdFromRecord;
+    private ComputeNewWatermark;
+    private ExecuteFetch;
+    private BuildRESTResponse;
+    private ParseJsonSafely;
+    private ShouldRetry;
+    private ComputeRetryDelay;
+    private Throttle;
+    private Sleep;
+    private ExtractServerVersion;
+    private IsPagedResult;
+    private StripTrailingSlash;
+    private BuildCRUDError;
+}
+/** Tree-shaking prevention — import and call from module entry point */
+export declare function LoadIMISConnector(): void;
+//# sourceMappingURL=IMISConnector.d.ts.map

package/dist/IMISConnector.d.ts.map

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