@memberjunction/integration-connectors 5.40.2 → 5.42.0

package/dist/NimbleAMSConnector.js

@@ -7,128 +7,52 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 /**
  * NimbleAMSConnector — Integration connector for Nimble AMS (Salesforce-native association management).
  *
- * API Documentation:
- *   - Nimble AMS API: https://help.nimbleams.com/help/live/api
- *   - Integration API: https://help.nimbleams.com/help/live/call-the-integration-api
- *   - Object Reference: https://nimbleuser.github.io/nams-api-docs/
+ * Nimble AMS is a Salesforce-native AMS: data lives as Salesforce sObjects — standard SF objects
+ * (Account, Contact) and NU__/NUINT__-prefixed managed-package custom objects (`__c` suffix). The
+ * connector surfaces THREE access doors, each carried on the per-IO `Configuration` from the frozen
+ * contract — never hardcoded here:
+ *
+ *   1. Salesforce REST SOQL — `/services/data/v{apiVersion}/query` with `nextRecordsUrl` cursor
+ *      pagination + `WHERE LastModifiedDate >= :watermark` incremental. The default read door, and
+ *      the write door for sObject CRUD (`/sobjects/{ObjectName}` flat body, path-delete).
+ *   2. Nimble Fuse — POST `/services/apexrest/NUINT/NUIntegrationService`. OUTBOUND reads run a
+ *      named Integration-Setting SOQL and return `{Records, RecordCount, Message}` (null fields are
+ *      OMITTED — missing fields are nullable, NOT a schema error). INBOUND writes are an
+ *      External-ID-keyed JSON upsert returning `{RecordCount, InboundResults:[{...,SalesforceId,
+ *      ErrorMessages}], ErrorMessages}` with per-record partial success.
+ *   3. NAMS LMS REST — `/services/apexrest/nams/api/lms/v1/...` GET with a `lastUpdated` incremental.
  *
- * Auth: Salesforce OAuth 2.0 (Connected App — client_credentials or authorization_code flow)
- * Base URL: https://{instance}.salesforce.com/services/data/v59.0 (Salesforce REST API)
- *           https://{instance}.salesforce.com/services/apexrest/NUINT/NUIntegrationService (Nimble Integration API)
- * Pagination: Salesforce standard — nextRecordsUrl in query results (2000 records/batch)
- * Rate limits: Salesforce org limits (100K API calls/24hr Enterprise, 15K Professional)
- * Incremental: SOQL WHERE LastModifiedDate >= watermark
- * CRUD: Full via Salesforce REST API /sobjects/{objectName}
+ * API Documentation:
+ *   - Nimble AMS API:          https://help.nimbleams.com/help/live/api
+ *   - Call the Integration API: https://help.nimbleams.com/help/live/call-the-integration-api
+ *   - Object Reference:        https://nimbleuser.github.io/nams-api-docs/
  *
- * Nimble AMS Custom Objects (NU__ namespace):
- *   All Nimble AMS objects use the NU__ namespace prefix on the Salesforce platform.
- *   Standard Salesforce objects (Account, Contact) are also used alongside custom objects.
+ * Auth: Salesforce OAuth 2.0 bearer (Connected App; client_credentials or refresh_token grant).
+ * Base URL: the per-org Salesforce instance URL (from the OAuth token response `instance_url`).
  *
- * API Categories:
- *   - Salesforce REST API (implemented) — SOQL queries, sObject CRUD on all NU__ objects
- *   - Nimble Integration API (implemented) — simplified inbound/outbound via named Integration Settings
- *   - Salesforce Bulk API 2.0 (NOT implemented) — for 10K+ record batches
- *   - Salesforce Streaming API (NOT implemented) — real-time CDC via PushTopics/CDC channels
- *   - Salesforce Metadata API (NOT implemented) — schema/config deployment, not data sync
+ * NO BAKED CATALOG. The object/field universe is Declared (credential-free docs → metadata file) +
+ * Discovered (runtime SF global-describe MECHANISM, scoped to the NU__/NUINT__ managed-package
+ * namespace). This file is pure mechanism: auth, HTTP, discover, fetch, normalize, transform, write.
  */
 import { RegisterClass } from '@memberjunction/global';
 import { Metadata } from '@memberjunction/core';
 import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
-// ─── Constants ────────────────────────────────────────────────────────────
-const SF_API_VERSION = 'v59.0';
-// Salesforce platform restricts SOQL `FIELDS(ALL)` to LIMIT <= 200 per query.
-// nextRecordsUrl cursor pagination chains additional batches.
-const SF_PAGE_SIZE = 200;
+// ─── Constants ──────────────────────────────────────────────────────────────
+const DEFAULT_SF_API_VERSION = '59.0';
+const FUSE_PATH = '/services/apexrest/NUINT/NUIntegrationService';
+/** SF managed-package namespaces that scope the global describe to Nimble objects. */
+const NIMBLE_NAMESPACES = ['NU__', 'NUINT__'];
+/** Standard SF objects used by Nimble AMS alongside the managed package. */
+const NIMBLE_STANDARD_OBJECTS = new Set(['Account', 'Contact']);
+/** Nimble Fuse OUTBOUND hard limits per call — 50,000 records OR 3MB, whichever is reached first. */
+const FUSE_MAX_RECORDS_PER_CALL = 50_000;
+const FUSE_MAX_BYTES_PER_CALL = 3 * 1024 * 1024; // 3MB
 const TOKEN_REFRESH_BUFFER_MS = 60_000;
+const TOKEN_LIFETIME_MS = 3_600_000;
 const MAX_RETRIES = 3;
 const REQUEST_TIMEOUT_MS = 30_000;
 const MIN_REQUEST_INTERVAL_MS = 50;
