@memberjunction/integration-connectors 5.8.0 → 5.10.0

package/dist/YourMembershipConnector.d.ts

@@ -1,6 +1,7 @@
-import type { UserInfo } from '@memberjunction/core';
+import { type UserInfo } from '@memberjunction/core';
 import type { MJCompanyIntegrationEntity } from '@memberjunction/core-entities';
-import { BaseIntegrationConnector, type ConnectionTestResult, type ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult, type DefaultFieldMapping } from '@memberjunction/integration-engine';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type FetchContext, type FetchBatchResult, type DefaultFieldMapping, type DefaultIntegrationConfig } from '@memberjunction/integration-engine';
+import type { MJIntegrationObjectEntity } from '@memberjunction/core-entities';
 /** Connection configuration parsed from CompanyIntegration.Configuration JSON */
 export interface YMConnectionConfig {
     /** YM client/site identifier (integer) */
@@ -13,6 +14,9 @@ export interface YMConnectionConfig {
 /**
  * Connector for the YourMembership (YM) AMS REST API.
  *
+ * Extends BaseRESTIntegrationConnector to leverage metadata-driven object/field
+ * discovery from IntegrationEngineBase cache and generic pagination handling.
+ *
  * Auth flow:
  *   1. POST /Ams/Authenticate with credentials + ClientID
  *   2. Receive SessionId
@@ -20,13 +24,87 @@ export interface YMConnectionConfig {
  *
  * Configuration JSON: { "ClientID": "25363", "APIKey": "...", "APIPassword": "..." }
  */
-export declare class YourMembershipConnector extends BaseIntegrationConnector {
+export declare class YourMembershipConnector extends BaseRESTIntegrationConnector {
     /** Session cache keyed by ClientID */
     private sessionCache;
+    /** Timestamp of the last API request, used for throttling */
+    private lastRequestTime;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity): 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): string;
+    /**
+     * Overrides base pagination URL building to use YM's expected parameter names:
+     * - PageNumber type: `PageNumber` / `PageSize` (not `page` / `pageSize`)
+     * - Offset type: `OffSet` (not `offset`); no explicit limit param — YM uses
+     *   its own default batch size (~200 records)
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, page: number, offset: number, cursor?: string): string;
+    /**
+     * Overrides base FetchChanges to handle YM-specific edge cases:
+     * - Groups/GroupTypes: nested GroupTypeList response needs custom flattening
+     * - Members: client-side watermark filtering + selective detail enrichment
+     *
+     * The MemberList API returns all members every time (no server-side date filter),
+     * but each record includes a `LastUpdated` field. We pull the full list, filter
+     * to only records changed since the watermark, and only call the expensive
+     * per-member detail endpoint for those changed records.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Filters the full member list to only records changed since the watermark,
+     * then enriches only those changed records via the detail endpoint.
+     * Returns a new watermark based on the latest LastUpdated value seen.
+     */
+    private FetchMembersWithWatermark;
+    /**
+     * Filters records by comparing a date field against a watermark timestamp.
+     * Returns only records where the date field is newer than the watermark,
+     * plus the latest date value seen (to use as the next watermark).
+     */
+    private FilterByWatermark;
+    /** Tests connectivity by authenticating and fetching ClientConfig. */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /** Returns suggested default configuration for YM integration setup. */
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    /** Returns suggested default field mappings for common YM objects to MJ entities. */
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    /**
+     * Fetches Groups or GroupTypes, which have a nested structure:
+     * GroupTypeList → Groups. When objectName is 'GroupTypes', returns just
+     * the type entries. When 'Groups', flattens into individual group records.
+     */
+    private FetchGroups;
+    /** Builds ExternalRecords for GroupType entries only. */
+    private BuildGroupTypeRecords;
+    /** Flattens nested GroupTypeList → Groups into flat group records. */
+    private FlattenGroupRecords;
+    /**
+     * Enriches Members records with full profile data from the detail endpoint.
+     * The list endpoint returns sparse data (name, email); the detail endpoint
+     * returns full address, phone, custom fields, etc.
+     */
+    private EnrichMembersWithDetails;
+    /**
+     * Fetches full detail data for a single member and merges it.
+     * Detail endpoint returns camelCase + nested objects; we normalize to flat PascalCase.
+     */
+    private EnrichSingleMember;
+    /**
+     * Maps the Members detail endpoint response to our flat PascalCase schema.
+     * Detail endpoint returns: { firstName, lastName, emailAddress, primaryAddress: { ... } }
+     * We need:                 { FirstName, LastName, EmailAddr, Phone, Address1, ... }
+     */
+    private NormalizeMemberDetail;
     /**
-     * Parses the Configuration JSON from a CompanyIntegration entity.
+     * Parses credentials from CompanyIntegration.CredentialID (preferred) or
+     * falls back to CompanyIntegration.Configuration JSON for backwards compat.
      */
-    protected ParseConfig(companyIntegration: MJCompanyIntegrationEntity): YMConnectionConfig;
+    protected ParseConfig(companyIntegration: MJCompanyIntegrationEntity, contextUser?: UserInfo): Promise<YMConnectionConfig>;
+    private LoadFromCredential;
+    private ParseConfigJson;
     /** Obtains or reuses a YM session for the given credentials. */
     protected GetSession(config: YMConnectionConfig): Promise<string>;
     /** Creates a new YM session via the Authenticate endpoint. */
@@ -34,43 +112,32 @@ export declare class YourMembershipConnector extends BaseIntegrationConnector {
     /** Invalidates a cached session so the next request re-authenticates. */
     protected InvalidateSession(clientId: string): void;
     /**
-     * Makes a GET request to a YM API endpoint using session auth.
-     * Retries once on 401 (session expiry).
+     * Makes a direct YM API request using the connector's auth and URL conventions.
+     * Used for YM-specific calls (Groups, detail enrichment, TestConnection)
+     * that bypass the base class's metadata-driven flow.
      */
-    protected MakeRequest(config: YMConnectionConfig, endpoint: string, queryParams?: Record<string, string>): Promise<Record<string, unknown>>;
-    private FetchWithSession;
-    private BuildUrl;
+    private MakeYMRequest;
+    /** Executes an HTTP request with a timeout. */
+    private FetchWithTimeout;
+    /** Wraps response.json() with a timeout to prevent indefinite hangs. */
+    private JsonWithTimeout;
+    /** Refreshes session after 401 or timeout, updating headers in-place. */
+    private RefreshSession;
+    /** Checks if an error is a timeout/abort error. */
+    private IsTimeoutError;
+    /** Calculates retry delay from Retry-After header or exponential backoff. */
+    private CalculateRetryDelay;
+    /** Converts a fetch Response + parsed body into a RESTResponse. */
+    private BuildRESTResponse;
+    private Sleep;
+    /** Checks for YM API-level errors in the response envelope. */
     private CheckResponseError;
-    /** Tests connectivity by authenticating and fetching ClientConfig. */
-    TestConnection(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ConnectionTestResult>;
-    /** Returns all known YM object types available for integration. */
-    DiscoverObjects(_companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
-    /** Returns the known field schema for a YM object. */
-    DiscoverFields(_companyIntegration: MJCompanyIntegrationEntity, objectName: string, _contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /** Filters out YM API metadata keys that shouldn't be stored as field data. */
+    private FilterMetadataKeys;
     /**
-     * Fetches a batch of records from a YM API endpoint.
-     *
-     * For paginated endpoints (Members, Events, Certifications), uses
-     * PageSize/PageNumber. The watermark tracks the current page number
-     * for resuming large fetches across batches.
-     *
-     * For non-paginated endpoints (MemberTypes, Memberships, Groups, Products),
-     * fetches all data in one call.
+     * Estimates record count from a raw response body.
+     * Used by ExtractPaginationInfo to determine if more pages exist.
      */
-    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
-    /** Fetches data from a paginated YM endpoint. Watermark = page number. */
-    private FetchPaginated;
-    /** Fetches all data from a non-paginated endpoint in a single request. */
-    private FetchAll;
-    /** Fetches endpoints that return a raw JSON array (e.g., Products). */
-    private FetchRawArray;
-    /**
-     * Fetches Groups, which have a nested structure: GroupTypeList → Groups.
-     * Flattens into individual group records with the GroupType name attached.
-     */
-    private FetchGroups;
-    /** Returns suggested default field mappings for YM objects to MJ entities. */
-    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
-    private BuildRecord;
+    private EstimateRecordCount;
 }
 //# sourceMappingURL=YourMembershipConnector.d.ts.map

package/dist/YourMembershipConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"YourMembershipConnector.d.ts","sourceRoot":"","sources":["../src/YourMembershipConnector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EACH,wBAAwB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,KAAK,mBAAmB,EAC3B,MAAM,oCAAoC,CAAC;AAI5C,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IAC/B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;CACvB;AA+MD;;;;;;;;;GASG;AACH,qBACa,uBAAwB,SAAQ,wBAAwB;IACjE,sCAAsC;IACtC,OAAO,CAAC,YAAY,CAAgC;IAIpD;;OAEG;IACH,SAAS,CAAC,WAAW,CAAC,kBAAkB,EAAE,0BAA0B,GAAG,kBAAkB;IAoBzF,gEAAgE;cAChD,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAQvE,8DAA8D;YAChD,aAAa;IAsC3B,yEAAyE;IACzE,SAAS,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMnD;;;OAGG;cACa,WAAW,CACvB,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAqBrB,gBAAgB;IAO9B,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,kBAAkB;IAS1B,sEAAsE;IACzD,cAAc,CACvB,kBAAkB,EAAE,0BAA0B,EAC9C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAkBhC,mEAAmE;IACtD,eAAe,CACxB,mBAAmB,EAAE,0BAA0B,EAC/C,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,oBAAoB,EAAE,CAAC;IASlC,sDAAsD;IACzC,cAAc,CACvB,mBAAmB,EAAE,0BAA0B,EAC/C,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,QAAQ,GACvB,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAIjC;;;;;;;;;OASG;IACU,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuBvE,0EAA0E;YAC5D,cAAc;IA+B5B,0EAA0E;YAC5D,QAAQ;IAmBtB,uEAAuE;YACzD,aAAa;IAyB3B;;;OAGG;YACW,WAAW;IA4BzB,8EAA8E;IAC9D,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACpB,mBAAmB,EAAE;IAyBxB,OAAO,CAAC,WAAW;CAYtB"}
+{"version":3,"file":"YourMembershipConnector.d.ts","sourceRoot":"","sources":["../src/YourMembershipConnector.ts"],"names":[],"mappings":"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"}