@memberjunction/integration-connectors 0.0.1 → 5.9.0

package/dist/RelationalDBConnector.js

@@ -0,0 +1,221 @@
+import { BaseIntegrationConnector, } from '@memberjunction/integration-engine';
+import sql from 'mssql';
+/**
+ * Abstract base class for connectors that read from relational databases via mssql.
+ * Handles connection management, object/field discovery, and connection testing.
+ * Subclasses must implement FetchChanges to define record extraction logic.
+ */
+export class RelationalDBConnector extends BaseIntegrationConnector {
+    constructor() {
+        super(...arguments);
+        /** Cache of open connection pools keyed by "server|database" */
+        this.poolCache = new Map();
+    }
+    /**
+     * Parses the Configuration JSON on a CompanyIntegration to extract connection details.
+     * @param companyIntegration - The entity containing Configuration JSON
+     * @returns Parsed connection configuration
+     * @throws Error if Configuration is missing or malformed
+     */
+    ParseConnectionConfig(companyIntegration) {
+        const configJson = companyIntegration.Get('Configuration');
+        if (!configJson) {
+            throw new Error('CompanyIntegration.Configuration is null or empty');
+        }
+        const parsed = JSON.parse(configJson);
+        const server = parsed['server'];
+        const database = parsed['database'];
+        const user = parsed['user'];
+        const password = parsed['password'];
+        const schema = parsed['schema'] ?? 'dbo';
+        if (!server || !database || !user || !password) {
+            throw new Error('Configuration JSON must contain server, database, user, and password fields');
+        }
+        return { Server: server, Database: database, User: user, Password: password, Schema: schema };
+    }
+    /**
+     * Opens or reuses a mssql ConnectionPool for the given configuration.
+     * Pools are cached by server+database to avoid redundant connections.
+     * @param config - Connection configuration
+     * @returns An open ConnectionPool
+     */
+    async GetPool(config) {
+        const cacheKey = `${config.Server}|${config.Database}`;
+        const existing = this.poolCache.get(cacheKey);
+        if (existing?.connected) {
+            return existing;
+        }
+        const pool = new sql.ConnectionPool({
+            server: config.Server,
+            database: config.Database,
+            user: config.User,
+            password: config.Password,
+            options: {
+                encrypt: false,
+                trustServerCertificate: true,
+            },
+        });
+        await pool.connect();
+        this.poolCache.set(cacheKey, pool);
+        return pool;
+    }
+    /**
+     * Tests connectivity to the source database by running SELECT 1.
+     * @param companyIntegration - The company integration with connection configuration
+     * @param _contextUser - User context for authorization
+     * @returns Connection test result with success/failure and message
+     */
+    async TestConnection(companyIntegration, _contextUser) {
+        try {
+            const config = this.ParseConnectionConfig(companyIntegration);
+            const pool = await this.GetPool(config);
+            const result = await pool.request().query('SELECT @@VERSION AS version');
+            const version = result.recordset[0]?.version ?? 'Unknown';
+            return {
+                Success: true,
+                Message: `Connected to ${config.Database} on ${config.Server}`,
+                ServerVersion: version.split('\n')[0],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { Success: false, Message: `Connection failed: ${message}` };
+        }
+    }
+    /**
+     * Discovers all user tables in the source database via INFORMATION_SCHEMA.
+     * @param companyIntegration - The company integration with connection configuration
+     * @param _contextUser - User context for authorization
+     * @returns Array of object schemas for each table found
+     */
+    async DiscoverObjects(companyIntegration, _contextUser) {
+        const config = this.ParseConnectionConfig(companyIntegration);
+        const pool = await this.GetPool(config);
+        const result = await pool.request()
+            .input('schemaName', sql.NVarChar, config.Schema)
+            .query(`SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE' AND TABLE_SCHEMA = @schemaName ORDER BY TABLE_NAME`);
+        return result.recordset.map((row) => ({
+            Name: row.TABLE_NAME,
+            Label: row.TABLE_NAME,
+            SupportsIncrementalSync: true,
+            SupportsWrite: false,
+        }));
+    }
+    /**
+     * Discovers columns on a specific table via INFORMATION_SCHEMA.COLUMNS.
+     * @param companyIntegration - The company integration with connection configuration
+     * @param objectName - Table name to inspect
+     * @param _contextUser - User context for authorization
+     * @returns Array of field schemas for the specified table
+     */
+    async DiscoverFields(companyIntegration, objectName, _contextUser) {
+        const config = this.ParseConnectionConfig(companyIntegration);
+        const pool = await this.GetPool(config);
+        const result = await pool
+            .request()
+            .input('tableName', sql.NVarChar, objectName)
+            .input('schemaName', sql.NVarChar, config.Schema)
+            .query(`SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMNPROPERTY(OBJECT_ID(TABLE_SCHEMA + '.' + TABLE_NAME), COLUMN_NAME, 'IsIdentity') AS IS_IDENTITY
+                 FROM INFORMATION_SCHEMA.COLUMNS
+                 WHERE TABLE_NAME = @tableName AND TABLE_SCHEMA = @schemaName
+                 ORDER BY ORDINAL_POSITION`);
+        return result.recordset.map((row) => this.mapColumnToFieldSchema(row));
+    }
+    /**
+     * Converts a row from INFORMATION_SCHEMA.COLUMNS to an ExternalFieldSchema.
+     * @param row - Column metadata row
+     * @returns Mapped field schema
+     */
+    mapColumnToFieldSchema(row) {
+        return {
+            Name: row.COLUMN_NAME,
+            Label: row.COLUMN_NAME,
+            DataType: row.DATA_TYPE,
+            IsRequired: row.IS_NULLABLE === 'NO',
+            IsUniqueKey: false,
+            IsReadOnly: row.IS_IDENTITY === 1,
+        };
+    }
+    /**
+     * Builds an ExternalRecord from a SQL result row.
+     * @param row - Raw database row
+     * @param idField - Column name to use as ExternalID
+     * @param objectType - Object type name for the record
+     * @param modifiedAtField - Column name for the modification timestamp
+     * @param deletedField - Column name for the deleted flag (optional)
+     * @returns An ExternalRecord
+     */
+    BuildExternalRecord(row, idField, objectType, modifiedAtField, deletedField) {
+        const modifiedRaw = row[modifiedAtField];
+        const modifiedAt = modifiedRaw instanceof Date ? modifiedRaw : undefined;
+        const isDeleted = deletedField ? Boolean(row[deletedField]) : undefined;
+        return {
+            ExternalID: String(row[idField]),
+            ObjectType: objectType,
+            Fields: { ...row },
+            ModifiedAt: modifiedAt,
+            IsDeleted: isDeleted,
+        };
+    }
+    /**
+     * Fetches changed records from a table, ordered by a modification timestamp column.
+     * Applies watermark filtering and batch size limiting.
+     * @param ctx - Fetch context with integration, object, watermark, and batch details
+     * @param idField - Column name for the primary key
+     * @param modifiedAtField - Column name for the modification timestamp
+     * @param deletedField - Column name for the deleted flag (optional)
+     * @returns Batch of external records with pagination info
+     */
+    async FetchChangesFromTable(ctx, idField, modifiedAtField, deletedField) {
+        const config = this.ParseConnectionConfig(ctx.CompanyIntegration);
+        const pool = await this.GetPool(config);
+        const request = pool.request();
+        let whereClause = '';
+        if (ctx.WatermarkValue) {
+            whereClause = `WHERE [${modifiedAtField}] > CAST(@watermark AS datetimeoffset(7))`;
+            request.input('watermark', sql.NVarChar, ctx.WatermarkValue);
+        }
+        // Fetch one extra to detect HasMore
+        const fetchCount = ctx.BatchSize + 1;
+        request.input('fetchCount', sql.Int, fetchCount);
+        // Include full-precision timestamp (datetimeoffset has 7 decimal places, JS Date only has 3)
+        // to avoid sub-millisecond precision loss in watermark comparisons
+        const rawTsCol = `CONVERT(varchar(50), [${modifiedAtField}], 126) AS [__mj_raw_ts]`;
+        const query = `SELECT TOP (@fetchCount) *, ${rawTsCol} FROM [${config.Schema}].[${ctx.ObjectName}] ${whereClause} ORDER BY [${modifiedAtField}], [${idField}]`;
+        const result = await request.query(query);
+        const hasMore = result.recordset.length > ctx.BatchSize;
+        const rows = hasMore ? result.recordset.slice(0, ctx.BatchSize) : result.recordset;
+        const newWatermark = this.extractRawWatermark(rows);
+        // Remove internal column before building records
+        for (const row of rows) {
+            delete row['__mj_raw_ts'];
+        }
+        const records = rows.map((row) => this.BuildExternalRecord(row, idField, ctx.ObjectName, modifiedAtField, deletedField));
+        return { Records: records, HasMore: hasMore, NewWatermarkValue: newWatermark };
+    }
+    /**
+     * Extracts the full-precision watermark string from the last row's __mj_raw_ts column.
+     * Uses CONVERT(varchar, ..., 126) output which preserves datetimeoffset(7) precision,
+     * avoiding the sub-millisecond truncation that JavaScript Date introduces.
+     * @param rows - Array of database rows containing __mj_raw_ts
+     * @returns Full-precision datetimeoffset string, or undefined
+     */
+    extractRawWatermark(rows) {
+        if (rows.length === 0)
+            return undefined;
+        const rawTs = rows[rows.length - 1]['__mj_raw_ts'];
+        return rawTs != null ? String(rawTs) : undefined;
+    }
+    /**
+     * Closes all cached connection pools. Call during cleanup/shutdown.
+     */
+    async CloseAllPools() {
+        for (const pool of this.poolCache.values()) {
+            if (pool.connected) {
+                await pool.close();
+            }
+        }
+        this.poolCache.clear();
+    }
+}
+//# sourceMappingURL=RelationalDBConnector.js.map

package/dist/RelationalDBConnector.js.map

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

package/dist/SalesforceConnector.d.ts

@@ -0,0 +1,28 @@
+import { type FetchContext, type FetchBatchResult, type DefaultFieldMapping } from '@memberjunction/integration-engine';
+import { RelationalDBConnector } from './RelationalDBConnector.js';
+/**
+ * Connector for Salesforce CRM data, backed by the mock_data database (sf schema).
+ * Reads from sf.Contact, sf.Account, and sf.Opportunity tables.
+ * Provides default field mappings for Contacts and Accounts to MJ entities.
+ */
+export declare class SalesforceConnector extends RelationalDBConnector {
+    /**
+     * Fetches a batch of changed records from the specified Salesforce object table.
+     * Uses LastModifiedDate for watermark-based incremental sync.
+     * @param ctx - Fetch context with integration, object, watermark, and batch details
+     * @returns Batch of Salesforce records with pagination info
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Returns suggested default field mappings for known Salesforce objects to MJ entities.
+     * @param objectName - Salesforce object name (e.g., "Contact")
+     * @param _entityName - Target MJ entity name (e.g., "Contacts")
+     * @returns Array of default field mappings
+     */
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    /** Default field mappings: sf_Contact -> Contacts */
+    private getContactMappings;
+    /** Default field mappings: sf_Account -> Companies */
+    private getAccountMappings;
+}
+//# sourceMappingURL=SalesforceConnector.d.ts.map

package/dist/SalesforceConnector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SalesforceConnector.d.ts","sourceRoot":"","sources":["../src/SalesforceConnector.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EAC3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AASnE;;;;GAIG;AACH,qBACa,mBAAoB,SAAQ,qBAAqB;IAC1D;;;;;OAKG;IACU,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIvE;;;;;OAKG;IACa,uBAAuB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACpB,mBAAmB,EAAE;IAWxB,qDAAqD;IACrD,OAAO,CAAC,kBAAkB;IAW1B,sDAAsD;IACtD,OAAO,CAAC,kBAAkB;CAS7B"}

package/dist/SalesforceConnector.js

@@ -0,0 +1,73 @@
+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 { BaseIntegrationConnector, } from '@memberjunction/integration-engine';
+import { RelationalDBConnector } from './RelationalDBConnector.js';
+/** Primary key column used across all Salesforce mock tables */
+const SF_ID_FIELD = 'Id';
+/** Modification timestamp column used across Salesforce mock tables */
+const SF_MODIFIED_FIELD = 'LastModifiedDate';
+/** Soft-delete flag column used across all Salesforce mock tables */
+const SF_DELETED_FIELD = 'IsDeleted';
+/**
+ * Connector for Salesforce CRM data, backed by the mock_data database (sf schema).
+ * Reads from sf.Contact, sf.Account, and sf.Opportunity tables.
+ * Provides default field mappings for Contacts and Accounts to MJ entities.
+ */
+let SalesforceConnector = class SalesforceConnector extends RelationalDBConnector {
+    /**
+     * Fetches a batch of changed records from the specified Salesforce object table.
+     * Uses LastModifiedDate for watermark-based incremental sync.
+     * @param ctx - Fetch context with integration, object, watermark, and batch details
+     * @returns Batch of Salesforce records with pagination info
+     */
+    async FetchChanges(ctx) {
+        return this.FetchChangesFromTable(ctx, SF_ID_FIELD, SF_MODIFIED_FIELD, SF_DELETED_FIELD);
+    }
+    /**
+     * Returns suggested default field mappings for known Salesforce objects to MJ entities.
+     * @param objectName - Salesforce object name (e.g., "Contact")
+     * @param _entityName - Target MJ entity name (e.g., "Contacts")
+     * @returns Array of default field mappings
+     */
+    GetDefaultFieldMappings(objectName, _entityName) {
+        switch (objectName) {
+            case 'Contact':
+                return this.getContactMappings();
+            case 'Account':
+                return this.getAccountMappings();
+            default:
+                return [];
+        }
+    }
+    /** Default field mappings: sf_Contact -> Contacts */
+    getContactMappings() {
+        return [
+            { SourceFieldName: 'Email', DestinationFieldName: 'Email', IsKeyField: true },
+            { SourceFieldName: 'FirstName', DestinationFieldName: 'FirstName' },
+            { SourceFieldName: 'LastName', DestinationFieldName: 'LastName' },
+            { SourceFieldName: 'Phone', DestinationFieldName: 'Phone' },
+            { SourceFieldName: 'Title', DestinationFieldName: 'Title' },
+            { SourceFieldName: 'Department', DestinationFieldName: 'Department' },
+        ];
+    }
+    /** Default field mappings: sf_Account -> Companies */
+    getAccountMappings() {
+        return [
+            { SourceFieldName: 'Name', DestinationFieldName: 'Name', IsKeyField: true },
+            { SourceFieldName: 'Industry', DestinationFieldName: 'Industry' },
+            { SourceFieldName: 'BillingCity', DestinationFieldName: 'City' },
+            { SourceFieldName: 'BillingState', DestinationFieldName: 'State' },
+            { SourceFieldName: 'Phone', DestinationFieldName: 'Phone' },
+        ];
+    }
+};
+SalesforceConnector = __decorate([
+    RegisterClass(BaseIntegrationConnector, 'SalesforceConnector')
+], SalesforceConnector);
+export { SalesforceConnector };
+//# sourceMappingURL=SalesforceConnector.js.map

package/dist/SalesforceConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SalesforceConnector.js","sourceRoot":"","sources":["../src/SalesforceConnector.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACH,wBAAwB,GAI3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,gEAAgE;AAChE,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,uEAAuE;AACvE,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAC7C,qEAAqE;AACrE,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAErC;;;;GAIG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAoB,SAAQ,qBAAqB;IAC1D;;;;;OAKG;IACI,KAAK,CAAC,YAAY,CAAC,GAAiB;QACvC,OAAO,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC7F,CAAC;IAED;;;;;OAKG;IACa,uBAAuB,CACnC,UAAkB,EAClB,WAAmB;QAEnB,QAAQ,UAAU,EAAE,CAAC;YACjB,KAAK,SAAS;gBACV,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACrC,KAAK,SAAS;gBACV,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACrC;gBACI,OAAO,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;IAED,qDAAqD;IAC7C,kBAAkB;QACtB,OAAO;YACH,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE;YAC7E,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB,EAAE,WAAW,EAAE;YACnE,EAAE,eAAe,EAAE,UAAU,EAAE,oBAAoB,EAAE,UAAU,EAAE;YACjE,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE;YAC3D,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE;YAC3D,EAAE,eAAe,EAAE,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE;SACxE,CAAC;IACN,CAAC;IAED,sDAAsD;IAC9C,kBAAkB;QACtB,OAAO;YACH,EAAE,eAAe,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;YAC3E,EAAE,eAAe,EAAE,UAAU,EAAE,oBAAoB,EAAE,UAAU,EAAE;YACjE,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,EAAE;YAChE,EAAE,eAAe,EAAE,cAAc,EAAE,oBAAoB,EAAE,OAAO,EAAE;YAClE,EAAE,eAAe,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE;SAC9D,CAAC;IACN,CAAC;CACJ,CAAA;AArDY,mBAAmB;IAD/B,aAAa,CAAC,wBAAwB,EAAE,qBAAqB,CAAC;GAClD,mBAAmB,CAqD/B"}

package/dist/YourMembershipConnector.d.ts

@@ -0,0 +1,143 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity } from '@memberjunction/core-entities';
+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) */
+    ClientID: string;
+    /** YM API key (used as UserName for session auth) */
+    APIKey: string;
+    /** YM API password (used as Password for session auth) */
+    APIPassword: string;
+}
+/**
+ * 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
+ *   3. Pass SessionId as X-SS-ID header on all data requests
+ *
+ * Configuration JSON: { "ClientID": "25363", "APIKey": "...", "APIPassword": "..." }
+ */
+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 credentials from CompanyIntegration.CredentialID (preferred) or
+     * falls back to CompanyIntegration.Configuration JSON for backwards compat.
+     */
+    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. */
+    private CreateSession;
+    /** Invalidates a cached session so the next request re-authenticates. */
+    protected InvalidateSession(clientId: string): void;
+    /**
+     * 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.
+     */
+    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;
+    /** Filters out YM API metadata keys that shouldn't be stored as field data. */
+    private FilterMetadataKeys;
+    /**
+     * Estimates record count from a raw response body.
+     * Used by ExtractPaginationInfo to determine if more pages exist.
+     */
+    private EstimateRecordCount;
+}
+//# sourceMappingURL=YourMembershipConnector.d.ts.map

package/dist/YourMembershipConnector.d.ts.map

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