@memberjunction/integration-connectors 5.14.0 → 5.16.0

package/dist/SalesforceConnector.js

@@ -4,67 +4,1171 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+import jwt from 'jsonwebtoken';
 import { RegisterClass } from '@memberjunction/global';
-import { BaseIntegrationConnector, } from '@memberjunction/integration-engine';
-import { RelationalDBConnector } from './RelationalDBConnector.js';
-/** Primary key column used across all Salesforce mock tables */
-const SF_ID_FIELD = 'Id';
-/** Modification timestamp column used across Salesforce mock tables */
-const SF_MODIFIED_FIELD = 'LastModifiedDate';
-/** Soft-delete flag column used across all Salesforce mock tables */
-const SF_DELETED_FIELD = 'IsDeleted';
+import { Metadata } from '@memberjunction/core';
+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'];
+// ─── Salesforce Object Metadata for Action Generation ─────────────────
+const SALESFORCE_OBJECTS = [
+    {
+        Name: 'Account', DisplayName: 'Account',
+        Description: 'A company, organization, or consumer in Salesforce CRM', SupportsWrite: true,
+        Fields: [
+            { Name: 'Name', DisplayName: 'Account Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account name' },
+            { Name: 'Industry', DisplayName: 'Industry', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account industry' },
+            { Name: 'Phone', DisplayName: 'Phone', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account phone number' },
+            { Name: 'Website', DisplayName: 'Website', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account website URL' },
+            { Name: 'BillingStreet', DisplayName: 'Billing Street', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Billing street address' },
+            { Name: 'BillingCity', DisplayName: 'Billing City', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Billing city' },
+            { Name: 'BillingState', DisplayName: 'Billing State', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Billing state/province' },
+            { Name: 'BillingPostalCode', DisplayName: 'Billing Postal Code', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Billing postal code' },
+            { Name: 'BillingCountry', DisplayName: 'Billing Country', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Billing country' },
+            { Name: 'Description', DisplayName: 'Description', Type: 'text', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account description' },
+            { Name: 'Type', DisplayName: 'Type', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Account type' },
+            { Name: 'AnnualRevenue', DisplayName: 'Annual Revenue', Type: 'number', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Annual revenue' },
+            { Name: 'NumberOfEmployees', DisplayName: 'Employees', Type: 'number', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Number of employees' },
+            { Name: 'Id', DisplayName: 'Account ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Contact', DisplayName: 'Contact',
+        Description: 'A person associated with an account in Salesforce CRM', SupportsWrite: true,
+        Fields: [
+            { Name: 'Email', DisplayName: 'Email', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact email address' },
+            { Name: 'FirstName', DisplayName: 'First Name', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact first name' },
+            { Name: 'LastName', DisplayName: 'Last Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact last name' },
+            { Name: 'Phone', DisplayName: 'Phone', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact phone number' },
+            { Name: 'MobilePhone', DisplayName: 'Mobile Phone', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mobile phone number' },
+            { Name: 'Title', DisplayName: 'Title', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact title' },
+            { Name: 'Department', DisplayName: 'Department', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact department' },
+            { Name: 'MailingStreet', DisplayName: 'Mailing Street', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mailing street address' },
+            { Name: 'MailingCity', DisplayName: 'Mailing City', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mailing city' },
+            { Name: 'MailingState', DisplayName: 'Mailing State', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mailing state/province' },
+            { Name: 'MailingPostalCode', DisplayName: 'Mailing Postal Code', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mailing postal code' },
+            { Name: 'MailingCountry', DisplayName: 'Mailing Country', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Mailing country' },
+            { Name: 'AccountId', DisplayName: 'Account ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Parent account ID' },
+            { Name: 'Id', DisplayName: 'Contact ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Lead', DisplayName: 'Lead',
+        Description: 'A prospective customer/lead in Salesforce CRM', SupportsWrite: true,
+        Fields: [
+            { Name: 'Email', DisplayName: 'Email', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead email address' },
+            { Name: 'FirstName', DisplayName: 'First Name', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead first name' },
+            { Name: 'LastName', DisplayName: 'Last Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead last name' },
+            { Name: 'Company', DisplayName: 'Company', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead company name' },
+            { Name: 'Phone', DisplayName: 'Phone', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead phone number' },
+            { Name: 'Title', DisplayName: 'Title', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead title' },
+            { Name: 'Status', DisplayName: 'Status', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Lead status' },
+            { Name: 'Id', DisplayName: 'Lead ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Opportunity', DisplayName: 'Opportunity',
+        Description: 'A sales opportunity in Salesforce CRM', SupportsWrite: true,
+        Fields: [
+            { Name: 'Name', DisplayName: 'Opportunity Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Opportunity name' },
+            { Name: 'Amount', DisplayName: 'Amount', Type: 'number', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Opportunity amount' },
+            { Name: 'StageName', DisplayName: 'Stage', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Current stage' },
+            { Name: 'CloseDate', DisplayName: 'Close Date', Type: 'date', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Expected close date' },
+            { Name: 'AccountId', DisplayName: 'Account ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Parent account ID' },
+            { Name: 'Description', DisplayName: 'Description', Type: 'text', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Opportunity description' },
+            { Name: 'Id', DisplayName: 'Opportunity ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Task', DisplayName: 'Task',
+        Description: 'A task or to-do item in Salesforce', SupportsWrite: true,
+        Fields: [
+            { Name: 'Subject', DisplayName: 'Subject', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Task subject' },
+            { Name: 'Status', DisplayName: 'Status', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Task status' },
+            { Name: 'Priority', DisplayName: 'Priority', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Task priority' },
+            { Name: 'WhoId', DisplayName: 'Who ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Related Contact or Lead ID' },
+            { Name: 'WhatId', DisplayName: 'What ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Related Account, Opportunity, etc. ID' },
+            { Name: 'Id', DisplayName: 'Task ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Event', DisplayName: 'Event',
+        Description: 'A calendar event in Salesforce', SupportsWrite: true,
+        Fields: [
+            { Name: 'Subject', DisplayName: 'Subject', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Event subject' },
+            { Name: 'StartDateTime', DisplayName: 'Start', Type: 'datetime', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Event start date/time' },
+            { Name: 'EndDateTime', DisplayName: 'End', Type: 'datetime', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Event end date/time' },
+            { Name: 'WhoId', DisplayName: 'Who ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Related Contact or Lead ID' },
+            { Name: 'Id', DisplayName: 'Event ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Case', DisplayName: 'Case',
+        Description: 'A support case in Salesforce', SupportsWrite: true,
+        Fields: [
+            { Name: 'Subject', DisplayName: 'Subject', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Case subject' },
+            { Name: 'Status', DisplayName: 'Status', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Case status' },
+            { Name: 'Priority', DisplayName: 'Priority', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Case priority' },
+            { Name: 'AccountId', DisplayName: 'Account ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Parent account ID' },
+            { Name: 'ContactId', DisplayName: 'Contact ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Related contact ID' },
+            { Name: 'Description', DisplayName: 'Description', Type: 'text', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Case description' },
+            { Name: 'Id', DisplayName: 'Case ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'Campaign', DisplayName: 'Campaign',
+        Description: 'A marketing campaign in Salesforce', SupportsWrite: true,
+        Fields: [
+            { Name: 'Name', DisplayName: 'Campaign Name', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Campaign name' },
+            { Name: 'Status', DisplayName: 'Status', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Campaign status' },
+            { Name: 'Type', DisplayName: 'Type', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Campaign type' },
+            { Name: 'StartDate', DisplayName: 'Start Date', Type: 'date', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Campaign start date' },
+            { Name: 'EndDate', DisplayName: 'End Date', Type: 'date', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Campaign end date' },
+            { Name: 'Id', DisplayName: 'Campaign ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
+        ],
+    },
+    {
+        Name: 'User', DisplayName: 'User',
+        Description: 'A Salesforce user (reference only, not writable)', SupportsWrite: false,
+        IncludeInActionGeneration: false,
+        Fields: [
+            { Name: 'Username', DisplayName: 'Username', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'User login name' },
+            { Name: 'Name', DisplayName: 'Full Name', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Full name' },
+            { Name: 'Email', DisplayName: 'Email', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'User email' },
+            { Name: 'Id', DisplayName: 'User ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce user ID' },
+        ],
+    },
+];
+// ─── SalesforceConnector ──────────────────────────────────────────────
 /**
- * Connector for Salesforce CRM data, backed by the mock_data database (sf schema).
- * Reads from sf.Contact, sf.Account, and sf.Opportunity tables.
- * Provides default field mappings for Contacts and Accounts to MJ entities.
+ * 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 RelationalDBConnector {
+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 };
+        // ── Pagination state for SOQL queryMore ─────────────────────────
+        this.queryLocator = null;
+        // ── Config ──────────────────────────────────────────────────────
+        this._config = null;
+    }
+    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'; }
+    // ─── Action Metadata ─────────────────────────────────────────────
+    GetIntegrationObjects() {
+        return SALESFORCE_OBJECTS;
+    }
+    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 = `${auth.InstanceUrl}/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 all queryable objects including custom objects (__c).
+     */
+    async DiscoverObjects(companyIntegration, contextUser) {
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${auth.InstanceUrl}/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 ?? [];
+        return sobjects
+            .filter(obj => obj.queryable)
+            .map(obj => ({
+            Name: obj.name,
+            Label: obj.label,
+            Description: obj.custom ? `Custom object: ${obj.label}` : undefined,
+            SupportsIncrementalSync: true,
+            SupportsWrite: obj.createable || obj.updateable,
+        }));
+    }
+    /**
+     * 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 = `${auth.InstanceUrl}/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.
+     */
+    async IntrospectSchema(companyIntegration, contextUser) {
+        const objects = await this.DiscoverObjects(companyIntegration, contextUser);
+        const result = { Objects: [] };
+        for (const obj of objects) {
+            try {
+                const sourceObj = await this.BuildSourceObjectFromDescribe(companyIntegration, contextUser, obj.Name);
+                result.Objects.push(sourceObj);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[Salesforce] Skipping "${obj.Name}" during introspection: ${msg}`);
+            }
+        }
+        return result;
+    }
+    // ─── FetchChanges (SOQL-based — overrides base class entirely) ───
     /**
-     * Fetches a batch of changed records from the specified Salesforce object table.
-     * Uses LastModifiedDate for watermark-based incremental sync.
-     * @param ctx - Fetch context with integration, object, watermark, and batch details
-     * @returns Batch of Salesforce records with pagination info
+     * 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.
      */
     async FetchChanges(ctx) {
-        return this.FetchChangesFromTable(ctx, SF_ID_FIELD, SF_MODIFIED_FIELD, SF_DELETED_FIELD);
+        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
+        const batchSize = ctx.BatchSize || this.effectiveBatchSize;
+        // If we have a queryLocator from a previous call, use queryMore
+        if (this.queryLocator && ctx.CurrentCursor) {
+            return this.FetchNextPage(auth, ctx.CurrentCursor);
+        }
+        // Build and execute SOQL query
+        const fields = await this.GetQueryableFieldNames(auth, ctx.ObjectName);
+        const soql = this.BuildSOQLQuery(ctx.ObjectName, fields, ctx.WatermarkValue, batchSize, true);
+        return this.ExecuteSOQLQuery(auth, soql, ctx.ObjectName);
     }
+    // ─── CRUD Operations ─────────────────────────────────────────────
     /**
-     * Returns suggested default field mappings for known Salesforce objects to MJ entities.
-     * @param objectName - Salesforce object name (e.g., "Contact")
-     * @param _entityName - Target MJ entity name (e.g., "Contacts")
-     * @returns Array of default field mappings
+     * Creates a new record in Salesforce.
      */
+    async CreateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const url = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/sobjects/${ctx.ObjectName}/`;
+        const body = this.StripReadOnlyFields(ctx.Attributes);
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
+        if (response.Status === 201 || (response.Status >= 200 && response.Status < 300)) {
+            const created = response.Body;
+            return {
+                Success: true,
+                ExternalID: created.id ?? '',
+                StatusCode: response.Status,
+            };
+        }
+        return this.BuildCRUDError(response, 'CreateRecord', ctx.ObjectName);
+    }
+    /**
+     * Updates an existing record in Salesforce (PATCH — only changed fields).
+     */
+    async UpdateRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const url = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/sobjects/${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.
+     */
+    async DeleteRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const headers = this.BuildHeaders(auth);
+        const url = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/sobjects/${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.
+     */
+    async GetRecord(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const headers = this.BuildHeaders(auth);
+        const url = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/sobjects/${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.
+     */
+    async SearchRecords(ctx) {
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const fields = await this.GetQueryableFieldNames(auth, ctx.ObjectName);
+        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 = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/query?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 '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,
+        };
+        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++) {
+            const response = await this.FetchWithTimeout(url, method, headers, body);
+            this.lastRequestTime = Date.now();
+            // Parse governor limits from response
+            this.ParseGovernorLimits(response.headers);
+            // Handle 401 — token expired, re-authenticate
+            if (response.status === 401 && attempt === 0) {
+                console.warn('[Salesforce] Token expired (401), re-authenticating...');
+                this.cachedAuth = null;
+                // Caller should re-authenticate; for now return the error
+            }
+            // Handle 429 — rate limited
+            if (response.status === 429) {
+                const delayMs = this.CalculateRetryDelay(attempt);
+                console.warn(`[Salesforce] Rate limited (429), 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 ?? []);
+    }
+    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;
+    }
+    // ─── SOQL Query Engine ───────────────────────────────────────────
+    /**
+     * Builds a SOQL query string with optional watermark filter.
+     */
+    BuildSOQLQuery(objectName, fields, watermarkValue, batchSize, includeDeleted) {
+        const dedupedFields = [...new Set([...REQUIRED_SOQL_FIELDS, ...fields])];
+        let soql = `SELECT ${dedupedFields.join(', ')} FROM ${objectName}`;
+        if (watermarkValue) {
+            soql += ` WHERE SystemModstamp > ${this.FormatSOQLDateTime(watermarkValue)}`;
+        }
+        soql += ' ORDER BY SystemModstamp ASC';
+        soql += ` LIMIT ${batchSize}`;
+        return soql;
+    }
+    /**
+     * Executes a SOQL query and returns records as a FetchBatchResult.
+     */
+    async ExecuteSOQLQuery(auth, soql, objectName) {
+        // Use queryAll to include deleted records (IsDeleted=true)
+        const url = `${auth.InstanceUrl}/services/data/v${auth.ApiVersion}/queryAll?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 = `${auth.InstanceUrl}${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 records = (body.records ?? []).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(body.records ?? []);
+        return {
+            Records: records,
+            HasMore: !body.done,
+            NewWatermarkValue: newWatermark ?? undefined,
+            NextCursor: body.nextRecordsUrl ?? undefined,
+        };
+    }
+    /**
+     * Extracts the maximum SystemModstamp value from a batch of records.
+     */
+    ExtractMaxWatermark(records) {
+        let maxTimestamp = null;
+        for (const record of records) {
+            const raw = record;
+            const stamp = raw['SystemModstamp'];
+            if (stamp && (!maxTimestamp || stamp > maxTimestamp)) {
+                maxTimestamp = stamp;
+            }
+        }
+        return maxTimestamp;
+    }
+    /**
+     * Gets queryable field names for a SF object via the Describe API.
+     */
+    async GetQueryableFieldNames(auth, objectName) {
+        const url = `${auth.InstanceUrl}/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 => 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
+        };
+        return jwt.sign(payload, config.PrivateKey, { algorithm: 'RS256' });
+    }
+    /**
+     * 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.Get('CredentialID');
+        if (credentialID) {
+            const creds = await this.LoadFromCredentialEntity(credentialID, contextUser);
+            if (creds)
+                return creds;
+        }
+        // Fallback: Configuration JSON
+        const configJson = companyIntegration.Get('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) {
+        const md = 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.Get('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);
+    }
+    Sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    // ─── SF Type Mapping ─────────────────────────────────────────────
+    /**
+     * Maps a Salesforce field describe to an ExternalFieldSchema.
+     */
+    MapSFFieldToSchema(f) {
+        return {
+            Name: f.name,
+            Label: f.label,
+            Description: f.inlineHelpText ?? undefined,
+            DataType: this.MapSalesforceType(f.type),
+            IsRequired: !f.nillable && !f.defaultedOnCreate,
+            IsUniqueKey: f.externalId || f.name === 'Id',
+            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 [];
+                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.
+     * Strips the SF `attributes` metadata object from the fields.
+     */
+    RawToExternalRecord(raw, objectType) {
+        const fields = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (key === 'attributes')
+                continue; // 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,
+        };
     }
-    /** Default field mappings: sf_Contact -> Contacts */
-    getContactMappings() {
+    /**
+     * 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 = `${auth.InstanceUrl}/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' },
         ];
     }
-    /** Default field mappings: sf_Account -> Companies */
-    getAccountMappings() {
+    GetAccountMappings() {
         return [
             { SourceFieldName: 'Name', DestinationFieldName: 'Name', IsKeyField: true },
-            { SourceFieldName: 'Industry', DestinationFieldName: 'Industry' },
+            { SourceFieldName: 'BillingStreet', DestinationFieldName: 'Address1' },
             { SourceFieldName: 'BillingCity', DestinationFieldName: 'City' },
-            { SourceFieldName: 'BillingState', DestinationFieldName: 'State' },
+            { 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);
+    }
 };
 SalesforceConnector = __decorate([
     RegisterClass(BaseIntegrationConnector, 'SalesforceConnector')