-// ─── Nimble AMS Objects (NU__ namespace + standard SF objects) ─────────────
-// Lean overlay: PK + key FKs + date fields. Full field list from Salesforce describe API at runtime.
-const NIMBLE_OBJECTS = [
-    // Standard Salesforce objects used by Nimble AMS
-    { Name: 'Account', DisplayName: 'Account', Description: 'Organization/company accounts', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
-            { Name: 'LastModifiedDate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Incremental date' },
-        ] },
-    { Name: 'Contact', DisplayName: 'Contact', Description: 'Individual contacts/members', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Salesforce record ID' },
-            { Name: 'AccountId', DisplayName: 'Account ID', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-            { Name: 'LastModifiedDate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Incremental date' },
-        ] },
-    // Nimble AMS custom objects (NU__ namespace)
-    { Name: 'NU__Membership__c', DisplayName: 'Membership', Description: 'Membership records', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Account__c', DisplayName: 'Account', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-            { Name: 'LastModifiedDate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Incremental date' },
-        ] },
-    { Name: 'NU__MembershipType__c', DisplayName: 'Membership Type', Description: 'Membership type definitions', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-    { Name: 'NU__Event__c', DisplayName: 'Event', Description: 'Events and conferences', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'LastModifiedDate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Incremental date' },
-        ] },
-    { Name: 'NU__EventRegistration__c', DisplayName: 'Event Registration', Description: 'Event registrations', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Event__c', DisplayName: 'Event', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Event' },
-            { Name: 'NU__Contact__c', DisplayName: 'Contact', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Contact' },
-        ] },
-    { Name: 'NU__Order__c', DisplayName: 'Order', Description: 'Sales orders', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Account__c', DisplayName: 'Account', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-            { Name: 'LastModifiedDate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Incremental date' },
-        ] },
-    { Name: 'NU__OrderItem__c', DisplayName: 'Order Item', Description: 'Order line items', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Order__c', DisplayName: 'Order', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Order' },
-        ] },
-    { Name: 'NU__Payment__c', DisplayName: 'Payment', Description: 'Payment records', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Order__c', DisplayName: 'Order', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Order' },
-        ] },
-    { Name: 'NU__Invoice__c', DisplayName: 'Invoice', Description: 'Invoices', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Account__c', DisplayName: 'Account', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-        ] },
-    { Name: 'NU__Committee__c', DisplayName: 'Committee', Description: 'Committees and boards', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-    { Name: 'NU__CommitteeMembership__c', DisplayName: 'Committee Member', Description: 'Committee membership records', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Committee__c', DisplayName: 'Committee', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Committee' },
-            { Name: 'NU__Contact__c', DisplayName: 'Contact', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Contact' },
-        ] },
-    { Name: 'NU__Donation__c', DisplayName: 'Donation', Description: 'Donation/gift records', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Account__c', DisplayName: 'Account', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-        ] },
-    { Name: 'NU__Product__c', DisplayName: 'Product', Description: 'Products/items for sale', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-    { Name: 'NU__Badge__c', DisplayName: 'Badge', Description: 'Badges/certifications', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-    { Name: 'NU__Subscription__c', DisplayName: 'Subscription', Description: 'Publication subscriptions', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Account__c', DisplayName: 'Account', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Account' },
-        ] },
-    { Name: 'NU__Campaign__c', DisplayName: 'Campaign', Description: 'Fundraising campaigns', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-    { Name: 'NU__Session__c', DisplayName: 'Session', Description: 'Event sessions', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Event__c', DisplayName: 'Event', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Event' },
-        ] },
-    { Name: 'NU__Credential__c', DisplayName: 'Credential', Description: 'Professional credentials/certifications', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-            { Name: 'NU__Contact__c', DisplayName: 'Contact', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'FK → Contact' },
-        ] },
-    { Name: 'NU__Chapter__c', DisplayName: 'Chapter', Description: 'Chapters/branches', SupportsWrite: true, Fields: [
-            { Name: 'Id', DisplayName: 'ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'Record ID' },
-        ] },
-];
-// ─── Connector ────────────────────────────────────────────────────────────
+// ─── Connector ──────────────────────────────────────────────────────────────
 let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationConnector {
     constructor() {
         super(...arguments);
@@ -136,103 +60,188 @@ let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationCon
         this.lastRequestTime = 0;
     }
     get IntegrationName() { return 'Nimble AMS'; }
+    // Capability getters reflect the contract: writeable objects expose SF-REST sObject CRUD
+    // (Create/Update/Delete) and Fuse upsert (Create/Update). The per-IO write columns gate which
+    // verb actually fires; these getters declare the connector CAN write where metadata says so.
     get SupportsCreate() { return true; }
     get SupportsUpdate() { return true; }
     get SupportsDelete() { return true; }
-    GetIntegrationObjects() { return NIMBLE_OBJECTS; }
-    GetActionGeneratorConfig() {
-        const config = super.GetActionGeneratorConfig();
-        if (!config)
-            return null;
-        config.IconClass = 'fa-solid fa-id-badge';
-        config.CategoryDescription = 'Nimble AMS (Salesforce-native) for memberships, events, orders, and donations';
-        config.ParentCategoryName = 'Association Management';
-        config.IncludeSearch = true;
-        config.IncludeList = true;
-        return config;
-    }
-    // ─── Discovery ─────────────────────────────────────────────────────
+    /**
+     * AUTHORITATIVE discovery (§ deactivation gate): the live SF global describe returns the FULL set
+     * of NU__/NUINT__ + standard objects the credential can see, so absence on a later refresh genuinely
+     * means the source dropped it. The Declared baseline plus the describe extension are the complete
+     * gamut for the scoped namespace.
+     */
+    get DiscoveryIsAuthoritative() { return true; }
+    /**
+     * Route schema introspection through the connector's LIVE SF global-describe discovery.
+     *
+     * `BaseRESTIntegrationConnector` (our parent) overrides the grandparent's real discover loop with a
+     * CACHE-DRIVEN `IntrospectSchema` that re-reads persisted ACTIVE metadata and is hard-coded
+     * non-authoritative — so it never calls our `DiscoverObjects`/`DiscoverFields` and can never drive
+     * the authoritative deactivation overlay. Nimble HAS live describe-backed discovery (and declares
+     * `DiscoveryIsAuthoritative = true`), so we invoke the grandparent `BaseIntegrationConnector`
+     * implementation directly. It calls `this.DiscoverObjects` → `this.DiscoverFields` per object and
+     * sets `IsAuthoritative` from our getter, so the full field set is discovered and absent
+     * objects/fields deactivate (reversibly) on a comprehensive refresh.
+     */
+    async IntrospectSchema(companyIntegration, contextUser, options) {
+        return BaseIntegrationConnector.prototype.IntrospectSchema.call(this, companyIntegration, contextUser, options);
+    }
+    // ── §7 sync-efficiency hooks ─────────────────────────────────────────────
+    /** Salesforce REST is monotonic when we ORDER BY the watermark column — narrow the next incremental. */
+    get MonotonicWatermark() { return true; }
+    /** Every Nimble sObject carries the immutable 18-char `Id`; the LMS REST objects carry `id`. */
+    StableOrderingKey(objectName) {
+        return objectName.startsWith('Lms') ? 'id' : 'Id';
+    }
+    /**
+     * Salesforce enforces a per-org rolling 24h API-call cap (Enterprise ~100k/day) rather than a
+     * tokens/sec rate — a conservative sustained rate keeps the connector well clear of the daily cap.
+     */
+    get RateLimitPolicy() {
+        return { TokensPerSec: 20, Burst: 25, ThrottleBackoffFactor: 0.5 };
+    }
+    /** Salesforce 429 / REQUEST_LIMIT_EXCEEDED → honor the standard `Retry-After` header (seconds). */
+    ExtractRetryAfterMs(error) {
+        if (!error || typeof error !== 'object')
+            return undefined;
+        const headers = error.Headers;
+        const ra = headers?.['retry-after'];
+        if (ra) {
+            const secs = Number(ra);
+            if (!isNaN(secs))
+                return secs * 1000;
+        }
+        return undefined;
+    }
+    // ── Discovery (runtime SF global-describe MECHANISM, namespace-scoped) ────
     async DiscoverObjects(companyIntegration, contextUser) {
-        // Try Salesforce describe API for dynamic discovery of NU__ objects
-        try {
-            const auth = await this.Authenticate(companyIntegration, contextUser);
-            const headers = this.BuildHeaders(auth);
-            const url = `${auth.InstanceURL}/services/data/${auth.ApiVersion}/sobjects`;
-            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
-            if (response.Status === 200) {
-                const body = response.Body;
-                const results = [];
-                for (const obj of (body.sobjects ?? [])) {
-                    // Include NU__ namespace objects + standard objects used by Nimble
-                    if (obj.name.startsWith('NU__') || ['Account', 'Contact', 'Lead', 'Opportunity', 'Campaign'].includes(obj.name)) {
-                        if (obj.queryable) {
-                            results.push({
-                                Name: obj.name, Label: obj.label, Description: `${obj.label} (Nimble AMS)`,
-                                SupportsIncrementalSync: true, SupportsWrite: obj.createable || obj.updateable,
-                            });
-                        }
-                    }
-                }
-                if (results.length > 0)
-                    return results;
-            }
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${this.SFDataBase(auth)}/sobjects/`;
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', this.BuildHeaders(auth));
+        if (response.Status < 200 || response.Status >= 300) {
+            throw new Error(`Nimble AMS DiscoverObjects failed: HTTP ${response.Status} at ${url}`);
         }
-        catch { /* Fall through to static */ }
-        return NIMBLE_OBJECTS.map(obj => ({
-            Name: obj.Name, Label: obj.DisplayName, Description: obj.Description,
-            SupportsIncrementalSync: true, SupportsWrite: obj.SupportsWrite ?? false,
-        }));
+        const body = response.Body;
+        const results = [];
+        for (const obj of (body.sobjects ?? [])) {
+            if (!obj.queryable)
+                continue;
+            if (!this.IsNimbleScopedObject(obj.name))
+                continue;
+            results.push({
+                Name: obj.name,
+                Label: obj.label,
+                Description: `${obj.label} (Nimble AMS)`,
+                SupportsIncrementalSync: true,
+                SupportsWrite: obj.createable || obj.updateable,
+            });
+        }
+        return results;
     }
     async DiscoverFields(companyIntegration, objectName, contextUser) {
-        // Salesforce describe endpoint for field metadata
-        try {
-            const auth = await this.Authenticate(companyIntegration, contextUser);
-            const headers = this.BuildHeaders(auth);
-            const url = `${auth.InstanceURL}/services/data/${auth.ApiVersion}/sobjects/${objectName}/describe`;
-            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
-            if (response.Status === 200) {
-                const body = response.Body;
-                return (body.fields ?? []).map(f => ({
-                    Name: f.name, Label: f.label, Description: '', DataType: this.MapSFType(f.type),
-                    IsRequired: !f.nillable, IsUniqueKey: f.name === 'Id' || f.unique, IsReadOnly: !f.createable && !f.updateable,
-                }));
-            }
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const url = `${this.SFDataBase(auth)}/sobjects/${encodeURIComponent(objectName)}/describe`;
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', this.BuildHeaders(auth));
+        if (response.Status < 200 || response.Status >= 300) {
+            throw new Error(`Nimble AMS DiscoverFields failed for "${objectName}": HTTP ${response.Status}`);
         }
-        catch { /* Fall through to static */ }
-        const obj = NIMBLE_OBJECTS.find(o => o.Name.toLowerCase() === objectName.toLowerCase());
-        if (!obj)
-            return [];
-        return obj.Fields.map(f => ({ Name: f.Name, Label: f.DisplayName, Description: f.Description, DataType: f.Type, IsRequired: f.IsRequired, IsUniqueKey: f.IsPrimaryKey, IsReadOnly: f.IsReadOnly }));
+        const body = response.Body;
+        return (body.fields ?? []).map(f => {
+            const schema = {
+                Name: f.name,
+                Label: f.label,
+                Description: '',
+                DataType: this.MapSFType(f.type),
+                // SF describe states create-time required via `nillable=false` (provable from the source).
+                IsRequired: f.nillable === false,
+                // Provable-only: the SF `id` system field is the PK; uniqueness alone is NOT PK.
+                IsPrimaryKey: f.type === 'id',
+                IsUniqueKey: f.type === 'id' || f.unique === true,
+                IsReadOnly: !f.createable && !f.updateable,
+            };
+            // Bounded typing — propagate the source's length/precision/scale when present.
+            if (typeof f.length === 'number' && f.length > 0)
+                schema.MaxLength = f.length;
+            if (typeof f.precision === 'number' && f.precision > 0)
+                schema.Precision = f.precision;
+            if (typeof f.scale === 'number' && f.scale >= 0)
+                schema.Scale = f.scale;
+            return schema;
+        });
+    }
+    /** A SF API name is in Nimble scope iff it is a managed-package object or a standard AMS object. */
+    IsNimbleScopedObject(name) {
+        if (NIMBLE_STANDARD_OBJECTS.has(name))
+            return true;
+        return NIMBLE_NAMESPACES.some(ns => name.startsWith(ns));
     }
     MapSFType(sfType) {
         const map = {
-            'id': 'string', 'string': 'string', 'textarea': 'string', 'url': 'string', 'email': 'string', 'phone': 'string',
-            'boolean': 'boolean', 'int': 'number', 'double': 'decimal', 'currency': 'decimal', 'percent': 'decimal',
-            'date': 'datetime', 'datetime': 'datetime', 'reference': 'string', 'picklist': 'string', 'multipicklist': 'string',
+            id: 'string', string: 'string', textarea: 'string', url: 'string', email: 'string', phone: 'string',
+            boolean: 'boolean', int: 'number', double: 'decimal', currency: 'decimal', percent: 'decimal',
+            date: 'datetime', datetime: 'datetime', time: 'string', reference: 'string',
+            picklist: 'string', multipicklist: 'string', base64: 'string', anyType: 'string', address: 'string',
         };
         return map[sfType] ?? 'string';
     }
-    // ─── Auth ──────────────────────────────────────────────────────────
+    // ── Auth (Salesforce OAuth2 bearer) ──────────────────────────────────────
     async Authenticate(companyIntegration, contextUser) {
         const config = await this.ParseConfig(companyIntegration, contextUser);
         if (this.tokenCache && this.tokenCache.ExpiresAt > Date.now() + TOKEN_REFRESH_BUFFER_MS) {
-            return { Token: this.tokenCache.AccessToken, TokenType: 'Bearer', Config: config, InstanceURL: config.InstanceURL, ApiVersion: SF_API_VERSION };
+            return this.BuildAuthContext(config, this.tokenCache.AccessToken, this.tokenCache.InstanceURL);
         }
         const token = await this.ObtainToken(config);
         this.tokenCache = token;
-        return { Token: token.AccessToken, TokenType: 'Bearer', Config: config, InstanceURL: config.InstanceURL, ApiVersion: SF_API_VERSION };
+        return this.BuildAuthContext(config, token.AccessToken, token.InstanceURL);
+    }
+    BuildAuthContext(config, accessToken, instanceURL) {
+        return {
+            Token: accessToken,
+            TokenType: 'Bearer',
+            Config: config,
+            InstanceURL: instanceURL,
+            ApiVersion: config.ApiVersion,
+        };
     }
     async ObtainToken(config) {
-        const tokenURL = `${config.InstanceURL}/services/oauth2/token`;
-        const body = new URLSearchParams({ grant_type: 'client_credentials', client_id: config.ClientID, client_secret: config.ClientSecret });
-        const response = await fetch(tokenURL, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: body.toString(), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        // Pre-provisioned access token (e.g. test/broker injection) — use as-is, no exchange.
+        if (config.AccessToken && config.InstanceURL) {
+            return { AccessToken: config.AccessToken, InstanceURL: config.InstanceURL, ExpiresAt: Date.now() + TOKEN_LIFETIME_MS };
+        }
+        const tokenURL = `${config.LoginURL.replace(/\/+$/, '')}/services/oauth2/token`;
+        const params = { client_id: config.ClientID };
+        if (config.RefreshToken) {
+            params['grant_type'] = 'refresh_token';
+            params['refresh_token'] = config.RefreshToken;
+            if (config.ClientSecret)
+                params['client_secret'] = config.ClientSecret;
+        }
+        else {
+            if (!config.ClientSecret)
+                throw new Error('Nimble AMS auth requires either a refresh_token or a client_secret.');
+            params['grant_type'] = 'client_credentials';
+            params['client_secret'] = config.ClientSecret;
+        }
+        const body = new URLSearchParams(params);
+        const response = await fetch(tokenURL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
         if (!response.ok)
-            throw new Error(`Nimble AMS auth failed: ${response.status}`);
+            throw new Error(`Nimble AMS auth failed: HTTP ${response.status}`);
         const data = await response.json();
-        return { AccessToken: data.access_token, ExpiresAt: Date.now() + (3600 * 1000) };
+        // Salesforce returns the org instance_url in the token response — it is the authoritative origin.
+        const instanceURL = data.instance_url ?? config.InstanceURL;
+        if (!instanceURL)
+            throw new Error('Nimble AMS auth response carried no instance_url and none was configured.');
+        return { AccessToken: data.access_token, InstanceURL: instanceURL, ExpiresAt: Date.now() + TOKEN_LIFETIME_MS };
     }
     async ParseConfig(companyIntegration, contextUser, provider) {
-        // Use the typed property — never .Get()/.Set() on entity-typed objects (CLAUDE.md §2b).
+        const fromConfigJSON = this.ParseConfigJSON(companyIntegration.Configuration);
         const credentialID = companyIntegration.CredentialID;
         if (credentialID) {
             const md = provider ?? new Metadata();
@@ -240,112 +249,382 @@ let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationCon
             const loaded = await credential.Load(credentialID);
             if (loaded && credential.Values) {
                 const parsed = JSON.parse(credential.Values);
-                return { InstanceURL: parsed['InstanceURL'] ?? '', ClientID: parsed['ClientID'] ?? parsed['clientId'] ?? '', ClientSecret: parsed['ClientSecret'] ?? parsed['clientSecret'] ?? '', AccessToken: parsed['AccessToken'], RefreshToken: parsed['RefreshToken'] };
+                return this.BuildConfig(parsed, fromConfigJSON);
             }
         }
-        throw new Error('No Nimble AMS credentials found.');
+        if (fromConfigJSON)
+            return this.BuildConfig(fromConfigJSON, null);
+        throw new Error('No Nimble AMS credentials found — set the Credential entity or Configuration JSON.');
+    }
+    ParseConfigJSON(json) {
+        if (!json)
+            return null;
+        try {
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    BuildConfig(creds, configJSON) {
+        const pick = (...keys) => {
+            for (const k of keys) {
+                if (creds[k])
+                    return creds[k];
+                if (configJSON && configJSON[k])
+                    return configJSON[k];
+            }
+            return undefined;
+        };
+        return {
+            InstanceURL: pick('InstanceURL', 'instanceUrl', 'instance_url') ?? '',
+            ClientID: pick('ClientID', 'clientId', 'client_id') ?? '',
+            ClientSecret: pick('ClientSecret', 'clientSecret', 'client_secret'),
+            AccessToken: pick('AccessToken', 'accessToken', 'access_token'),
+            RefreshToken: pick('RefreshToken', 'refreshToken', 'refresh_token'),
+            LoginURL: pick('LoginURL', 'loginUrl', 'login_url') ?? 'https://login.salesforce.com',
+            ApiVersion: this.NormalizeApiVersion(pick('SalesforceAPIVersion', 'ApiVersion', 'apiVersion')),
+        };
+    }
+    /** Accept "59.0" or "v59.0"; the SF data path embeds it as `v{version}`. Store the bare number. */
+    NormalizeApiVersion(raw) {
+        if (!raw)
+            return DEFAULT_SF_API_VERSION;
+        return raw.replace(/^v/i, '');
     }
-    // ─── TestConnection ────────────────────────────────────────────────
+    // ── TestConnection ───────────────────────────────────────────────────────
     async TestConnection(companyIntegration, contextUser) {
         try {
             const auth = await this.Authenticate(companyIntegration, contextUser);
-            const headers = this.BuildHeaders(auth);
-            const response = await this.MakeHTTPRequest(auth, `${auth.InstanceURL}/services/data/${auth.ApiVersion}/sobjects`, 'GET', headers);
-            if (response.Status === 200)
+            const response = await this.MakeHTTPRequest(auth, `${this.SFDataBase(auth)}/sobjects/`, 'GET', this.BuildHeaders(auth));
+            if (response.Status >= 200 && response.Status < 300)
                 return { Success: true, Message: 'Connected to Nimble AMS (Salesforce)' };
-            return { Success: false, Message: `API returned ${response.Status}` };
+            return { Success: false, Message: `Nimble AMS API returned HTTP ${response.Status}` };
         }
         catch (err) {
             return { Success: false, Message: err instanceof Error ? err.message : String(err) };
         }
     }
-    // ─── URL / Response / Pagination ───────────────────────────────────
+    // ── URL / Response / Pagination ──────────────────────────────────────────
     GetBaseURL(_ci, auth) {
-        const a = auth;
-        return `${a.InstanceURL}/services/data/${a.ApiVersion}`;
+        return auth.InstanceURL;
     }
-    BuildPaginatedURL(basePath, _obj, _page, _offset, cursor) {
-        return cursor ?? basePath;
+    /** The instance origin for all REST calls. Routes through GetBaseURL so a test harness can redirect. */
+    Origin(auth) {
+        return this.GetBaseURL(undefined, auth);
     }
+    /** The `/services/data/v{version}` base for all Salesforce REST calls. */
+    SFDataBase(auth) {
+        return `${this.Origin(auth)}/services/data/v${auth.ApiVersion}`;
+    }
+    /** Strip the SF `attributes` envelope blob from every record (sanctioned, declared removal). */
+    TransformRecord(raw, _obj, _fields) {
+        if (!('attributes' in raw))
+            return raw;
+        const out = { ...raw };
+        delete out['attributes'];
+        return out;
+    }
+    ExcludedSourceKeys(_objectName) {
+        return ['attributes'];
+    }
+    /**
+     * Strip the response envelope to expose individual records. Handles all three doors:
+     *  - SF SOQL  → `body.records`
+     *  - Fuse out → `body.Records` (note: PascalCase; null fields omitted per record)
+     *  - LMS REST → root array or single object
+     */
     NormalizeResponse(rawBody, _key) {
         if (Array.isArray(rawBody))
             return rawBody;
+        if (!rawBody || typeof rawBody !== 'object')
+            return [];
         const body = rawBody;
         if (Array.isArray(body['records']))
             return body['records'];
-        if (body && Object.keys(body).length > 0)
-            return [body];
-        return [];
+        if (Array.isArray(body['Records']))
+            return body['Records'];
+        // A single non-enveloped record (e.g. LMS get-one) — pass through as one record.
+        return [body];
     }
     ExtractPaginationInfo(rawBody, _pt, _cp, _co, _ps) {
         const body = rawBody;
-        return { HasMore: !body.done, NextCursor: body.nextRecordsUrl };
+        return { HasMore: body?.done === false, NextCursor: body?.nextRecordsUrl };
     }
-    // ─── FetchChanges — SOQL-based ─────────────────────────────────────
+    // ── FetchChanges (door-aware) ────────────────────────────────────────────
     async FetchChanges(ctx) {
+        const obj = this.GetCachedObject(ctx.CompanyIntegration.IntegrationID, ctx.ObjectName);
+        const cfg = this.ReadAccessConfig(obj);
+        const family = cfg.Family ?? '';
+        if (family === 'FuseEndpoint') {
+            // The Fuse endpoint IO is a contract descriptor, not a queryable record type — nothing to pull.
+            return { Records: [], HasMore: false, Warnings: [{ Code: 'NON_QUERYABLE', Message: `"${ctx.ObjectName}" is the Fuse contract descriptor; it carries no syncable records.` }] };
+        }
+        if (family === 'LmsFamily') {
+            return this.FetchLMS(ctx, obj);
+        }
+        // Default door: Salesforce REST SOQL (also used by the Fuse outbound named-SOQL setting when one
+        // is configured — the SOQL path is the credential-free-verifiable common case).
+        return this.FetchSOQL(ctx, obj);
+    }
+    /** Salesforce REST SOQL fetch — cursor pagination via nextRecordsUrl + watermark-ordered incremental. */
+    async FetchSOQL(ctx, obj) {
         const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
         const headers = this.BuildHeaders(auth);
-        let soql = `SELECT FIELDS(ALL) FROM ${ctx.ObjectName} ORDER BY LastModifiedDate ASC LIMIT ${SF_PAGE_SIZE}`;
-        if (ctx.WatermarkValue) {
-            soql = `SELECT FIELDS(ALL) FROM ${ctx.ObjectName} WHERE LastModifiedDate >= ${ctx.WatermarkValue} ORDER BY LastModifiedDate ASC LIMIT ${SF_PAGE_SIZE}`;
-        }
+        const watermarkField = obj.IncrementalWatermarkField ?? 'LastModifiedDate';
+        // Follow the SF cursor when present; otherwise build the first SOQL page.
         const url = ctx.CurrentCursor
-            ? `${auth.InstanceURL}${ctx.CurrentCursor}`
-            : `${auth.InstanceURL}/services/data/${auth.ApiVersion}/query?q=${encodeURIComponent(soql)}`;
+            ? `${this.GetBaseURL(ctx.CompanyIntegration, auth)}${ctx.CurrentCursor}`
+            : `${this.SFDataBase(auth)}/query?q=${encodeURIComponent(this.BuildSOQL(ctx.ObjectName, watermarkField, ctx.WatermarkValue ?? null))}`;
         const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
-        if (response.Status < 200 || response.Status >= 300)
-            throw new Error(`Nimble AMS SOQL error: ${response.Status}`);
+        if (response.Status < 200 || response.Status >= 300) {
+            throw new Error(`Nimble AMS SOQL error for "${ctx.ObjectName}": HTTP ${response.Status} — ${this.SafeBody(response)}`);
+        }
         const body = response.Body;
-        const records = body.records ?? [];
-        const externalRecords = records.map(r => ({ ExternalID: String(r['Id'] ?? ''), ObjectType: ctx.ObjectName, Fields: r }));
+        const raw = body.records ?? [];
+        // Defensive: the Fuse OUTBOUND door caps a single call at 50,000 records; SF native paging
+        // (≤2000/page) keeps SOQL pages well under it, so a page at/over the cap signals a misconfig.
+        const warnings = raw.length >= FUSE_MAX_RECORDS_PER_CALL
+            ? [{ Code: 'PAGE_AT_RECORD_CAP', Message: `"${ctx.ObjectName}" returned ${raw.length} records in one page — at/over the ${FUSE_MAX_RECORDS_PER_CALL}-record Fuse per-call cap.` }]
+            : undefined;
+        const records = raw.map(r => this.RawToExternalRecord(r, obj, ctx.ObjectName, watermarkField, 'Id'));
+        // Watermark advances ONLY on the final page (full-batch success), and only to the max seen.
         let newWatermark;
         if (body.done) {
-            for (const r of records) {
-                const mod = r['LastModifiedDate'];
-                if (mod && (!newWatermark || mod > newWatermark))
+            for (const r of raw) {
+                const mod = r[watermarkField];
+                if (typeof mod === 'string' && (!newWatermark || mod > newWatermark))
                     newWatermark = mod;
             }
         }
-        return { Records: externalRecords, HasMore: !body.done, NextCursor: body.nextRecordsUrl, NewWatermarkValue: body.done ? newWatermark : undefined };
+        return {
+            Records: records,
+            HasMore: body.done === false,
+            NextCursor: body.nextRecordsUrl,
+            NewWatermarkValue: body.done ? newWatermark : undefined,
+            Warnings: warnings,
+        };
     }
-    // ─── CRUD ──────────────────────────────────────────────────────────
-    async CreateRecord(ctx) {
+    /**
+     * Build the SOQL for the first page. CRITICAL: NO `LIMIT` — Salesforce natively paginates via
+     * done/nextRecordsUrl, so a SOQL LIMIT would cap the ENTIRE result set and SF would report
+     * done=true at that count, silently dropping every record past the limit AND advancing the
+     * watermark past them next sync. Use `>=` (not `>`) so records at the exact watermark instant
+     * aren't lost; engine dedupe absorbs the boundary re-fetch. ORDER BY the watermark for monotonicity.
+     */
+    BuildSOQL(objectName, watermarkField, watermarkValue) {
+        let soql = `SELECT FIELDS(ALL) FROM ${objectName}`;
+        if (watermarkValue)
+            soql += ` WHERE ${watermarkField} >= ${this.FormatSOQLDateTime(watermarkValue)}`;
+        soql += ` ORDER BY ${watermarkField} ASC`;
+        return soql;
+    }
+    /** SF SOQL datetime literals are unquoted ISO-8601 (e.g. 2026-01-01T00:00:00Z). */
+    FormatSOQLDateTime(value) {
+        // Already an unquoted ISO literal → use verbatim; otherwise emit a UTC ISO string.
+        if (/^\d{4}-\d{2}-\d{2}T/.test(value))
+            return value.endsWith('Z') || /[+-]\d{2}:\d{2}$/.test(value) ? value : `${value}Z`;
+        const d = new Date(value);
+        return isNaN(d.getTime()) ? value : d.toISOString();
+    }
+    /** NAMS LMS REST fetch — GET with an optional `lastUpdated` incremental filter (no pagination). */
+    async FetchLMS(ctx, obj) {
         const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
+        const headers = this.BuildHeaders(auth);
+        const watermarkField = obj.IncrementalWatermarkField ?? 'lastUpdated';
+        const base = `${this.GetBaseURL(ctx.CompanyIntegration, auth)}${obj.APIPath}`;
+        const url = ctx.WatermarkValue
+            ? `${base}?${encodeURIComponent(watermarkField)}=${encodeURIComponent(ctx.WatermarkValue)}`
+            : base;
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300) {
+            throw new Error(`Nimble AMS LMS error for "${ctx.ObjectName}": HTTP ${response.Status} — ${this.SafeBody(response)}`);
+        }
+        const raw = this.NormalizeResponse(response.Body, null);
+        const records = raw.map(r => this.RawToExternalRecord(r, obj, ctx.ObjectName, watermarkField, 'id'));
+        let newWatermark;
+        for (const r of raw) {
+            const mod = r[watermarkField];
+            if (typeof mod === 'string' && (!newWatermark || mod > newWatermark))
+                newWatermark = mod;
+        }
+        // LMS REST returns the full set in one response (no cursor) → batch is always complete.
+        return { Records: records, HasMore: false, NewWatermarkValue: newWatermark };
+    }
+    // ── CRUD (door-aware: Fuse inbound upsert vs Salesforce REST sObject) ─────
+    async CreateRecord(ctx) {
+        const ci = ctx.CompanyIntegration;
+        const obj = this.GetCachedObject(ci.IntegrationID, ctx.ObjectName);
+        if (this.IsFuseWritePath(obj)) {
+            return this.FuseUpsert(ctx.ContextUser, ci, obj, ctx.ObjectName, ctx.Attributes, /*forUpdate*/ false);
+        }
+        return this.SFRestCreate(ctx.ContextUser, ci, ctx.ObjectName, ctx.Attributes, obj);
+    }
+    async UpdateRecord(ctx) {
+        const ci = ctx.CompanyIntegration;
+        const obj = this.GetCachedObject(ci.IntegrationID, ctx.ObjectName);
+        if (this.IsFuseWritePath(obj)) {
+            // Fuse is upsert-keyed by External ID — the External ID rides in the record body, not the path.
+            const result = await this.FuseUpsert(ctx.ContextUser, ci, obj, ctx.ObjectName, ctx.Attributes, /*forUpdate*/ true);
+            // For update we report the supplied ExternalID on success (Fuse returns the SalesforceId).
+            return result.Success ? { Success: true, StatusCode: result.StatusCode, ExternalID: result.ExternalID ?? ctx.ExternalID } : result;
+        }
+        return this.SFRestUpdate(ctx.ContextUser, ci, ctx.ObjectName, ctx.ExternalID, ctx.Attributes, obj);
+    }
+    async DeleteRecord(ctx) {
+        const ci = ctx.CompanyIntegration;
+        const obj = this.GetCachedObject(ci.IntegrationID, ctx.ObjectName);
+        if (!obj.DeleteAPIPath || !obj.DeleteMethod) {
+            return { Success: false, StatusCode: 0, ErrorMessage: `DeleteRecord not supported for "${ctx.ObjectName}": Fuse is upsert-only; hard delete requires Salesforce REST sObject DELETE, which this object does not declare.` };
+        }
+        const auth = await this.Authenticate(ci, ctx.ContextUser);
+        const url = this.ResolveSFRestPath(auth, obj.DeleteAPIPath, ctx.ObjectName, ctx.ExternalID);
+        const response = await this.MakeHTTPRequest(auth, url, obj.DeleteMethod, this.BuildHeaders(auth));
+        if (response.Status === 204 || (response.Status >= 200 && response.Status < 300)) {
+            return { Success: true, StatusCode: response.Status, ExternalID: ctx.ExternalID };
+        }
+        return { Success: false, StatusCode: response.Status, ExternalID: '', ErrorMessage: `DeleteRecord failed for "${ctx.ObjectName}": HTTP ${response.Status} — ${this.SafeBody(response)}` };
+    }
+    /** Salesforce REST sObject create — POST `/sobjects/{ObjectName}` flat body, ID in response `id`. */
+    async SFRestCreate(contextUser, ci, objectName, attributes, obj) {
+        const auth = await this.Authenticate(ci, contextUser);
+        const createPath = obj.CreateAPIPath ?? `/services/data/v{apiVersion}/sobjects/{ObjectName}/`;
+        const url = this.ResolveSFRestPath(auth, createPath, objectName, undefined);
         const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
-        const url = `${auth.InstanceURL}/services/data/${auth.ApiVersion}/sobjects/${ctx.ObjectName}`;
-        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, ctx.Attributes);
+        const response = await this.MakeHTTPRequest(auth, url, obj.CreateMethod ?? 'POST', headers, attributes);
         if (response.Status >= 200 && response.Status < 300) {
             const body = response.Body;
-            const newID = body['id'] == null ? undefined : String(body['id']);
-            return this.BuildCreatedResult(newID, response.Status, ctx.ObjectName);
+            const newID = body?.['id'] == null ? undefined : String(body['id']);
+            return this.BuildCreatedResult(newID, response.Status, objectName); // fail LOUDLY on empty id
         }
-        return this.BuildCRUDError(response, 'CreateRecord', ctx.ObjectName);
+        return { Success: false, StatusCode: response.Status, ErrorMessage: `CreateRecord failed for "${objectName}": HTTP ${response.Status} — ${this.SafeBody(response)}` };
     }
-    async UpdateRecord(ctx) {
-        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
+    /** Salesforce REST sObject update — PATCH `/sobjects/{ObjectName}/{Id}` flat body. */
+    async SFRestUpdate(contextUser, ci, objectName, externalID, attributes, obj) {
+        const auth = await this.Authenticate(ci, contextUser);
+        const updatePath = obj.UpdateAPIPath ?? `/services/data/v{apiVersion}/sobjects/{ObjectName}/{Id}`;
+        const url = this.ResolveSFRestPath(auth, updatePath, objectName, externalID);
         const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
-        const url = `${auth.InstanceURL}/services/data/${auth.ApiVersion}/sobjects/${ctx.ObjectName}/${ctx.ExternalID}`;
-        const response = await this.MakeHTTPRequest(auth, url, 'PATCH', headers, ctx.Attributes);
-        if (response.Status >= 200 && response.Status < 300)
-            return { Success: true, ExternalID: ctx.ExternalID, StatusCode: response.Status };
-        return this.BuildCRUDError(response, 'UpdateRecord', ctx.ObjectName);
+        const response = await this.MakeHTTPRequest(auth, url, obj.UpdateMethod ?? 'PATCH', headers, attributes);
+        if (response.Status >= 200 && response.Status < 300) {
+            return { Success: true, StatusCode: response.Status, ExternalID: externalID };
+        }
+        return { Success: false, StatusCode: response.Status, ExternalID: '', ErrorMessage: `UpdateRecord failed for "${objectName}": HTTP ${response.Status} — ${this.SafeBody(response)}` };
     }
-    async DeleteRecord(ctx) {
-        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
-        const headers = this.BuildHeaders(auth);
-        const url = `${auth.InstanceURL}/services/data/${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 };
-        return this.BuildCRUDError(response, 'DeleteRecord', ctx.ObjectName);
+    /**
+     * Nimble Fuse INBOUND upsert — POST `/services/apexrest/NUINT/NUIntegrationService` with the
+     * `{Request: {Name, "Authentication Key", InboundRecords:[{Fields:{...}}]}}` envelope. Parses the
+     * per-record `InboundResults` for partial success, routes the single-record create through
+     * BuildCreatedResult, and fails LOUDLY on an empty SalesforceId.
+     */
+    async FuseUpsert(contextUser, ci, obj, objectName, attributes, forUpdate) {
+        const auth = await this.Authenticate(ci, contextUser);
+        const cfg = this.ReadAccessConfig(obj);
+        const settingName = cfg.InboundSettingName;
+        if (!settingName) {
+            return { Success: false, StatusCode: 0, ErrorMessage: `Fuse upsert for "${objectName}" requires Configuration.InboundSettingName (the admin-configured Integration-Setting name); none is set.` };
+        }
+        const authKey = (auth.Config.AccessToken ? undefined : auth.Config.ClientSecret) ?? auth.Token ?? '';
+        const envelope = {
+            Request: {
+                Name: settingName,
+                'Authentication Key': authKey,
+                InboundRecords: [{ Fields: attributes }],
+            },
+        };
+        const url = `${this.GetBaseURL(ci, auth)}${FUSE_PATH}`;
+        const headers = { ...this.BuildHeaders(auth), 'Content-Type': 'application/json' };
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, envelope);
+        if (response.Status < 200 || response.Status >= 300) {
+            return { Success: false, StatusCode: response.Status, ErrorMessage: `Fuse upsert failed for "${objectName}": HTTP ${response.Status} — ${this.SafeBody(response)}` };
+        }
+        const body = response.Body;
+        const result = (body.InboundResults ?? [])[0];
+        const envelopeError = this.JoinErrors(body.ErrorMessages);
+        if (!result) {
+            return { Success: false, StatusCode: response.Status, ErrorMessage: `Fuse upsert for "${objectName}" returned no InboundResults${envelopeError ? ` — ${envelopeError}` : ''}.` };
+        }
+        const recordError = this.JoinErrors(result.ErrorMessages ?? result.ErrorMessage);
+        if (result.Success === false || recordError) {
+            return { Success: false, StatusCode: response.Status, ExternalID: '', ErrorMessage: `Fuse upsert for "${objectName}" failed for ExternalId="${result.ExternalId ?? ''}": ${recordError || envelopeError || body.Message || 'unknown error'}` };
+        }
+        // A 2xx with no SalesforceId is a silent loss — fail LOUDLY via BuildCreatedResult.
+        if (!forUpdate) {
+            return this.BuildCreatedResult(result.SalesforceId, response.Status, objectName);
+        }
+        const sfid = result.SalesforceId == null ? '' : String(result.SalesforceId).trim();
+        if (sfid.length === 0) {
+            return { Success: false, StatusCode: response.Status, ErrorMessage: `Fuse upsert (update) for "${objectName}" returned HTTP ${response.Status} but no SalesforceId — treating as a failure.` };
+        }
+        return { Success: true, StatusCode: response.Status, ExternalID: sfid };
+    }
+    JoinErrors(errs) {
+        if (!errs)
+            return '';
+        return Array.isArray(errs) ? errs.filter(Boolean).join('; ') : errs;
     }
-    BuildCRUDError(response, op, obj) {
-        const bodyStr = typeof response.Body === 'string' ? response.Body : JSON.stringify(response.Body);
-        return { Success: false, ExternalID: '', StatusCode: response.Status, ErrorMessage: `${op} failed for ${obj}: HTTP ${response.Status} — ${bodyStr?.substring(0, 300)}` };
+    /** True when the object's write door is the Fuse inbound upsert (vs Salesforce REST sObject CRUD). */
+    IsFuseWritePath(obj) {
+        return (obj.CreateAPIPath ?? '').includes(FUSE_PATH) || (obj.UpdateAPIPath ?? '').includes(FUSE_PATH);
+    }
+    /**
+     * Resolve a Salesforce-REST path template, substituting `{apiVersion}` (bare version), `{ObjectName}`,
+     * and `{Id}`/`{ExternalID}`. The contract's SF-REST paths are root-relative (start at /services/...),
+     * so we prefix the instance origin only.
+     */
+    ResolveSFRestPath(auth, pathTemplate, objectName, externalID) {
+        let path = pathTemplate
+            .replace(/\{apiVersion\}/g, auth.ApiVersion)
+            .replace(/\{ObjectName\}/g, encodeURIComponent(objectName));
+        if (externalID !== undefined) {
+            const enc = encodeURIComponent(externalID);
+            path = path.replace(/\{Id\}/g, enc).replace(/\{ID\}/g, enc).replace(/\{id\}/g, enc).replace(/\{ExternalID\}/g, enc);
+        }
+        return `${this.Origin(auth)}${path}`;
+    }
+    /**
+     * Build an ExternalRecord from a raw vendor record. The FULL record flows into `Fields` (custom-column
+     * pass-through contract M1–M4) — the ONLY removed key is the sanctioned SF `attributes` envelope blob
+     * declared in {@link ExcludedSourceKeys}. The PK field supplies ExternalID; the watermark field supplies
+     * ModifiedAt. (FetchSOQL/FetchLMS override the base fetch, so we hand-build records here.)
+     */
+    RawToExternalRecord(raw, obj, objectType, watermarkField, pkField) {
+        const transformed = this.TransformRecord(raw, obj, this.GetCachedFields(obj.ID));
+        const excluded = new Set(this.ExcludedSourceKeys(objectType));
+        const fields = {};
+        for (const [key, value] of Object.entries(transformed)) {
+            if (excluded.has(key))
+                continue;
+            fields[key] = value;
+        }
+        const modRaw = raw[watermarkField];
+        return {
+            ExternalID: String(raw[pkField] ?? ''),
+            ObjectType: objectType,
+            Fields: fields,
+            ModifiedAt: typeof modRaw === 'string' ? new Date(modRaw) : undefined,
+            IsDeleted: raw['IsDeleted'] === true,
+        };
     }
-    // ─── Headers + HTTP ────────────────────────────────────────────────
+    /** Parse the per-IO access Configuration (Family / SObjectType / AccessPath / Fuse setting names). */
+    ReadAccessConfig(obj) {
+        const raw = obj.Configuration;
+        if (!raw)
+            return {};
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return {};
+        }
+    }
+    // ── Headers + HTTP transport ─────────────────────────────────────────────
     BuildHeaders(auth) {
-        return { 'Authorization': `Bearer ${auth.Token}`, 'Accept': 'application/json', 'User-Agent': 'MemberJunction-Integration/1.0' };
+        return {
+            Authorization: `Bearer ${auth.Token}`,
+            Accept: 'application/json',
+            'User-Agent': 'MemberJunction-Integration/1.0',
+        };
     }
     async MakeHTTPRequest(_auth, url, method, headers, body) {
         await this.Throttle();
@@ -356,17 +635,18 @@ let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationCon
                 this.tokenCache = null;
                 continue;
             }
-            if (response.status === 429) {
-                const d = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 500, 60_000);
-                await this.Sleep(d);
+            if (response.status === 429 && attempt < MAX_RETRIES) {
+                const ra = Number(response.headers.get('retry-after'));
+                const wait = !isNaN(ra) && ra > 0 ? ra * 1000 : Math.min(1000 * Math.pow(2, attempt) + Math.random() * 500, 60_000);
+                await this.Sleep(wait);
                 continue;
             }
             if (response.status >= 500 && attempt < MAX_RETRIES) {
                 await this.Sleep(Math.min(1000 * Math.pow(2, attempt), 30_000));
                 continue;
             }
-            const responseBody = await this.ParseBody(response);
-            return this.ToRESTResponse(response, responseBody);
+            const parsed = await this.ParseBody(response);
+            return this.ToRESTResponse(response, parsed);
         }
         throw new Error(`Nimble AMS request failed after ${MAX_RETRIES} retries: ${url}`);
     }
