@memberjunction/connector-salesforce 1.0.0

package/dist/SalesforceConnector.d.ts

@@ -0,0 +1,460 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity, MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult, type DefaultFieldMapping, type DefaultIntegrationConfig, type ExternalRecord, type CRUDResult, type CreateRecordContext, type UpdateRecordContext, type DeleteRecordContext, type GetRecordContext, type SearchContext, type SearchResult, type SourceSchemaInfo, type IntegrationObjectInfo, type ActionGeneratorConfig, type IntrospectSchemaOptions } from '@memberjunction/integration-engine';
+/** Supported Salesforce auth flows */
+type SalesforceAuthFlow = 'jwt_bearer' | 'client_credentials';
+/** Connection configuration parsed from CompanyIntegration.Configuration JSON */
+export interface SalesforceConnectionConfig {
+    /** Auth flow to use */
+    AuthFlow: SalesforceAuthFlow;
+    /** Salesforce login URL (e.g. https://login.salesforce.com or https://myorg.my.salesforce.com) */
+    LoginUrl: string;
+    /** Connected App Consumer Key */
+    ClientId: string;
+    /** Salesforce REST API version. Default: '61.0' */
+    ApiVersion: string;
+    /** JWT Bearer only — Integration user email */
+    Username?: string;
+    /** JWT Bearer only — PEM-encoded RSA private key */
+    PrivateKey?: string;
+    /** Client Credentials only — Connected App client secret */
+    ClientSecret?: string;
+    /** Optional — token endpoint URL if different from LoginUrl (e.g. My Domain URL for JWT flow) */
+    TokenUrl?: string;
+    /** Maximum retries for rate-limited or failed requests. Default: 5 */
+    MaxRetries?: number;
+    /** HTTP request timeout in milliseconds. Default: 30000 */
+    RequestTimeoutMs?: number;
+    /** Minimum milliseconds between API requests. Default: 100 */
+    MinRequestIntervalMs?: number;
+    /** Batch size for SOQL queries. Default: 2000 */
+    DefaultBatchSize?: number;
+}
+/** Extended auth context carrying Salesforce credentials and cached token */
+interface SalesforceAuthContext extends RESTAuthContext {
+    /** Salesforce instance URL (pod-specific, e.g., https://na1.salesforce.com) */
+    InstanceUrl: string;
+    /** API version string */
+    ApiVersion: string;
+    /** Full config for reference */
+    Config: SalesforceConnectionConfig;
+    /** The CompanyIntegration this auth was built for — lets API URLs route through the
+     *  overridable GetBaseURL() (production returns InstanceUrl; test harnesses redirect to a mock). */
+    CompanyIntegration: MJCompanyIntegrationEntity;
+}
+/**
+ * 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.
+ */
+export declare class SalesforceConnector extends BaseRESTIntegrationConnector {
+    private cachedAuth;
+    private tokenObtainedAt;
+    private lastRequestTime;
+    private governorState;
+    private _config;
+    private get effectiveMaxRetries();
+    private get effectiveRequestTimeoutMs();
+    private get effectiveMinRequestIntervalMs();
+    private get effectiveBatchSize();
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsDelete(): boolean;
+    get SupportsSearch(): boolean;
+    get IntegrationName(): string;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): IntegrationObjectInfo[];
+    GetActionGeneratorConfig(): ActionGeneratorConfig | null;
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ConnectionTestResult>;
+    /**
+     * 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).
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * 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.
+     */
+    private isUserRelevantSObject;
+    /**
+     * Discovers fields on a specific SF object via the Describe API.
+     * Skips compound fields (address, location) — their component fields are included individually.
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * 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.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo, options?: IntrospectSchemaOptions): Promise<SourceSchemaInfo>;
+    private DoIntrospectSchema;
+    private static readonly INTROSPECT_CACHE_TTL_MS;
+    private static readonly introspectCache;
+    /**
+     * 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.
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * 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).
+     */
+    private ResolveAPIFamily;
+    private IsValidFamily;
+    /**
+     * Returns the REST path prefix for an SObject in the given API family.
+     * Used by CRUD operations and field discovery.
+     */
+    private SObjectBasePath;
+    /**
+     * Returns the SOQL query endpoint for the given API family.
+     * Standard uses /query + /queryAll; Tooling uses /tooling/query.
+     */
+    private SOQLEndpoint;
+    /**
+     * 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.
+     */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /**
+     * Updates an existing record in Salesforce (PATCH — only changed fields).
+     * Honors API family routing; Tooling uses `/tooling/sobjects/`, everything
+     * else uses standard `/sobjects/`.
+     */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * 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.
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Retrieves a single record by its Salesforce ID. Routes to the API family
+     * endpoint indicated by IntegrationObject metadata.
+     */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    /**
+     * 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.
+     */
+    SearchRecords(ctx: SearchContext): Promise<SearchResult>;
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SalesforceAuthContext>;
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    protected MakeHTTPRequest(auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    protected NormalizeResponse(rawBody: unknown, _responseDataKey: string | null): Record<string, unknown>[];
+    /**
+     * 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).
+     */
+    protected TransformRecord(raw: Record<string, unknown>, _obj: MJIntegrationObjectEntity, _fields: MJIntegrationObjectFieldEntity[]): Record<string, unknown>;
+    /**
+     * 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).
+     */
+    protected ExcludedSourceKeys(_objectName: string): string[];
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * 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.
+     */
+    private ApiBase;
+    /**
+     * Builds a SOQL query string with optional watermark filter.
+     */
+    private BuildSOQLQuery;
+    /**
+     * 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.
+     */
+    private ExecuteSOQLQuery;
+    /**
+     * Fetches the next page of results using a queryMore locator.
+     */
+    private FetchNextPage;
+    /**
+     * Parses a SOQL query response into a FetchBatchResult.
+     */
+    private ParseSOQLResponse;
+    /**
+     * 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.
+     */
+    private ExtractMaxWatermark;
+    /**
+     * 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.
+     */
+    private GetQueryableFieldNames;
+    /**
+     * Builds a signed JWT assertion for the SF JWT Bearer Token flow.
+     */
+    private BuildJWTAssertion;
+    /**
+     * 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.
+     */
+    private NormalizePem;
+    /**
+     * Exchanges a JWT assertion for an access token at the SF token endpoint.
+     */
+    private ExchangeJWTForToken;
+    /**
+     * Exchanges Client Credentials for an access token.
+     * Used with Connected Apps configured for the OAuth 2.0 Client Credentials flow.
+     */
+    private ExchangeClientCredentialsForToken;
+    /**
+     * Checks if the cached token is still valid (within 80% of lifetime).
+     */
+    private IsTokenValid;
+    /**
+     * Loads credentials from the Credential entity or Configuration JSON.
+     */
+    private LoadCredentials;
+    private LoadFromCredentialEntity;
+    private ParseCredentialJson;
+    private BuildConnectionConfig;
+    private ApplyConfigOverrides;
+    /**
+     * Throttles requests to respect minimum interval between API calls.
+     */
+    private ThrottleIfNeeded;
+    /**
+     * Checks governor limits and pauses if approaching the daily API limit.
+     */
+    private CheckGovernorLimits;
+    /**
+     * Parses the Sforce-Limit-Info header from every SF response.
+     */
+    private ParseGovernorLimits;
+    private FetchWithTimeout;
+    private BuildRESTResponse;
+    private ExtractHeaders;
+    private SafeParseJSON;
+    private CalculateRetryDelay;
+    /**
+     * 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.
+     */
+    private RetryAfterMs;
+    private Sleep;
+    /**
+     * 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.
+     */
+    private MapSFFieldToSchema;
+    /**
+     * Maps a Salesforce field type to a generic integration type.
+     */
+    private MapSalesforceType;
+    /**
+     * Formats a watermark value as a SOQL datetime literal.
+     */
+    private FormatSOQLDateTime;
+    /**
+     * Builds a SOQL WHERE clause from a Filters map.
+     */
+    private BuildWhereClauseFromFilters;
+    /**
+     * Checks if a response contains a specific SF error code.
+     */
+    private HasSFErrorCode;
+    /**
+     * Extracts SF error objects from a response.
+     */
+    private ExtractSFErrors;
+    /**
+     * Checks if a response body contains an UNABLE_TO_LOCK_ROW error.
+     */
+    private IsLockRowError;
+    /**
+     * Builds a CRUDResult for error responses.
+     */
+    private BuildCRUDError;
+    /**
+     * Handles write errors with special retry logic for UNABLE_TO_LOCK_ROW.
+     */
+    private HandleWriteError;
+    /**
+     * 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.
+     */
+    private RawToExternalRecord;
+    /**
+     * Strips read-only and system fields from an attributes map before write operations.
+     */
+    private StripReadOnlyFields;
+    private BuildSourceObjectFromDescribe;
+    private GetContactMappings;
+    private GetAccountMappings;
+    private GetLeadMappings;
+    private ValidateResponse;
+    private PreviewBody;
+    /**
+     * Lists Analytics Reports or Dashboards via the Analytics API. Read-only;
+     * no incremental-sync support at this endpoint.
+     */
+    private FetchAnalyticsList;
+    private AnalyticsItemToRecord;
+    private GetAnalyticsReport;
+    private GetAnalyticsDashboard;
+    /**
+     * 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.
+     */
+    private FetchKnowledgeArticles;
+    /**
+     * Lists in-flight Bulk API 2.0 jobs. Useful for monitoring background
+     * imports/queries the integration previously started.
+     */
+    private FetchBulkJobs;
+    /**
+     * 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.
+     */
+    private CreateBulkJob;
+    /**
+     * Aborts a running Bulk API 2.0 job by PATCHing state=Aborted.
+     */
+    private AbortBulkJob;
+    private GetBulkJob;
+    /**
+     * 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.
+     */
+    private ExecuteCompositeRequest;
+    /**
+     * 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).
+     */
+    private CollectCompositeSubErrors;
+    /** Formats a single failed composite sub-response into a readable error string. */
+    private SummarizeCompositeSubError;
+    /**
+     * Salesforce sub-request error bodies are typically an array of
+     * `{ errorCode, message }`. Pull a concise detail string out of that shape.
+     */
+    private ExtractCompositeSubErrorDetail;
+}
+export {};