@memberjunction/connector-salesforce 1.0.0

package/dist/SalesforceConnector.js

@@ -0,0 +1,1865 @@
+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;
+};
+var SalesforceConnector_1;
+import jwt from 'jsonwebtoken';
+import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
+// ─── Constants ────────────────────────────────────────────────────────
+const DEFAULT_API_VERSION = '61.0';
+const DEFAULT_MAX_RETRIES = 5;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+const DEFAULT_MIN_REQUEST_INTERVAL_MS = 100;
+const DEFAULT_BATCH_SIZE = 2000;
+/** Token lifetime — SF tokens last ~2 hours; refresh at 80% (96 min) */
+const TOKEN_LIFETIME_MS = 2 * 60 * 60 * 1000;
+const TOKEN_REFRESH_THRESHOLD = 0.8;
+/** Governor limit thresholds */
+const GOVERNOR_THROTTLE_THRESHOLD = 0.8;
+const GOVERNOR_PAUSE_THRESHOLD = 0.95;
+/** SF compound field types to skip during discovery */
+const COMPOUND_FIELD_TYPES = new Set(['address', 'location']);
+/** SF system fields that are always read-only */
+const SYSTEM_READ_ONLY_FIELDS = new Set([
+    'Id', 'CreatedDate', 'CreatedById', 'LastModifiedDate', 'LastModifiedById',
+    'SystemModstamp', 'IsDeleted', 'LastActivityDate', 'LastViewedDate',
+    'LastReferencedDate', 'MasterRecordId',
+]);
+/** Fields always included in SOQL SELECT */
+const REQUIRED_SOQL_FIELDS = ['Id', 'SystemModstamp', 'IsDeleted', 'LastModifiedById'];
+/**
+ * Objects that SF exposes through the main `/sobjects/` endpoint but that only
+ * function correctly through the Tooling API. The Data API describes them as
+ * `queryable=true` so they'd otherwise land in the picker, but syncing them
+ * produces one or more of: duplicate-key violations (pagination returns the
+ * same record across pages), sentinel `000000000000000AAA` IDs, or
+ * `MALFORMED_QUERY` on fields like `Metadata`/`FullName` that SF permits only
+ * one-row-at-a-time in Tooling queries.
+ *
+ * Observed causing errors in production syncs; blacklisting here eliminates
+ * ~960 errors per cold apply and ~10 per incremental without any value loss
+ * (these are metadata/telemetry tables, not business data).
+ */
+const TOOLING_API_DENYLIST = new Set([
+    'EntityDefinition',
+    'DataType',
+    'AuraDefinitionInfo',
+    'AuraDefinitionBundleInfo',
+    'FormulaFunction',
+    'AppDefinition',
+    'UserSetupEntityAccess',
+    'PlatformEventUsageMetric',
+    'EventBusSubscriber',
+    'ApexClass',
+    'ApexPage',
+    'ApexTrigger',
+    'ApexComponent',
+    'Publisher',
+    'ExternalString',
+    'CustomHttpHeader',
+    'FormulaFunctionCategory',
+]);
+// ─── SalesforceConnector ──────────────────────────────────────────────
+/**
+ * Production Salesforce CRM connector using the Salesforce REST API v61.0.
+ *
+ * Supports:
+ * - OAuth 2.0 JWT Bearer Token authentication (RS256)
+ * - Live schema discovery via SF Describe API
+ * - SOQL-based incremental sync with SystemModstamp watermarks
+ * - Full CRUD (Create, Update, Delete) via SObject REST API
+ * - SOQL/SOSL search support
+ * - Comprehensive SF error code handling and governor limit management
+ *
+ * Extends BaseRESTIntegrationConnector but overrides FetchChanges entirely
+ * because Salesforce uses SOQL queries instead of standard REST list endpoints.
+ */
+let SalesforceConnector = class SalesforceConnector extends BaseRESTIntegrationConnector {
+    constructor() {
+        super(...arguments);
+        // ── Token cache ─────────────────────────────────────────────────
+        this.cachedAuth = null;
+        this.tokenObtainedAt = 0;
+        // ── Rate limit / governor tracking ──────────────────────────────
+        this.lastRequestTime = 0;
+        this.governorState = { CurrentUsage: 0, DailyLimit: 15000, LastUpdated: 0 };
+        // ── Config ──────────────────────────────────────────────────────
+        this._config = null;
+    }
+    static { SalesforceConnector_1 = this; }
+    get effectiveMaxRetries() { return this._config?.MaxRetries ?? DEFAULT_MAX_RETRIES; }
+    get effectiveRequestTimeoutMs() { return this._config?.RequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS; }
+    get effectiveMinRequestIntervalMs() { return this._config?.MinRequestIntervalMs ?? DEFAULT_MIN_REQUEST_INTERVAL_MS; }
+    get effectiveBatchSize() { return this._config?.DefaultBatchSize ?? DEFAULT_BATCH_SIZE; }
+    // ─── Capability Getters ──────────────────────────────────────────
+    get SupportsCreate() { return true; }
+    get SupportsUpdate() { return true; }
+    get SupportsDelete() { return true; }
+    get SupportsSearch() { return true; }
+    get IntegrationName() { return 'Salesforce'; }
+    /**
+     * CORRECTION (IMPROVE build): affirm AUTHORITATIVE discovery. The global describe
+     * (`/sobjects/`) returns the COMPLETE credentialed gamut of queryable objects this
+     * org exposes (standard + custom `__c`), and `DoIntrospectSchema` describes that whole
+     * set. So an object/field absent from a comprehensive refresh genuinely means the
+     * source dropped it, and the engine's refresh path may safely DEACTIVATE it
+     * (`Status='Disabled'` — reversible; it flips back to Active if the object reappears on
+     * a later discovery). This is what makes comprehensive-refresh deactivation correct
+     * for Salesforce rather than wrongly wiping Declared metadata.
+     */
+    get DiscoveryIsAuthoritative() { return true; }
+    // ─── Action Metadata ─────────────────────────────────────────────
+    /**
+     * Action-generation hint set. CORRECTION (IMPROVE build): this used to return
+     * a baked famous-subset catalog (~9 objects hardcoded in this file). That is a
+     * `catalog-in-code` defect — it froze the object universe to a famous subset.
+     *
+     * It now derives the hint set ENTIRELY from the runtime-cached IntegrationObject /
+     * IntegrationObjectField metadata for the Salesforce integration — the FULL
+     * Declared (credential-free catalog) + Discovered (live `DiscoverObjects` describe,
+     * custom `__c` included) gamut. There is NO baked catalog. If the metadata cache is
+     * not yet populated (e.g. action generation runs before the integration is seeded),
+     * it returns an empty array — the connector NEVER falls back to a hardcoded list.
+     *
+     * The per-tenant object UNIVERSE for sync comes exclusively from `DiscoverObjects`
+     * (live global describe / sObjects endpoint); this method only shapes the cached
+     * catalog into the ActionMetadataGenerator's hint structure.
+     */
+    GetIntegrationObjects() {
+        const engine = IntegrationEngineBase.Instance;
+        const integration = engine.Integrations.find(i => i.Name === this.IntegrationName);
+        if (!integration)
+            return [];
+        const objects = engine.GetActiveIntegrationObjects(integration.ID);
+        return objects.map(obj => {
+            const fields = engine.GetIntegrationObjectFields(obj.ID);
+            return {
+                Name: obj.Name,
+                DisplayName: obj.DisplayName ?? obj.Name,
+                Description: obj.Description ?? undefined,
+                SupportsWrite: obj.SupportsWrite,
+                Fields: fields.map(f => ({
+                    Name: f.Name,
+                    DisplayName: f.DisplayName ?? f.Name,
+                    Description: f.Description ?? undefined,
+                    Type: f.Type ?? 'string',
+                    IsRequired: f.IsRequired,
+                    IsReadOnly: f.IsReadOnly,
+                    IsPrimaryKey: f.IsPrimaryKey,
+                })),
+            };
+        });
+    }
+    GetActionGeneratorConfig() {
+        const config = super.GetActionGeneratorConfig();
+        if (!config)
+            return null;
+        config.IconClass = 'fa-brands fa-salesforce';
+        return config;
+    }
+    // ─── TestConnection ──────────────────────────────────────────────
+    async TestConnection(companyIntegration, contextUser) {
+        try {
+            const auth = await this.Authenticate(companyIntegration, contextUser);
+            const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/`;
+            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: `Successfully connected to Salesforce (${auth.InstanceUrl})`,
+                    ServerVersion: `Salesforce REST API v${auth.ApiVersion}`,
+                };
+            }
+            return {
+                Success: false,
+                Message: `Salesforce API returned ${response.Status}: ${this.PreviewBody(response.Body)}`,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { Success: false, Message: `Connection failed: ${message}` };
+        }
+    }
+    // ─── Discovery (Live from SF Describe API) ───────────────────────
+    /**
+     * Discovers available objects by calling the SF SObjects API.
+     * Returns user-relevant queryable objects: standard CRM objects + custom
+     * (__c). Filters out audit/system noise (~1,866 → ~150-300 typically).
+     * Set MJ_SALESFORCE_INCLUDE_ALL_SOBJECTS=true to bypass the filter and
+     * return the full catalog (useful for debugging or unusual integrations).
+     */
+    async DiscoverObjects(companyIntegration, contextUser) {
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/sobjects/`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const sobjects = body.sobjects ?? [];
+        const includeAll = process.env.MJ_SALESFORCE_INCLUDE_ALL_SOBJECTS === 'true';
+        const filtered = sobjects.filter(obj => {
+            if (!obj.queryable)
+                return false;
+            if (TOOLING_API_DENYLIST.has(obj.name))
+                return false;
+            if (includeAll)
+                return true;
+            return this.isUserRelevantSObject(obj);
+        });
+        if (!includeAll) {
+            const removed = sobjects.length - filtered.length;
+            console.log(`[Salesforce] DiscoverObjects: filtered ${sobjects.length} → ${filtered.length} (excluded ${removed} system/audit objects; set MJ_SALESFORCE_INCLUDE_ALL_SOBJECTS=true to bypass)`);
+        }
+        return filtered.map(obj => ({
+            Name: obj.name,
+            Label: obj.label,
+            Description: obj.custom ? `Custom object: ${obj.label}` : undefined,
+            SupportsIncrementalSync: true,
+            SupportsWrite: obj.createable || obj.updateable,
+        }));
+    }
+    /**
+     * Heuristic for "user-relevant" SF object: customer data (custom objects
+     * with __c suffix) OR createable standard CRM objects, excluding audit
+     * tables, system metadata, and managed-package telemetry.
+     *
+     * Standard SF orgs return ~1,866 sobjects from describeGlobal — most are
+     * audit/internal noise that don't represent business data the user wants
+     * to sync into MJ. This drops them to ~150-300.
+     */
+    isUserRelevantSObject(obj) {
+        // Custom objects always pass — they're customer-defined data
+        if (obj.custom)
+            return true;
+        const name = obj.name;
+        // STRICT exclusions only. Don't filter anything that could possibly
+        // hold customer data. Each exclusion below is a category SF defines
+        // as pure audit/internal/metadata with no customer-meaningful rows:
+        //
+        //   *ChangeEvent: CDC stream, transient, replicated by replication API
+        //   *Feed:        Chatter feed entries (separate "Feed" sync if wanted)
+        //   *History:     audit tables — every value-change is one row
+        //   *FieldHistory: same as *History but per-field tracking
+        //   *Share:       SF row-level access control entries (security metadata)
+        //   *OwnerSharingRule / *CriteriaBasedSharingRule: security rules
+        //   *PermissionSet*: profile/permission internals
+        //
+        // Things we used to exclude that we now LET THROUGH because they CAN
+        // be customer data: EmailMessage (email log), CaseComment / FeedComment
+        // (customer interactions), EntitySubscription (notification subs),
+        // Vote (idea/feedback), Tag (content tagging), Solution (knowledge),
+        // ProcessInstance (workflow approvals), Domain (tenant config).
+        if (/(?:ChangeEvent|Feed|History|FieldHistory|Share|OwnerSharingRule|CriteriaBasedSharingRule)$/.test(name)) {
+            return false;
+        }
+        // SF tooling/setup metadata: Apex code, permissions, setup audit, login
+        // history, async job framework, sandbox/cron internals, network/site
+        // metadata, theme/branding, package licenses. None of these are
+        // business data the integration should sync.
+        if (/^(Apex|Permission|Setup|Login|Async|Sandbox|Auth|Network|Stamp|Site|FlowDefinition|FlowInterview|FlowVariableView|EventLog|CronTrigger|StreamingChannel|InstalledMobileApp|UserPackageLicense|PackageLicense|Theme)/.test(name)) {
+            return false;
+        }
+        // Specific system catalog objects — schema-of-the-schema metadata,
+        // not customer data. These are readable but represent SF's own
+        // structural definitions, never user-entered records.
+        if (/^(EntityDefinition|FieldDefinition|EntityParticle|RelationshipInfo|RelationshipDomain|StandardAction|UserAppMenuItem|UserListView|UserPreference|UserShare|GroupMember|FiscalYearSettings|Period|RecordType|BusinessProcess|PicklistValueInfo)$/.test(name)) {
+            return false;
+        }
+        // NOTE: we intentionally do NOT exclude `!obj.createable`. Many SF
+        // objects are flagged non-createable because they're auto-populated
+        // by SF (rollups, attachment-link junctions, history-style records)
+        // but they DO carry real customer data we want to sync. The
+        // targeted exclusions above already cover the audit/security/CDC
+        // categories that have no business value.
+        return true;
+    }
+    /**
+     * Discovers fields on a specific SF object via the Describe API.
+     * Skips compound fields (address, location) — their component fields are included individually.
+     */
+    async DiscoverFields(companyIntegration, objectName, contextUser) {
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/sobjects/${objectName}/describe`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const fields = body.fields ?? [];
+        return fields
+            .filter(f => !COMPOUND_FIELD_TYPES.has(f.type))
+            .map(f => this.MapSFFieldToSchema(f));
+    }
+    /**
+     * Full schema introspection — builds object graph with relationships.
+     *
+     * If `options.ObjectNames` is provided, only those objects are described
+     * (fast path for user-selected subsets). Without a filter, every
+     * queryable sobject is described — ~70s even with parallelism on a
+     * large org — and the result is cached per-org for 5 minutes so
+     * back-to-back resolver calls don't re-describe.
+     *
+     * Filtered calls bypass the cache on purpose: the subset is typically
+     * small and cheap, and the full-schema cache would shadow newer results
+     * if a user selects a previously-unknown object.
+     */
+    async IntrospectSchema(companyIntegration, contextUser, options) {
+        const filtered = options?.ObjectNames && options.ObjectNames.length > 0;
+        if (filtered) {
+            return this.DoIntrospectSchema(companyIntegration, contextUser, options);
+        }
+        // Dedupe back-to-back introspection requests from the same org.
+        // Three separate resolvers call IntrospectSchema; without this, the
+        // UI's "discover then apply" flow re-describes every object twice.
+        const cacheKey = companyIntegration.ID;
+        const cached = SalesforceConnector_1.introspectCache.get(cacheKey);
+        const now = Date.now();
+        if (cached && cached.expiresAt > now) {
+            const remainingSec = Math.round((cached.expiresAt - now) / 1000);
+            console.log(`[Salesforce] IntrospectSchema: reusing in-flight/cached result (${remainingSec}s TTL remaining)`);
+            return cached.promise;
+        }
+        const promise = this.DoIntrospectSchema(companyIntegration, contextUser);
+        SalesforceConnector_1.introspectCache.set(cacheKey, {
+            promise,
+            expiresAt: now + SalesforceConnector_1.INTROSPECT_CACHE_TTL_MS,
+        });
+        // If the run fails, evict so the next request can retry
+        promise.catch(() => SalesforceConnector_1.introspectCache.delete(cacheKey));
+        return promise;
+    }
+    async DoIntrospectSchema(companyIntegration, contextUser, options) {
+        const allObjects = await this.DiscoverObjects(companyIntegration, contextUser);
+        const wanted = options?.ObjectNames && options.ObjectNames.length > 0
+            ? new Set(options.ObjectNames)
+            : null;
+        const objects = wanted ? allObjects.filter(o => wanted.has(o.Name)) : allObjects;
+        const total = objects.length;
+        const startMs = Date.now();
+        const CONCURRENCY = 8;
+        console.log(`[Salesforce] IntrospectSchema: describing ${total} queryable objects (parallel×${CONCURRENCY})...`);
+        // CORRECTION (IMPROVE build): mark the FULL (unscoped) introspection authoritative so
+        // the comprehensive-refresh deactivation path may run. A SCOPED introspection
+        // (ObjectNames filter) describes only a subset and can NEVER prove absence, so it is
+        // never authoritative regardless of DiscoveryIsAuthoritative.
+        const result = { Objects: [], IsAuthoritative: this.DiscoveryIsAuthoritative && !wanted };
+        let nextIdx = 0;
+        let succeeded = 0;
+        let skipped = 0;
+        const worker = async () => {
+            while (true) {
+                const myIdx = nextIdx++;
+                if (myIdx >= total)
+                    return;
+                const obj = objects[myIdx];
+                try {
+                    const sourceObj = await this.BuildSourceObjectFromDescribe(companyIntegration, contextUser, obj.Name);
+                    result.Objects.push(sourceObj);
+                    succeeded++;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    skipped++;
+                    console.warn(`[Salesforce] Skipping "${obj.Name}" during introspection: ${msg}`);
+                }
+                const done = succeeded + skipped;
+                if (done % 100 === 0 || done === total) {
+                    const elapsedSec = ((Date.now() - startMs) / 1000).toFixed(1);
+                    const etaSec = done < total
+                        ? (((Date.now() - startMs) / done) * (total - done) / 1000).toFixed(0)
+                        : '0';
+                    console.log(`[Salesforce] IntrospectSchema progress: ${done}/${total} (ok=${succeeded}, skipped=${skipped}) — ${elapsedSec}s elapsed, ~${etaSec}s remaining`);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+        console.log(`[Salesforce] IntrospectSchema complete: ${succeeded}/${total} objects in ${((Date.now() - startMs) / 1000).toFixed(1)}s`);
+        return result;
+    }
+    // ─── Introspection cache (module-scoped via static) ──────────────
+    // Resolver creates a fresh connector per request, so instance-level
+    // caching is useless. Static Map survives across requests in the same
+    // process. TTL is modest to allow schema refresh on demand.
+    static { this.INTROSPECT_CACHE_TTL_MS = 5 * 60 * 1000; }
+    static { this.introspectCache = new Map(); }
+    // ─── FetchChanges (SOQL-based — overrides base class entirely) ───
+    /**
+     * Fetches changed records using SOQL queries with SystemModstamp watermarks.
+     * Completely overrides the base class REST pagination because SF uses
+     * SOQL + queryMore, not standard REST list endpoints.
+     *
+     * Dispatches to family-specific fetch routines based on the
+     * IntegrationObject metadata's `DefaultQueryParams.api_family` hint:
+     * tooling → Tooling API, analytics_report/dashboard → Analytics API,
+     * bulk_* / composite → not intended for listing (returns empty batch),
+     * everything else → standard SObject SOQL flow.
+     */
+    async FetchChanges(ctx) {
+        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
+        const batchSize = ctx.BatchSize || this.effectiveBatchSize;
+        const family = this.ResolveAPIFamily(ctx.CompanyIntegration.IntegrationID, ctx.ObjectName);
+        // Continuation: SF returned a nextRecordsUrl on the previous call,
+        // and the engine passed it back as CurrentCursor. Re-issue against
+        // the same query state via /query/<locator> rather than re-running
+        // the original SOQL (which would just return the first page again
+        // and silently truncate the dataset to one batch). Pre-existing bug:
+        // a dead `this.queryLocator` member shadowed this branch with an
+        // always-false condition, so every "next batch" call re-executed
+        // the initial SOQL and produced duplicate first-page results until
+        // the engine's duplicate-batch guard aborted the entity.
+        if (ctx.CurrentCursor) {
+            return this.FetchNextPage(auth, ctx.CurrentCursor);
+        }
+        if (family === 'analytics_report' || family === 'analytics_dashboard') {
+            return this.FetchAnalyticsList(auth, family, ctx.ObjectName);
+        }
+        if (family === 'bulk_ingest' || family === 'bulk_query') {
+            return this.FetchBulkJobs(auth, family, ctx.ObjectName);
+        }
+        if (family === 'composite') {
+            // Composite is a per-request construct, not a queryable endpoint
+            return { Records: [], HasMore: false };
+        }
+        if (family === 'knowledge') {
+            const page = ctx.CurrentPage ?? 1;
+            return this.FetchKnowledgeArticles(auth, ctx.ObjectName, ctx.WatermarkValue, batchSize, page);
+        }
+        // Standard SObject (sobject) and Tooling (tooling) both use SOQL —
+        // just against different endpoints.
+        const fields = await this.GetQueryableFieldNames(auth, ctx.ObjectName, family);
+        const soql = this.BuildSOQLQuery(ctx.ObjectName, fields, ctx.WatermarkValue, batchSize, true);
+        return this.ExecuteSOQLQuery(auth, soql, ctx.ObjectName, family);
+    }
+    /**
+     * Resolves the API family for a given IntegrationObject by reading its
+     * `DefaultQueryParams.api_family` flag from the engine cache. Defaults to
+     * `sobject` when no metadata is available (common in unit tests).
+     */
+    ResolveAPIFamily(integrationID, objectName) {
+        try {
+            const obj = IntegrationEngineBase.Instance.GetIntegrationObject(integrationID, objectName);
+            if (!obj || !obj.DefaultQueryParams)
+                return 'sobject';
+            const parsed = JSON.parse(obj.DefaultQueryParams);
+            if (this.IsValidFamily(parsed.api_family))
+                return parsed.api_family;
+            return 'sobject';
+        }
+        catch {
+            return 'sobject';
+        }
+    }
+    IsValidFamily(v) {
+        return v === 'sobject' || v === 'tooling' || v === 'knowledge'
+            || v === 'analytics_report' || v === 'analytics_dashboard'
+            || v === 'bulk_ingest' || v === 'bulk_query' || v === 'composite';
+    }
+    /**
+     * Returns the REST path prefix for an SObject in the given API family.
+     * Used by CRUD operations and field discovery.
+     */
+    SObjectBasePath(auth, family) {
+        const base = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}`;
+        return family === 'tooling' ? `${base}/tooling/sobjects` : `${base}/sobjects`;
+    }
+    /**
+     * Returns the SOQL query endpoint for the given API family.
+     * Standard uses /query + /queryAll; Tooling uses /tooling/query.
+     */
+    SOQLEndpoint(auth, family, includeDeleted) {
+        const base = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}`;
+        if (family === 'tooling')
+            return `${base}/tooling/query`;
+        return includeDeleted ? `${base}/queryAll` : `${base}/query`;
+    }
+    // ─── CRUD Operations ─────────────────────────────────────────────
+    /**
+     * Creates a new record in Salesforce. Dispatches to the appropriate API
+     * family endpoint (standard SObjects, Tooling, Bulk Ingest/Query jobs, or
+     * Composite) based on the IntegrationObject metadata.
+     */
+    async CreateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const family = this.ResolveAPIFamily(companyIntegration.IntegrationID, ctx.ObjectName);
+        if (family === 'bulk_ingest' || family === 'bulk_query') {
+            return this.CreateBulkJob(auth, family, ctx.Attributes);
+        }
+        if (family === 'composite') {
+            return this.ExecuteCompositeRequest(auth, ctx.Attributes);
+        }
+        if (family === 'analytics_report' || family === 'analytics_dashboard' || family === 'knowledge') {
+            return {
+                Success: false,
+                ErrorMessage: `[Salesforce] Create is not supported for API family "${family}" (${ctx.ObjectName})`,
+                StatusCode: 405,
+            };
+        }
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const url = `${this.SObjectBasePath(auth, family)}/${ctx.ObjectName}/`;
+        const body = this.StripReadOnlyFields(ctx.Attributes);
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
+        if (response.Status >= 200 && response.Status < 300) {
+            // SF SObject create returns { id, success, errors }. CORRECTION (IMPROVE build):
+            // route through BuildCreatedResult — a 2xx with success=false or an empty/absent id
+            // is a FAILURE (silently losing the record + duplicate create next sync), never
+            // a hand-constructed { Success:true, ExternalID:'' }.
+            const created = response.Body;
+            if (created.success === false) {
+                const detail = (created.errors ?? [])
+                    .map(e => `${e.errorCode}: ${e.message}`).join('; ');
+                return {
+                    Success: false,
+                    StatusCode: response.Status,
+                    ErrorMessage: `[Salesforce] Create of "${ctx.ObjectName}" returned HTTP ${response.Status} with success=false${detail ? `: ${detail}` : ''}`,
+                };
+            }
+            return this.BuildCreatedResult(created.id, response.Status, ctx.ObjectName);
+        }
+        return this.BuildCRUDError(response, 'CreateRecord', ctx.ObjectName);
+    }
+    /**
+     * Updates an existing record in Salesforce (PATCH — only changed fields).
+     * Honors API family routing; Tooling uses `/tooling/sobjects/`, everything
+     * else uses standard `/sobjects/`.
+     */
+    async UpdateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const family = this.ResolveAPIFamily(companyIntegration.IntegrationID, ctx.ObjectName);
+        if (family !== 'sobject' && family !== 'tooling') {
+            return {
+                Success: false,
+                ErrorMessage: `[Salesforce] Update is not supported for API family "${family}" (${ctx.ObjectName})`,
+                StatusCode: 405,
+            };
+        }
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const url = `${this.SObjectBasePath(auth, family)}/${ctx.ObjectName}/${ctx.ExternalID}`;
+        const body = this.StripReadOnlyFields(ctx.Attributes);
+        const response = await this.MakeHTTPRequest(auth, url, 'PATCH', headers, body);
+        if (response.Status === 204 || (response.Status >= 200 && response.Status < 300)) {
+            return {
+                Success: true,
+                ExternalID: ctx.ExternalID,
+                StatusCode: response.Status,
+            };
+        }
+        return this.HandleWriteError(response, 'UpdateRecord', ctx.ObjectName, ctx.ExternalID, auth, headers, url, body);
+    }
+    /**
+     * Deletes a record from Salesforce. For Bulk Job families, delete aborts
+     * the job. For standard and Tooling SObjects, performs a soft delete
+     * (Recycle Bin, 15-day retention). Analytics/Composite/Knowledge do not
+     * support deletion through this path.
+     */
+    async DeleteRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const family = this.ResolveAPIFamily(companyIntegration.IntegrationID, ctx.ObjectName);
+        if (family === 'bulk_ingest' || family === 'bulk_query') {
+            return this.AbortBulkJob(auth, family, ctx.ExternalID);
+        }
+        if (family !== 'sobject' && family !== 'tooling') {
+            return {
+                Success: false,
+                ErrorMessage: `[Salesforce] Delete is not supported for API family "${family}" (${ctx.ObjectName})`,
+                StatusCode: 405,
+            };
+        }
+        const headers = this.BuildHeaders(auth);
+        const url = `${this.SObjectBasePath(auth, family)}/${ctx.ObjectName}/${ctx.ExternalID}`;
+        const response = await this.MakeHTTPRequest(auth, url, 'DELETE', headers);
+        if (response.Status === 204 || (response.Status >= 200 && response.Status < 300)) {
+            return { Success: true, ExternalID: ctx.ExternalID, StatusCode: response.Status };
+        }
+        // ENTITY_IS_DELETED means it's already gone — treat as success
+        if (this.HasSFErrorCode(response, 'ENTITY_IS_DELETED')) {
+            return { Success: true, ExternalID: ctx.ExternalID, StatusCode: 200 };
+        }
+        return this.BuildCRUDError(response, 'DeleteRecord', ctx.ObjectName);
+    }
+    /**
+     * Retrieves a single record by its Salesforce ID. Routes to the API family
+     * endpoint indicated by IntegrationObject metadata.
+     */
+    async GetRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const family = this.ResolveAPIFamily(companyIntegration.IntegrationID, ctx.ObjectName);
+        if (family === 'analytics_report') {
+            return this.GetAnalyticsReport(auth, ctx.ExternalID);
+        }
+        if (family === 'analytics_dashboard') {
+            return this.GetAnalyticsDashboard(auth, ctx.ExternalID);
+        }
+        if (family === 'bulk_ingest' || family === 'bulk_query') {
+            return this.GetBulkJob(auth, family, ctx.ExternalID);
+        }
+        if (family === 'composite') {
+            return null;
+        }
+        const headers = this.BuildHeaders(auth);
+        const url = `${this.SObjectBasePath(auth, family)}/${ctx.ObjectName}/${ctx.ExternalID}`;
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status === 404)
+            return null;
+        this.ValidateResponse(response, url);
+        const raw = response.Body;
+        return this.RawToExternalRecord(raw, ctx.ObjectName);
+    }
+    // ─── Search (SOQL) ───────────────────────────────────────────────
+    /**
+     * Searches records using SOQL WHERE clauses built from the provided filters.
+     * Search is supported for Standard SObjects and Tooling SObjects; other API
+     * families return an empty result.
+     */
+    async SearchRecords(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const family = this.ResolveAPIFamily(companyIntegration.IntegrationID, ctx.ObjectName);
+        if (family !== 'sobject' && family !== 'tooling') {
+            return { Records: [], TotalCount: 0, HasMore: false };
+        }
+        const fields = await this.GetQueryableFieldNames(auth, ctx.ObjectName, family);
+        const whereClause = this.BuildWhereClauseFromFilters(ctx.Filters);
+        const limit = ctx.PageSize ?? 100;
+        const offset = ctx.Page != null && ctx.Page > 1 ? (ctx.Page - 1) * limit : 0;
+        let soql = `SELECT ${fields.join(', ')} FROM ${ctx.ObjectName}`;
+        if (whereClause)
+            soql += ` WHERE ${whereClause}`;
+        if (ctx.Sort)
+            soql += ` ORDER BY ${ctx.Sort}`;
+        soql += ` LIMIT ${limit}`;
+        if (offset > 0)
+            soql += ` OFFSET ${offset}`;
+        const url = `${this.SOQLEndpoint(auth, family, false)}?q=${encodeURIComponent(soql)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const records = (body.records ?? []).map(r => this.RawToExternalRecord(r, ctx.ObjectName));
+        return {
+            Records: records,
+            TotalCount: body.totalSize ?? records.length,
+            HasMore: !body.done,
+        };
+    }
+    // ─── Default Field Mappings ──────────────────────────────────────
+    GetDefaultFieldMappings(objectName, _entityName) {
+        switch (objectName) {
+            case 'Contact': return this.GetContactMappings();
+            case 'Account': return this.GetAccountMappings();
+            case 'Lead': return this.GetLeadMappings();
+            default: return [];
+        }
+    }
+    GetDefaultConfiguration() {
+        return {
+            DefaultSchemaName: 'Salesforce',
+            DefaultObjects: [
+                {
+                    SourceObjectName: 'Account',
+                    TargetTableName: 'SalesforceAccount',
+                    TargetEntityName: 'Salesforce Account',
+                    SyncEnabled: true,
+                    FieldMappings: this.GetAccountMappings(),
+                },
+                {
+                    SourceObjectName: 'Contact',
+                    TargetTableName: 'SalesforceContact',
+                    TargetEntityName: 'Salesforce Contact',
+                    SyncEnabled: true,
+                    FieldMappings: this.GetContactMappings(),
+                },
+                {
+                    SourceObjectName: 'Lead',
+                    TargetTableName: 'SalesforceLead',
+                    TargetEntityName: 'Salesforce Lead',
+                    SyncEnabled: true,
+                    FieldMappings: this.GetLeadMappings(),
+                },
+            ],
+        };
+    }
+    // ─── BaseRESTIntegrationConnector abstract implementations ───────
+    async Authenticate(companyIntegration, contextUser) {
+        // Return cached auth if still valid
+        if (this.cachedAuth && this.IsTokenValid()) {
+            return this.cachedAuth;
+        }
+        const credentials = await this.LoadCredentials(companyIntegration, contextUser);
+        const config = this.BuildConnectionConfig(credentials, companyIntegration);
+        this._config = config;
+        console.log(`[Salesforce] Authenticating via ${config.AuthFlow === 'client_credentials' ? 'Client Credentials' : 'JWT Bearer Token'}...`);
+        const tokenResponse = config.AuthFlow === 'client_credentials'
+            ? await this.ExchangeClientCredentialsForToken(config)
+            : await this.ExchangeJWTForToken(config.TokenUrl ?? config.LoginUrl, this.BuildJWTAssertion(config));
+        this.cachedAuth = {
+            Token: tokenResponse.access_token,
+            InstanceUrl: tokenResponse.instance_url,
+            ApiVersion: config.ApiVersion,
+            Config: config,
+            CompanyIntegration: companyIntegration,
+        };
+        this.tokenObtainedAt = Date.now();
+        console.log(`[Salesforce] Authenticated, instance: ${tokenResponse.instance_url}`);
+        return this.cachedAuth;
+    }
+    BuildHeaders(auth) {
+        return {
+            'Authorization': `Bearer ${auth.Token}`,
+            'Accept': 'application/json',
+        };
+    }
+    async MakeHTTPRequest(auth, url, method, headers, body) {
+        await this.ThrottleIfNeeded();
+        await this.CheckGovernorLimits();
+        const maxRetries = this.effectiveMaxRetries;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            // Transient network / timeout resilience: a FetchWithTimeout throw (AbortSignal timeout,
+            // socket reset, DNS blip) is retried with backoff like any other transient failure, instead
+            // of failing the record on the very first attempt. Idempotent — it retries the SAME request.
+            let response;
+            try {
+                response = await this.FetchWithTimeout(url, method, headers, body);
+            }
+            catch (netErr) {
+                if (attempt < maxRetries) {
+                    const delayMs = this.CalculateRetryDelay(attempt);
+                    console.warn(`[Salesforce] Network/timeout error, retrying in ${delayMs}ms ` +
+                        `(attempt ${attempt + 1}/${maxRetries})`);
+                    await this.Sleep(delayMs);
+                    continue;
+                }
+                throw netErr;
+            }
+            this.lastRequestTime = Date.now();
+            // Parse governor limits from response
+            this.ParseGovernorLimits(response.headers);
+            // Handle 401 — token expired. Clear the cache so the NEXT operation re-authenticates.
+            // NOTE: inline re-auth+retry within this call is NOT done here — MakeHTTPRequest has no
+            // CompanyIntegration/contextUser to call Authenticate() with (that would need a base-signature
+            // change across all connectors). Cache-clear → next-op-recovers is the current contract.
+            if (response.status === 401 && attempt === 0) {
+                console.warn('[Salesforce] Token expired (401), re-authenticating on next operation...');
+                this.cachedAuth = null;
+            }
+            // Handle 429 — rate limited. Honor the vendor's stated wait (Retry-After / Sforce-Limit-Info)
+            // when present; fall back to the AIMD-style exponential backoff otherwise.
+            if (response.status === 429) {
+                const delayMs = this.RetryAfterMs(response.headers) ?? this.CalculateRetryDelay(attempt);
+                console.warn(`[Salesforce] Rate limited (429), retrying in ${delayMs}ms ` +
+                    `(attempt ${attempt + 1}/${maxRetries})`);
+                await this.Sleep(delayMs);
+                continue;
+            }
+            // Handle 500/502/503/504 — transient server-side errors. Per the Salesforce/Fonteva error
+            // contract these are retry-if-safe (backoff). Only retried while attempts remain; otherwise
+            // the non-2xx response is returned to the caller for normal error handling.
+            if ((response.status === 500 || response.status === 502 || response.status === 503 || response.status === 504)
+                && attempt < maxRetries) {
+                const delayMs = this.RetryAfterMs(response.headers) ?? this.CalculateRetryDelay(attempt);
+                console.warn(`[Salesforce] Server error (${response.status}), retrying in ${delayMs}ms ` +
+                    `(attempt ${attempt + 1}/${maxRetries})`);
+                await this.Sleep(delayMs);
+                continue;
+            }
+            // Handle UNABLE_TO_LOCK_ROW — retry with backoff
+            if (response.status === 400) {
+                const responseBody = await this.SafeParseJSON(response);
+                if (this.IsLockRowError(responseBody) && attempt < maxRetries) {
+                    const delayMs = this.CalculateRetryDelay(attempt);
+                    console.warn(`[Salesforce] Row lock contention, retrying in ${delayMs}ms`);
+                    await this.Sleep(delayMs);
+                    continue;
+                }
+                return this.BuildRESTResponse(response, responseBody);
+            }
+            // Handle 204 No Content (successful DELETE/PATCH)
+            if (response.status === 204) {
+                return { Status: 204, Body: {}, Headers: this.ExtractHeaders(response) };
+            }
+            const responseBody = await this.SafeParseJSON(response);
+            return this.BuildRESTResponse(response, responseBody);
+        }
+        throw new Error(`Salesforce API request failed after ${maxRetries} retries: ${url}`);
+    }
+    NormalizeResponse(rawBody, _responseDataKey) {
+        // SF SOQL responses have records at body.records
+        const body = rawBody;
+        return (body.records ?? []);
+    }
+    /**
+     * CORRECTION (IMPROVE build): per-record transform that strips Salesforce's
+     * `attributes` metadata blob (e.g. `{ type, url }`) from every record. This is a
+     * SANCTIONED removal declared in {@link ExcludedSourceKeys}, NOT a silent drop — the
+     * `attributes` key is vendor envelope noise, not customer data, so dropping it can
+     * never lose a custom column. Every OTHER source field flows through untouched, so
+     * the full-record pass-through contract (custom-column capture) is preserved.
+     *
+     * Used by both the base-fetch path (GetRecord via applyTransformPreservingKeys) and
+     * the SOQL override path (RawToExternalRecord routes through StripVendorAttributes,
+     * which reuses ExcludedSourceKeys so the two paths agree on what is removed).
+     */
+    TransformRecord(raw, _obj, _fields) {
+        if (!('attributes' in raw))
+            return raw; // identity fast-path — nothing to strip
+        const out = { ...raw };
+        delete out['attributes'];
+        return out;
+    }
+    /**
+     * The Salesforce `attributes` blob is the ONLY key any object's TransformRecord
+     * removes. Declaring it here makes the removal auditable and excludes it from the
+     * base's re-add-dropped-keys safety net (and from change-detection).
+     */
+    ExcludedSourceKeys(_objectName) {
+        return ['attributes'];
+    }
+    ExtractPaginationInfo(rawBody, _paginationType, _currentPage, _currentOffset, _pageSize) {
+        // Not used — we override FetchChanges entirely for SOQL
+        const body = rawBody;
+        return {
+            HasMore: !body.done,
+            NextCursor: body.nextRecordsUrl ?? undefined,
+        };
+    }
+    GetBaseURL(_companyIntegration, auth) {
+        const sfAuth = auth;
+        return sfAuth.InstanceUrl;
+    }
+    /**
+     * The API origin for all REST calls. Routes through GetBaseURL() so a test harness can
+     * redirect the connector to a mock server (the base class hooks GetBaseURL); in production
+     * this returns the authenticated InstanceUrl unchanged. ALL URL construction must go through
+     * this rather than reading auth.InstanceUrl directly, or the connector is not mock-testable.
+     */
+    ApiBase(auth) {
+        return this.GetBaseURL(auth.CompanyIntegration, auth);
+    }
+    // ─── SOQL Query Engine ───────────────────────────────────────────
+    /**
+     * Builds a SOQL query string with optional watermark filter.
+     */
+    BuildSOQLQuery(objectName, fields, watermarkValue, batchSize, includeDeleted) {
+        // Many SF system/tooling/meta objects lack one or more of the "standard"
+        // audit fields (SystemModstamp, IsDeleted, LastModifiedById). Assuming
+        // they're always present produces `INVALID_FIELD` errors. Build the
+        // SELECT from what the object's describe actually exposes.
+        const available = new Set(fields);
+        const requiredPresent = REQUIRED_SOQL_FIELDS.filter(f => available.has(f));
+        const dedupedFields = [...new Set([...requiredPresent, ...fields])];
+        // Pick the best available watermark/ordering column.
+        // Preference: SystemModstamp > LastModifiedDate > CreatedDate > (none)
+        const watermarkCol = available.has('SystemModstamp')
+            ? 'SystemModstamp'
+            : available.has('LastModifiedDate')
+                ? 'LastModifiedDate'
+                : available.has('CreatedDate')
+                    ? 'CreatedDate'
+                    : null;
+        let soql = `SELECT ${dedupedFields.join(', ')} FROM ${objectName}`;
+        if (watermarkValue && watermarkCol) {
+            // `>=` not `>` — strict greater-than misses records modified
+            // at exactly the watermark instant. SF's SystemModstamp has
+            // millisecond precision but bulk updates can produce multiple
+            // records with the identical modstamp; only the last one shapes
+            // the saved watermark. Without `>=`, any record colliding on
+            // that exact ms after watermark save is permanently dropped
+            // (the watermark advances past it next sync). Engine dedupe
+            // handles the cheap cost of re-fetching boundary records.
+            soql += ` WHERE ${watermarkCol} >= ${this.FormatSOQLDateTime(watermarkValue)}`;
+        }
+        if (watermarkCol) {
+            soql += ` ORDER BY ${watermarkCol} ASC`;
+        }
+        // NO `LIMIT batchSize`. SF's REST API natively paginates the result
+        // via `done` / `nextRecordsUrl` — the engine loop drives subsequent
+        // pages. A SOQL LIMIT here would cap the ENTIRE result set at
+        // batchSize records and SF would (correctly) report done=true at
+        // that count, silently dropping every record past the limit. The
+        // worst part: incremental syncs advance the watermark past the
+        // dropped records, so they're never re-fetched on subsequent runs.
+        // Per-page batch size is controlled by the `Sforce-Query-Options`
+        // header (or SF default) and does not need a SOQL LIMIT.
+        // _ = batchSize  // intentionally unused — preserved param for API stability
+        void batchSize;
+        return soql;
+    }
+    /**
+     * Executes a SOQL query and returns records as a FetchBatchResult.
+     * For the standard SObject family this uses `queryAll` so that soft-deleted
+     * records are returned (IsDeleted=true). For the Tooling family, the
+     * Tooling API's `/tooling/query` endpoint is used — `queryAll` is not
+     * supported there.
+     */
+    async ExecuteSOQLQuery(auth, soql, objectName, family = 'sobject') {
+        const includeDeleted = family === 'sobject';
+        const url = `${this.SOQLEndpoint(auth, family, includeDeleted)}?q=${encodeURIComponent(soql)}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        return this.ParseSOQLResponse(response.Body, objectName);
+    }
+    /**
+     * Fetches the next page of results using a queryMore locator.
+     */
+    async FetchNextPage(auth, queryLocator) {
+        // queryLocator is a relative URL like /services/data/v61.0/query/01gxx...
+        const url = `${this.ApiBase(auth)}${queryLocator}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        // Extract object name from the first record's attributes
+        const firstRecord = body.records?.[0];
+        const attrs = firstRecord?.['attributes'];
+        const objectName = attrs?.type ?? 'Unknown';
+        return this.ParseSOQLResponse(body, objectName);
+    }
+    /**
+     * Parses a SOQL query response into a FetchBatchResult.
+     */
+    ParseSOQLResponse(body, objectName) {
+        const rawRecords = body.records ?? [];
+        // Some Salesforce system/metadata objects (e.g. TabDefinition,
+        // FormulaFunctionAllowedType) return many rows that all share the
+        // placeholder `Id = '000000000000000AAA'` — SF treats Id as
+        // non-unique on those objects, but MJ's auto-generated UQ_<table>_PK
+        // rejects the duplicates and produces one error per record after
+        // the first. Dedupe on Id within the batch (keep first occurrence)
+        // before returning to the engine.
+        const seenIds = new Set();
+        const dedupedRaw = [];
+        let duplicatesDropped = 0;
+        for (const r of rawRecords) {
+            const raw = r;
+            const id = raw['Id'];
+            if (id) {
+                if (seenIds.has(id)) {
+                    duplicatesDropped++;
+                    continue;
+                }
+                seenIds.add(id);
+            }
+            dedupedRaw.push(r);
+        }
+        if (duplicatesDropped > 0) {
+            console.warn(`[Salesforce] ${objectName}: dropped ${duplicatesDropped} record(s) with duplicate Id ` +
+                `(SF returned non-unique Ids for this object — typical for system/metadata sObjects ` +
+                `like TabDefinition, FormulaFunctionAllowedType where Id is a placeholder).`);
+        }
+        const records = dedupedRaw.map(r => {
+            const raw = r;
+            const record = this.RawToExternalRecord(raw, objectName);
+            record.IsDeleted = raw['IsDeleted'] === true;
+            record.ModifiedAt = raw['SystemModstamp']
+                ? new Date(raw['SystemModstamp'])
+                : undefined;
+            return record;
+        });
+        // Compute new watermark from the max SystemModstamp in this batch
+        const newWatermark = this.ExtractMaxWatermark(dedupedRaw);
+        return {
+            Records: records,
+            HasMore: !body.done,
+            NewWatermarkValue: newWatermark ?? undefined,
+            NextCursor: body.nextRecordsUrl ?? undefined,
+        };
+    }
+    /**
+     * Extracts the maximum SystemModstamp value from a batch of records and
+     * advances it by 1ms so the next sync's `WHERE SystemModstamp >= <wm>`
+     * filter excludes the boundary cluster.
+     *
+     * Why advance: the SOQL filter uses `>=` (not `>`) on purpose so we don't
+     * drop records that share the modstamp instant of the previous max. But
+     * if the saved watermark equals the new max, every subsequent incremental
+     * re-pulls the same boundary cluster forever and the watermark plateaus.
+     * Observed in the wild: 1,800 EmailMessage records bulk-imported with
+     * identical SystemModstamp re-fetched on every run with `Updated` count
+     * never decreasing.
+     *
+     * SF's SystemModstamp is millisecond-precision, so adding 1ms cannot
+     * skip a real record — there is nothing scheduled between `max` and
+     * `max + 1ms`. The connector returns the advanced value as
+     * `NewWatermarkValue`; the engine persists it; the next run picks up
+     * cleanly past the cluster.
+     */
+    ExtractMaxWatermark(records) {
+        let maxTimestamp = null;
+        for (const record of records) {
+            const raw = record;
+            const stamp = raw['SystemModstamp'];
+            if (stamp && (!maxTimestamp || stamp > maxTimestamp)) {
+                maxTimestamp = stamp;
+            }
+        }
+        if (!maxTimestamp)
+            return null;
+        const parsed = new Date(maxTimestamp);
+        if (Number.isNaN(parsed.getTime()))
+            return maxTimestamp;
+        return new Date(parsed.getTime() + 1).toISOString();
+    }
+    /**
+     * Gets queryable field names for a SF object via the Describe API. When
+     * `family === 'tooling'`, calls the Tooling describe endpoint instead of
+     * the standard one.
+     */
+    async GetQueryableFieldNames(auth, objectName, family = 'sobject') {
+        const url = `${this.SObjectBasePath(auth, family)}/${objectName}/describe`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const fields = body.fields ?? [];
+        return fields
+            .filter(f => !COMPOUND_FIELD_TYPES.has(f.type))
+            .map(f => f.name);
+    }
+    // ─── JWT Authentication ──────────────────────────────────────────
+    /**
+     * Builds a signed JWT assertion for the SF JWT Bearer Token flow.
+     */
+    BuildJWTAssertion(config) {
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            iss: config.ClientId,
+            sub: config.Username,
+            aud: config.LoginUrl,
+            exp: now + 300, // 5 minutes
+        };
+        if (!config.PrivateKey) {
+            throw new Error('Salesforce JWT Bearer authentication requires a PrivateKey.');
+        }
+        const pem = this.NormalizePem(config.PrivateKey);
+        return jwt.sign(payload, pem, { algorithm: 'RS256' });
+    }
+    /**
+     * Normalize a PEM private key that may have had its newlines stripped or
+     * replaced with spaces / literal "\n" sequences. Rebuilds the standard
+     * BEGIN header / 64-char body / END footer layout that OpenSSL requires.
+     */
+    NormalizePem(key) {
+        if (!key)
+            return key;
+        // First, normalize escaped newlines to real ones
+        let normalized = key.includes('\\n') ? key.replace(/\\n/g, '\n') : key;
+        // If real newlines exist already, trust them
+        if (normalized.includes('\n'))
+            return normalized;
+        // Split out header / footer / body and rebuild with real newlines
+        const headerMatch = normalized.match(/^(-----BEGIN [^-]+-----)/);
+        const footerMatch = normalized.match(/(-----END [^-]+-----)\s*$/);
+        if (!headerMatch || !footerMatch)
+            return normalized;
+        const header = headerMatch[1];
+        const footer = footerMatch[1];
+        const bodyRaw = normalized.slice(header.length, normalized.length - footer.length);
+        const body = bodyRaw.replace(/\s+/g, '');
+        const chunked = body.match(/.{1,64}/g)?.join('\n') ?? body;
+        return `${header}\n${chunked}\n${footer}`;
+    }
+    /**
+     * Exchanges a JWT assertion for an access token at the SF token endpoint.
+     */
+    async ExchangeJWTForToken(loginUrl, jwtAssertion) {
+        const tokenUrl = `${loginUrl}/services/oauth2/token`;
+        const body = `grant_type=${encodeURIComponent('urn:ietf:params:oauth:grant-type:jwt-bearer')}&assertion=${encodeURIComponent(jwtAssertion)}`;
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+            signal: AbortSignal.timeout(this.effectiveRequestTimeoutMs),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`Salesforce JWT token exchange failed (HTTP ${response.status}): ${errorBody}`);
+        }
+        const result = await response.json();
+        if (!result.access_token || !result.instance_url) {
+            throw new Error('Salesforce token response missing access_token or instance_url');
+        }
+        return result;
+    }
+    /**
+     * Exchanges Client Credentials for an access token.
+     * Used with Connected Apps configured for the OAuth 2.0 Client Credentials flow.
+     */
+    async ExchangeClientCredentialsForToken(config) {
+        if (!config.ClientSecret) {
+            throw new Error('Client Credentials flow requires clientSecret');
+        }
+        const tokenUrl = `${config.LoginUrl}/services/oauth2/token`;
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: config.ClientId,
+            client_secret: config.ClientSecret,
+        }).toString();
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body,
+            signal: AbortSignal.timeout(this.effectiveRequestTimeoutMs),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`Salesforce Client Credentials token exchange failed (HTTP ${response.status}): ${errorBody}`);
+        }
+        const result = await response.json();
+        if (!result.access_token || !result.instance_url) {
+            throw new Error('Salesforce token response missing access_token or instance_url');
+        }
+        return result;
+    }
+    /**
+     * Checks if the cached token is still valid (within 80% of lifetime).
+     */
+    IsTokenValid() {
+        if (!this.cachedAuth || this.tokenObtainedAt === 0)
+            return false;
+        const elapsed = Date.now() - this.tokenObtainedAt;
+        return elapsed < TOKEN_LIFETIME_MS * TOKEN_REFRESH_THRESHOLD;
+    }
+    // ─── Credential Loading ──────────────────────────────────────────
+    /**
+     * Loads credentials from the Credential entity or Configuration JSON.
+     */
+    async LoadCredentials(companyIntegration, contextUser) {
+        // Try Credential entity first
+        const credentialID = companyIntegration.CredentialID;
+        if (credentialID) {
+            const creds = await this.LoadFromCredentialEntity(credentialID, contextUser);
+            if (creds)
+                return creds;
+        }
+        // Fallback: Configuration JSON
+        const configJson = companyIntegration.Configuration;
+        if (configJson) {
+            const creds = this.ParseCredentialJson(configJson);
+            if (creds)
+                return creds;
+        }
+        throw new Error('No Salesforce credentials found. Set Configuration JSON with either ' +
+            '(a) clientId + clientSecret for Client Credentials flow, or ' +
+            '(b) clientId + username + privateKey for JWT Bearer flow.');
+    }
+    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;
+        return this.ParseCredentialJson(credential.Values);
+    }
+    ParseCredentialJson(json) {
+        try {
+            const parsed = JSON.parse(json);
+            const clientId = parsed['clientId'] ?? parsed['ClientId'];
+            if (!clientId)
+                return null;
+            const loginUrl = parsed['loginUrl'] ?? parsed['LoginUrl'] ?? 'https://login.salesforce.com';
+            const apiVersion = parsed['apiVersion'] ?? parsed['ApiVersion'] ?? DEFAULT_API_VERSION;
+            const tokenUrl = parsed['tokenUrl'] ?? parsed['TokenUrl'];
+            // Detect auth flow: if clientSecret is present, use client_credentials;
+            // otherwise require privateKey + username for JWT Bearer
+            const clientSecret = parsed['clientSecret'] ?? parsed['ClientSecret'];
+            const privateKey = parsed['privateKey'] ?? parsed['PrivateKey'];
+            const username = parsed['username'] ?? parsed['Username'];
+            const explicitFlow = parsed['authFlow'] ?? parsed['AuthFlow'];
+            if (explicitFlow === 'client_credentials' || (clientSecret && !privateKey)) {
+                if (!clientSecret)
+                    return null;
+                return {
+                    AuthFlow: 'client_credentials',
+                    LoginUrl: loginUrl,
+                    ClientId: clientId,
+                    ClientSecret: clientSecret,
+                    ApiVersion: apiVersion,
+                    TokenUrl: tokenUrl,
+                };
+            }
+            // JWT Bearer flow
+            if (!privateKey || !username)
+                return null;
+            return {
+                AuthFlow: 'jwt_bearer',
+                LoginUrl: loginUrl,
+                ClientId: clientId,
+                Username: username,
+                PrivateKey: privateKey,
+                ApiVersion: apiVersion,
+                TokenUrl: tokenUrl,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    BuildConnectionConfig(credentials, companyIntegration) {
+        const config = {
+            AuthFlow: credentials.AuthFlow,
+            LoginUrl: credentials.LoginUrl,
+            ClientId: credentials.ClientId,
+            ApiVersion: credentials.ApiVersion,
+            Username: credentials.Username,
+            PrivateKey: credentials.PrivateKey,
+            ClientSecret: credentials.ClientSecret,
+            TokenUrl: credentials.TokenUrl,
+        };
+        const configJson = companyIntegration.Configuration;
+        if (configJson) {
+            this.ApplyConfigOverrides(config, configJson);
+        }
+        return config;
+    }
+    ApplyConfigOverrides(config, json) {
+        try {
+            const parsed = JSON.parse(json);
+            const parseOptionalInt = (key) => {
+                const v = parsed[key];
+                if (v == null)
+                    return undefined;
+                const n = Number(v);
+                return isNaN(n) ? undefined : Math.floor(n);
+            };
+            config.MaxRetries = parseOptionalInt('MaxRetries');
+            config.RequestTimeoutMs = parseOptionalInt('RequestTimeoutMs');
+            config.MinRequestIntervalMs = parseOptionalInt('MinRequestIntervalMs');
+            config.DefaultBatchSize = parseOptionalInt('DefaultBatchSize');
+        }
+        catch {
+            // Configuration JSON may not be valid — ignore
+        }
+    }
+    // ─── Rate Limit / Governor Limit Management ──────────────────────
+    /**
+     * Throttles requests to respect minimum interval between API calls.
+     */
+    async ThrottleIfNeeded() {
+        const minInterval = this.effectiveMinRequestIntervalMs;
+        const elapsed = Date.now() - this.lastRequestTime;
+        if (elapsed < minInterval) {
+            await this.Sleep(minInterval - elapsed);
+        }
+    }
+    /**
+     * Checks governor limits and pauses if approaching the daily API limit.
+     */
+    async CheckGovernorLimits() {
+        const { CurrentUsage, DailyLimit } = this.governorState;
+        if (DailyLimit === 0)
+            return;
+        const ratio = CurrentUsage / DailyLimit;
+        if (ratio >= GOVERNOR_PAUSE_THRESHOLD) {
+            throw new Error(`Salesforce governor limit critical: ${CurrentUsage}/${DailyLimit} API calls used ` +
+                `(${Math.round(ratio * 100)}%). Sync paused to prevent REQUEST_LIMIT_EXCEEDED.`);
+        }
+        if (ratio >= GOVERNOR_THROTTLE_THRESHOLD) {
+            console.warn(`[Salesforce] Governor limit warning: ${CurrentUsage}/${DailyLimit} ` +
+                `(${Math.round(ratio * 100)}%). Adding throttle delay.`);
+            await this.Sleep(500); // Extra delay when approaching limit
+        }
+    }
+    /**
+     * Parses the Sforce-Limit-Info header from every SF response.
+     */
+    ParseGovernorLimits(headers) {
+        const limitInfo = headers.get('sforce-limit-info');
+        if (!limitInfo)
+            return;
+        // Format: "api-usage=25/15000"
+        const match = limitInfo.match(/api-usage=(\d+)\/(\d+)/);
+        if (match) {
+            this.governorState = {
+                CurrentUsage: parseInt(match[1], 10),
+                DailyLimit: parseInt(match[2], 10),
+                LastUpdated: Date.now(),
+            };
+        }
+    }
+    // ─── HTTP Helpers ────────────────────────────────────────────────
+    async FetchWithTimeout(url, method, headers, body) {
+        const fetchOptions = {
+            method,
+            headers,
+            signal: AbortSignal.timeout(this.effectiveRequestTimeoutMs),
+        };
+        if (body !== undefined && method !== 'GET' && method !== 'DELETE') {
+            fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+        }
+        return fetch(url, fetchOptions);
+    }
+    BuildRESTResponse(response, body) {
+        return {
+            Status: response.status,
+            Body: body,
+            Headers: this.ExtractHeaders(response),
+        };
+    }
+    ExtractHeaders(response) {
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key.toLowerCase()] = value;
+        });
+        return headers;
+    }
+    async SafeParseJSON(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return {};
+        }
+    }
+    CalculateRetryDelay(attempt) {
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s (capped at 30s)
+        return Math.min(1000 * Math.pow(2, attempt), 30000);
+    }
+    /**
+     * Parses the vendor's stated retry wait from a 429/503 response into milliseconds, so the connector
+     * honors `Retry-After` (delta-seconds OR an HTTP-date) and Salesforce's `Sforce-Limit-Info` rather
+     * than blindly using exponential backoff. Returns null when no usable signal is present (caller falls
+     * back to {@link CalculateRetryDelay}). Capped at 60s so a hostile/garbage header can't stall a sync.
+     */
+    RetryAfterMs(headers) {
+        const raw = headers?.get?.('retry-after');
+        if (raw) {
+            const secs = Number(raw);
+            if (Number.isFinite(secs) && secs >= 0)
+                return Math.min(secs * 1000, 60000);
+            const when = Date.parse(raw); // HTTP-date form
+            if (!Number.isNaN(when))
+                return Math.min(Math.max(when - Date.now(), 0), 60000);
+        }
+        return null;
+    }
+    Sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    // ─── SF Type Mapping ─────────────────────────────────────────────
+    /**
+     * Maps a Salesforce field describe to an ExternalFieldSchema.
+     * Custom fields can be detected by callers via the `__c` suffix in the
+     * field name — Salesforce standardizes this convention for all custom
+     * fields on both standard and custom SObjects.
+     */
+    MapSFFieldToSchema(f) {
+        // Salesforce's `Id` is the universal PK on every SObject (standard + custom).
+        // The /describe response sets type='id' on the PK field but doesn't carry
+        // an explicit IsPrimaryKey signal, so we have to stamp it here.  Without
+        // this, UpsertField's new-field path would persist `Id` with no PK flag
+        // and the downstream SoftPKClassifier becomes the only safety net.
+        const isPK = f.name === 'Id' || f.type === 'id';
+        return {
+            Name: f.name,
+            Label: f.label,
+            Description: f.inlineHelpText ?? undefined,
+            DataType: this.MapSalesforceType(f.type),
+            IsRequired: !f.nillable && !f.defaultedOnCreate,
+            IsPrimaryKey: isPK,
+            IsUniqueKey: isPK || f.externalId,
+            IsReadOnly: f.calculated || !f.updateable || SYSTEM_READ_ONLY_FIELDS.has(f.name),
+            IsForeignKey: f.type === 'reference' && f.referenceTo.length > 0,
+            ForeignKeyTarget: f.referenceTo.length > 0 ? f.referenceTo[0] : null,
+        };
+    }
+    /**
+     * Maps a Salesforce field type to a generic integration type.
+     */
+    MapSalesforceType(sfType) {
+        switch (sfType) {
+            case 'string':
+            case 'textarea':
+            case 'url':
+            case 'email':
+            case 'phone':
+            case 'picklist':
+            case 'multipicklist':
+            case 'combobox':
+                return 'string';
+            case 'int':
+                return 'integer';
+            case 'double':
+            case 'currency':
+            case 'percent':
+                return 'decimal';
+            case 'boolean':
+                return 'boolean';
+            case 'date':
+                return 'date';
+            case 'datetime':
+                return 'datetime';
+            case 'time':
+                return 'time';
+            case 'id':
+            case 'reference':
+                return 'nvarchar(18)';
+            case 'base64':
+            case 'encryptedstring':
+                return 'text';
+            default:
+                return 'string';
+        }
+    }
+    // ─── SOQL Helpers ────────────────────────────────────────────────
+    /**
+     * Formats a watermark value as a SOQL datetime literal.
+     */
+    FormatSOQLDateTime(value) {
+        // If it's already in ISO 8601 format, it works directly in SOQL
+        // SOQL accepts: 2026-03-13T10:30:00.000Z or 2026-03-13T10:30:00.000+00:00
+        if (value.includes('T'))
+            return value;
+        // If it's just a date, append time
+        return `${value}T00:00:00.000Z`;
+    }
+    /**
+     * Builds a SOQL WHERE clause from a Filters map.
+     */
+    BuildWhereClauseFromFilters(filters) {
+        const conditions = Object.entries(filters).map(([field, value]) => {
+            const escaped = value.replace(/'/g, "\\'");
+            return `${field} = '${escaped}'`;
+        });
+        return conditions.length > 0 ? conditions.join(' AND ') : null;
+    }
+    // ─── Error Handling ──────────────────────────────────────────────
+    /**
+     * Checks if a response contains a specific SF error code.
+     */
+    HasSFErrorCode(response, errorCode) {
+        const errors = this.ExtractSFErrors(response);
+        return errors.some(e => e.errorCode === errorCode);
+    }
+    /**
+     * Extracts SF error objects from a response.
+     */
+    ExtractSFErrors(response) {
+        const body = response.Body;
+        if (Array.isArray(body)) {
+            return body;
+        }
+        if (body && typeof body === 'object' && 'message' in body) {
+            return [body];
+        }
+        return [];
+    }
+    /**
+     * Checks if a response body contains an UNABLE_TO_LOCK_ROW error.
+     */
+    IsLockRowError(body) {
+        if (!Array.isArray(body))
+            return false;
+        return body.some((e) => e['errorCode'] === 'UNABLE_TO_LOCK_ROW');
+    }
+    /**
+     * Builds a CRUDResult for error responses.
+     */
+    BuildCRUDError(response, operation, objectName) {
+        const errors = this.ExtractSFErrors(response);
+        const message = errors.length > 0
+            ? errors.map(e => `${e.errorCode}: ${e.message}`).join('; ')
+            : `[Salesforce] ${operation} on ${objectName} failed (HTTP ${response.Status})`;
+        return {
+            Success: false,
+            ErrorMessage: message,
+            StatusCode: response.Status,
+        };
+    }
+    /**
+     * Handles write errors with special retry logic for UNABLE_TO_LOCK_ROW.
+     */
+    async HandleWriteError(response, operation, objectName, externalID, auth, headers, url, body) {
+        // UNABLE_TO_LOCK_ROW — retry once more
+        if (this.HasSFErrorCode(response, 'UNABLE_TO_LOCK_ROW')) {
+            console.warn(`[Salesforce] Row lock contention on ${objectName}/${externalID}, retrying...`);
+            await this.Sleep(1000);
+            const retry = await this.MakeHTTPRequest(auth, url, 'PATCH', headers, body);
+            if (retry.Status === 204 || (retry.Status >= 200 && retry.Status < 300)) {
+                return { Success: true, ExternalID: externalID, StatusCode: retry.Status };
+            }
+        }
+        return this.BuildCRUDError(response, operation, objectName);
+    }
+    // ─── Record Conversion ───────────────────────────────────────────
+    /**
+     * Converts a raw SF API record to an ExternalRecord. The SOQL override path
+     * hand-builds records, so it routes through the SAME sanctioned strip the base path
+     * uses: every key flows through to `Fields` EXCEPT those declared in
+     * {@link ExcludedSourceKeys} (just `attributes`). This preserves full-record
+     * pass-through for custom-column capture while removing only the vendor envelope blob.
+     */
+    RawToExternalRecord(raw, objectType) {
+        const excluded = new Set(this.ExcludedSourceKeys(objectType));
+        const fields = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (excluded.has(key))
+                continue; // sanctioned removal (SF metadata, not a data field)
+            fields[key] = value;
+        }
+        return {
+            ExternalID: String(raw['Id'] ?? ''),
+            ObjectType: objectType,
+            Fields: fields,
+            ModifiedAt: raw['SystemModstamp']
+                ? new Date(raw['SystemModstamp'])
+                : undefined,
+        };
+    }
+    /**
+     * Strips read-only and system fields from an attributes map before write operations.
+     */
+    StripReadOnlyFields(attributes) {
+        const result = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (SYSTEM_READ_ONLY_FIELDS.has(key))
+                continue;
+            if (value === undefined)
+                continue;
+            result[key] = value;
+        }
+        return result;
+    }
+    // ─── Schema Building ─────────────────────────────────────────────
+    async BuildSourceObjectFromDescribe(companyIntegration, contextUser, objectName) {
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/sobjects/${objectName}/describe`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const sfFields = (body.fields ?? []).filter(f => !COMPOUND_FIELD_TYPES.has(f.type));
+        const fields = sfFields.map(f => ({
+            Name: f.name,
+            Label: f.label,
+            Description: f.inlineHelpText ?? undefined,
+            SourceType: this.MapSalesforceType(f.type),
+            IsRequired: !f.nillable && !f.defaultedOnCreate,
+            MaxLength: f.length > 0 ? f.length : null,
+            Precision: f.precision > 0 ? f.precision : null,
+            Scale: f.scale > 0 ? f.scale : null,
+            DefaultValue: f.defaultValue != null ? String(f.defaultValue) : null,
+            IsPrimaryKey: f.name === 'Id',
+            IsForeignKey: f.type === 'reference' && f.referenceTo.length > 0,
+            ForeignKeyTarget: f.referenceTo.length > 0 ? f.referenceTo[0] : null,
+        }));
+        const relationships = sfFields
+            .filter(f => f.type === 'reference' && f.referenceTo.length > 0)
+            .map(f => ({
+            FieldName: f.name,
+            TargetObject: f.referenceTo[0],
+            TargetField: 'Id',
+        }));
+        return {
+            ExternalName: objectName,
+            ExternalLabel: body.label ?? objectName,
+            Description: undefined,
+            Fields: fields,
+            PrimaryKeyFields: ['Id'],
+            Relationships: relationships,
+        };
+    }
+    // ─── Default Field Mappings ──────────────────────────────────────
+    GetContactMappings() {
+        return [
+            { SourceFieldName: 'Email', DestinationFieldName: 'Email', IsKeyField: true },
+            { SourceFieldName: 'FirstName', DestinationFieldName: 'FirstName' },
+            { SourceFieldName: 'LastName', DestinationFieldName: 'LastName' },
+            { SourceFieldName: 'Phone', DestinationFieldName: 'Phone' },
+            { SourceFieldName: 'MobilePhone', DestinationFieldName: 'MobilePhone' },
+            { SourceFieldName: 'Title', DestinationFieldName: 'Title' },
+            { SourceFieldName: 'Department', DestinationFieldName: 'Department' },
+            { SourceFieldName: 'MailingStreet', DestinationFieldName: 'Address1' },
+            { SourceFieldName: 'MailingCity', DestinationFieldName: 'City' },
+            { SourceFieldName: 'MailingState', DestinationFieldName: 'StateOrProvince' },
+            { SourceFieldName: 'MailingPostalCode', DestinationFieldName: 'PostalCode' },
+            { SourceFieldName: 'MailingCountry', DestinationFieldName: 'Country' },
+        ];
+    }
+    GetAccountMappings() {
+        return [
+            { SourceFieldName: 'Name', DestinationFieldName: 'Name', IsKeyField: true },
+            { SourceFieldName: 'BillingStreet', DestinationFieldName: 'Address1' },
+            { SourceFieldName: 'BillingCity', DestinationFieldName: 'City' },
+            { SourceFieldName: 'BillingState', DestinationFieldName: 'StateOrProvince' },
+            { SourceFieldName: 'BillingPostalCode', DestinationFieldName: 'PostalCode' },
+            { SourceFieldName: 'BillingCountry', DestinationFieldName: 'Country' },
+            { SourceFieldName: 'Phone', DestinationFieldName: 'Phone' },
+            { SourceFieldName: 'Website', DestinationFieldName: 'WebSite' },
+            { SourceFieldName: 'Industry', DestinationFieldName: 'Industry' },
+            { SourceFieldName: 'Description', DestinationFieldName: 'Description' },
+        ];
+    }
+    GetLeadMappings() {
+        return [
+            { SourceFieldName: 'Email', DestinationFieldName: 'Email', IsKeyField: true },
+            { SourceFieldName: 'FirstName', DestinationFieldName: 'FirstName' },
+            { SourceFieldName: 'LastName', DestinationFieldName: 'LastName' },
+            { SourceFieldName: 'Phone', DestinationFieldName: 'Phone' },
+            { SourceFieldName: 'Company', DestinationFieldName: 'CompanyName' },
+            { SourceFieldName: 'Title', DestinationFieldName: 'Title' },
+        ];
+    }
+    // ─── Validation Helpers ──────────────────────────────────────────
+    ValidateResponse(response, url) {
+        if (response.Status < 200 || response.Status >= 300) {
+            const preview = this.PreviewBody(response.Body);
+            throw new Error(`HTTP ${response.Status} from ${url}: ${preview}`);
+        }
+    }
+    PreviewBody(body) {
+        if (typeof body === 'string')
+            return body.slice(0, 500);
+        return JSON.stringify(body).slice(0, 500);
+    }
+    // ─── Analytics API (Reports & Dashboards) ────────────────────────
+    /**
+     * Lists Analytics Reports or Dashboards via the Analytics API. Read-only;
+     * no incremental-sync support at this endpoint.
+     */
+    async FetchAnalyticsList(auth, family, objectName) {
+        const segment = family === 'analytics_report' ? 'reports' : 'dashboards';
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/analytics/${segment}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const list = body.reports ?? body.dashboards ?? [];
+        const records = list.map(item => this.AnalyticsItemToRecord(item, objectName));
+        return { Records: records, HasMore: false };
+    }
+    AnalyticsItemToRecord(item, objectType) {
+        return {
+            ExternalID: String(item.id ?? ''),
+            ObjectType: objectType,
+            Fields: { ...item },
+        };
+    }
+    async GetAnalyticsReport(auth, id) {
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/analytics/reports/${id}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status === 404)
+            return null;
+        this.ValidateResponse(response, url);
+        return {
+            ExternalID: id,
+            ObjectType: 'Report',
+            Fields: response.Body,
+        };
+    }
+    async GetAnalyticsDashboard(auth, id) {
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/analytics/dashboards/${id}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status === 404)
+            return null;
+        this.ValidateResponse(response, url);
+        return {
+            ExternalID: id,
+            ObjectType: 'Dashboard',
+            Fields: response.Body,
+        };
+    }
+    // ─── Knowledge Articles ──────────────────────────────────────────
+    /**
+     * Fetches published Knowledge article versions. This endpoint is
+     * paginated via `pageNumber`/`pageSize` (not cursor). The connector
+     * returns a single batch; callers that need pagination can issue
+     * additional requests via SearchRecords.
+     */
+    async FetchKnowledgeArticles(auth, objectName, watermarkValue, batchSize, page = 1) {
+        const params = new URLSearchParams({ pageSize: String(batchSize), pageNumber: String(page) });
+        if (watermarkValue) {
+            params.set('publishStatus', 'Online');
+        }
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/support/knowledgeArticles?${params}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const records = (body.articles ?? []).map(a => ({
+            ExternalID: String(a.id ?? ''),
+            ObjectType: objectName,
+            Fields: a,
+        }));
+        // Knowledge Articles uses page-based pagination. The endpoint doesn't
+        // return a documented total/has-more signal in its body, so treat a
+        // full page as "potentially more" — same defensive pattern used for
+        // SI and YM. Engine loop drives subsequent pages via NextPage; an
+        // empty next-page response terminates naturally. Without this guard
+        // sync silently caps at batchSize records per object — identical to
+        // the SOQL LIMIT bug we already fixed in this session.
+        const hasMore = records.length >= batchSize;
+        return {
+            Records: records,
+            HasMore: hasMore,
+            NextPage: hasMore ? page + 1 : undefined,
+        };
+    }
+    // ─── Bulk API 2.0 (Ingest & Query Jobs) ──────────────────────────
+    /**
+     * Lists in-flight Bulk API 2.0 jobs. Useful for monitoring background
+     * imports/queries the integration previously started.
+     */
+    async FetchBulkJobs(auth, family, objectName) {
+        const segment = family === 'bulk_ingest' ? 'ingest' : 'query';
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/jobs/${segment}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        this.ValidateResponse(response, url);
+        const body = response.Body;
+        const records = (body.records ?? []).map(r => ({
+            ExternalID: String(r.id ?? ''),
+            ObjectType: objectName,
+            Fields: r,
+            ModifiedAt: r.systemModstamp ? new Date(r.systemModstamp) : undefined,
+        }));
+        return {
+            Records: records,
+            HasMore: !body.done,
+            NextCursor: body.nextRecordsUrl ?? undefined,
+        };
+    }
+    /**
+     * Creates (starts) a new Bulk API 2.0 ingest or query job using the
+     * provided attributes. Required fields differ by operation; we pass
+     * attributes straight through to Salesforce after stripping any readonly
+     * fields. For ingest, CSV data is uploaded in a separate request (PUT) —
+     * callers must issue that themselves via UploadBulkData once the job ID
+     * is known.
+     */
+    async CreateBulkJob(auth, family, attrs) {
+        const segment = family === 'bulk_ingest' ? 'ingest' : 'query';
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/jobs/${segment}`;
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const body = this.StripReadOnlyFields(attrs);
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
+        if (response.Status >= 200 && response.Status < 300) {
+            const created = response.Body;
+            return this.BuildCreatedResult(created.id, response.Status, `${family} job`);
+        }
+        return this.BuildCRUDError(response, 'CreateBulkJob', family);
+    }
+    /**
+     * Aborts a running Bulk API 2.0 job by PATCHing state=Aborted.
+     */
+    async AbortBulkJob(auth, family, jobId) {
+        const segment = family === 'bulk_ingest' ? 'ingest' : 'query';
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/jobs/${segment}/${jobId}`;
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const response = await this.MakeHTTPRequest(auth, url, 'PATCH', headers, { state: 'Aborted' });
+        if (response.Status >= 200 && response.Status < 300) {
+            return { Success: true, ExternalID: jobId, StatusCode: response.Status };
+        }
+        return this.BuildCRUDError(response, 'AbortBulkJob', family);
+    }
+    async GetBulkJob(auth, family, jobId) {
+        const segment = family === 'bulk_ingest' ? 'ingest' : 'query';
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/jobs/${segment}/${jobId}`;
+        const headers = this.BuildHeaders(auth);
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status === 404)
+            return null;
+        this.ValidateResponse(response, url);
+        return {
+            ExternalID: jobId,
+            ObjectType: family === 'bulk_ingest' ? 'BulkIngestJob' : 'BulkQueryJob',
+            Fields: response.Body,
+        };
+    }
+    // ─── Composite Requests ──────────────────────────────────────────
+    /**
+     * Executes a composite request — up to 25 sub-requests in one HTTP call.
+     * The `attrs` payload is expected to be the full composite body or at
+     * least a `compositeRequest` array. Returns the overall composite
+     * response as the created record's ExternalID (Salesforce returns
+     * per-sub-request results; callers should inspect Fields for details).
+     *
+     * Salesforce returns HTTP 200 for the OVERALL composite call even when
+     * individual sub-requests fail (the composite envelope carries a
+     * per-sub-request `httpStatusCode`). Blanket-returning Success:true on the
+     * envelope status swallows those sub-request failures. We inspect the
+     * `compositeResponse` array and fail loudly if any sub-request returned a
+     * 4xx/5xx, summarizing the sub-request errors so the caller sees them.
+     */
+    async ExecuteCompositeRequest(auth, attrs) {
+        const url = `${this.ApiBase(auth)}/services/data/v${auth.ApiVersion}/composite`;
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        // Either pass the whole payload through or wrap a bare array
+        const body = Array.isArray(attrs.compositeRequest)
+            ? attrs
+            : { allOrNone: true, compositeRequest: [attrs] };
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
+        if (response.Status >= 200 && response.Status < 300) {
+            const subErrors = this.CollectCompositeSubErrors(response.Body);
+            if (subErrors.length > 0) {
+                return {
+                    Success: false,
+                    StatusCode: response.Status,
+                    ErrorMessage: `[Salesforce] Composite request returned HTTP ${response.Status} but ${subErrors.length} sub-request(s) failed: ${subErrors.join('; ')}`,
+                };
+            }
+            return { Success: true, ExternalID: 'composite', StatusCode: response.Status };
+        }
+        return this.BuildCRUDError(response, 'ExecuteCompositeRequest', 'CompositeRequest');
+    }
+    /**
+     * Inspects a composite response body for per-sub-request failures. A
+     * sub-request failed if its `httpStatusCode` is >= 400. Returns a
+     * human-readable summary string per failed sub-request (empty array when
+     * all sub-requests succeeded or the body has no compositeResponse array).
+     */
+    CollectCompositeSubErrors(responseBody) {
+        const subResponses = responseBody?.compositeResponse;
+        if (!Array.isArray(subResponses))
+            return [];
+        const failures = [];
+        for (const sub of subResponses) {
+            if (typeof sub?.httpStatusCode === 'number' && sub.httpStatusCode >= 400) {
+                failures.push(this.SummarizeCompositeSubError(sub));
+            }
+        }
+        return failures;
+    }
+    /** Formats a single failed composite sub-response into a readable error string. */
+    SummarizeCompositeSubError(sub) {
+        const ref = sub.referenceId ?? '(no referenceId)';
+        const detail = this.ExtractCompositeSubErrorDetail(sub.body);
+        return `${ref} (HTTP ${sub.httpStatusCode})${detail ? `: ${detail}` : ''}`;
+    }
+    /**
+     * Salesforce sub-request error bodies are typically an array of
+     * `{ errorCode, message }`. Pull a concise detail string out of that shape.
+     */
+    ExtractCompositeSubErrorDetail(body) {
+        if (Array.isArray(body)) {
+            return body
+                .map(e => {
+                const err = e;
+                return [err.errorCode, err.message].filter(Boolean).join(': ');
+            })
+                .filter(Boolean)
+                .join(', ');
+        }
+        return '';
+    }
+};
+SalesforceConnector = SalesforceConnector_1 = __decorate([
+    RegisterClass(BaseIntegrationConnector, '@memberjunction/connector-salesforce')
+], SalesforceConnector);
+export { SalesforceConnector };
+//# sourceMappingURL=SalesforceConnector.js.map