@@ -375,8 +655,14 @@ let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationCon
         const tid = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
         try {
             const opts = { method, headers, signal: controller.signal };
-            if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH'))
-                opts.body = JSON.stringify(body);
+            if (body !== undefined && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+                const serialized = JSON.stringify(body);
+                // Fuse OUTBOUND enforces a 3MB-per-call ceiling — guard the request body up front.
+                if (url.includes(FUSE_PATH) && Buffer.byteLength(serialized, 'utf8') > FUSE_MAX_BYTES_PER_CALL) {
+                    throw new Error(`Nimble Fuse request body exceeds the ${FUSE_MAX_BYTES_PER_CALL}-byte (3MB) per-call limit.`);
+                }
+                opts.body = serialized;
+            }
             return await fetch(url, opts);
         }
         catch (err) {
@@ -388,22 +674,30 @@ let NimbleAMSConnector = class NimbleAMSConnector extends BaseRESTIntegrationCon
             clearTimeout(tid);
         }
     }
-    async ParseBody(r) { const ct = r.headers.get('content-type') ?? ''; return ct.includes('json') ? r.json() : r.text(); }
-    ToRESTResponse(r, body) { const h = {}; r.headers.forEach((v, k) => { h[k.toLowerCase()] = v; }); return { Status: r.status, Body: body, Headers: h }; }
-    async Throttle() { const e = Date.now() - this.lastRequestTime; if (e < MIN_REQUEST_INTERVAL_MS)
-        await this.Sleep(MIN_REQUEST_INTERVAL_MS - e); }
-    Sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
-    GetDefaultFieldMappings(objectName) {
-        const obj = NIMBLE_OBJECTS.find(o => o.Name.toLowerCase() === objectName.toLowerCase());
-        if (!obj)
-            return [{ SourceFieldName: 'Id', DestinationFieldName: 'Id', IsKeyField: true }];
-        return obj.Fields.map(f => ({ SourceFieldName: f.Name, DestinationFieldName: f.Name, IsKeyField: f.IsPrimaryKey }));
+    async ParseBody(r) {
+        const ct = r.headers.get('content-type') ?? '';
+        return ct.includes('json') ? r.json().catch(() => null) : r.text();
+    }
+    ToRESTResponse(r, body) {
+        const h = {};
+        r.headers.forEach((v, k) => { h[k.toLowerCase()] = v; });
+        return { Status: r.status, Body: body, Headers: h };
     }
+    SafeBody(r) {
+        const s = typeof r.Body === 'string' ? r.Body : JSON.stringify(r.Body);
+        return (s ?? '').substring(0, 300);
+    }
+    async Throttle() {
+        const elapsed = Date.now() - this.lastRequestTime;
+        if (elapsed < MIN_REQUEST_INTERVAL_MS)
+            await this.Sleep(MIN_REQUEST_INTERVAL_MS - elapsed);
+    }
+    Sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
 };
 NimbleAMSConnector = __decorate([
     RegisterClass(BaseIntegrationConnector, 'NimbleAMSConnector')
 ], NimbleAMSConnector);
 export { NimbleAMSConnector };
-// Tree-shaking prevention — REQUIRED
+// Tree-shaking prevention — REQUIRED so @RegisterClass survives bundling.
 export function LoadNimbleAMSConnector() { }
 //# sourceMappingURL=NimbleAMSConnector.js.map