@memberjunction/integration-connectors 5.41.0 → 5.42.0

package/dist/NetSuiteConnector.js

@@ -5,601 +5,699 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 /**
- * NetSuiteConnector — Integration connector for Oracle NetSuite ERP platform.
+ * NetSuiteConnector — Integration connector for Oracle NetSuite (SuiteTalk REST Web Services).
  *
- * API Documentation: https://system.netsuite.com/help/helpcenter/en_US/APIs/REST_API_Browser/record/v1/2023.1/index.html
+ * API docs: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/ (SuiteTalk REST API Guide)
  *
- * Auth: OAuth 1.0 Token-Based Authentication (TBA) — non-expiring tokens.
- *       Credentials: ConsumerKey, ConsumerSecret, TokenID, TokenSecret, AccountID
- *       Authorization header with HMAC-SHA256 signature per OAuth 1.0 spec.
- * Base URL: https://{accountId}.suitetalk.api.netsuite.com/services/rest/record/v1
- * SuiteQL: https://{accountId}.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql
- * Pagination: limit/offset (max 1000 per page)
- * Rate limits: 15 concurrent requests/account
- * Incremental: SuiteQL queries with lastmodifieddate >= watermark
- * CRUD: Full CRUD via REST Record API on ALL record types
+ * SCOPE: SuiteTalk REST Web Services only — the Record Service (CRUD on standard + custom record
+ *        types) + the SuiteQL query service. SOAP / RESTlets / SuiteAnalytics Connect are out of scope.
  *
- * Discovery: DYNAMIC via GET /record/v1/metadata-catalog/
- *   - Enumerates ALL available record types for the account (100+ standard types)
- *   - Field metadata fetched per record type via GET /record/v1/metadata-catalog/{recordType}
- *   - New record types (including custom records) are picked up automatically
+ * ── Auth (selected per-connection by Configuration / credential) ───────────────────────────────
+ *   • OAuth 1.0a TBA (Token-Based Authentication) — the primary documented flow. Long-lived,
+ *     non-expiring ConsumerKey/ConsumerSecret + TokenID/TokenSecret, signed per request with
+ *     HMAC-SHA256 and a per-account `realm`. Signing is delegated to the shared `OAuth1aSigner`
+ *     auth-helper — NEVER inline crypto.
+ *   • OAuth 2.0 bearer — the documented alternate (Authorization Code flow). A pre-minted bearer
+ *     access token is supplied via the credential/Configuration and sent as `Authorization: Bearer`.
+ *     (Refresh, when a refresh token + token URL are present, is delegated to OAuth2TokenManager.)
+ *   Mode is chosen by Configuration.AuthFlow ('oauth1-tba' | 'oauth2') or inferred from the
+ *   credential keys present (BearerToken/AccessToken ⇒ OAuth2; ConsumerKey+TokenID ⇒ TBA).
  *
- * API Categories:
- *   - REST Record API (implemented, dynamic) — direct CRUD on ALL record types via metadata catalog
- *   - SuiteQL API (implemented) — SQL-like queries for read + incremental sync
- *   - RESTlet API (NOT implemented) — custom SuiteScript server-side endpoints, not standard
- *   - SOAP/SuiteTalk SOAP (NOT implemented) — legacy XML, superseded by REST
- *   - CSV Import API (NOT implemented) — file-based batch upload, not API-driven
- *   - No webhooks/CDC — use SuiteQL lastmodifieddate polling instead
+ * ── Host (tenant-agnostic — NO baked account) ──────────────────────────────────────────────────
+ *   The base URL is built at runtime from Configuration.AccountID:
+ *   `https://{accountId}.suitetalk.api.netsuite.com` (e.g. '1234567' prod, '1234567_SB1' sandbox).
+ *   Per-account subdomains require the account id be lowercased and '_' → '-' in the subdomain.
+ *
+ * ── Reads ──────────────────────────────────────────────────────────────────────────────────────
+ *   FetchChanges runs SuiteQL: POST /services/rest/query/v1/suiteql with the SQL in the body
+ *   `{ q: '<SQL>' }` and the REQUIRED header `Prefer: transient`. This expresses the lastModifiedDate
+ *   incremental watermark predicate (a thing the generic GET path cannot), so FetchChanges is the one
+ *   genuinely-idiosyncratic override. Everything else rides the base.
+ *
+ * ── CRUD ───────────────────────────────────────────────────────────────────────────────────────
+ *   Create/Update/Delete/Get use the base class's GENERIC per-operation path — they read the IO's
+ *   Create/Update/Delete APIPath/Method/BodyShape/BodyKey/IDLocation columns and dispatch. NetSuite's
+ *   Record Service CRUD is a plain REST shape (POST collection, PATCH /{id}, DELETE /{id}), so no
+ *   override is needed or written.
+ *
+ * ── Pagination ─────────────────────────────────────────────────────────────────────────────────
+ *   Offset/limit (default 1000). Responses carry the HATEOAS envelope { items, count, totalResults,
+ *   hasMore, offset, links:[{rel:'next',href}] } — surfaced in NormalizeResponse + ExtractPaginationInfo.
+ *
+ * ── Incremental ────────────────────────────────────────────────────────────────────────────────
+ *   lastModifiedDate watermark (via WatermarkService in the engine; the connector applies the IO's
+ *   IncrementalWatermarkField inside the SuiteQL predicate and returns the max-seen on full-batch success).
+ *
+ * ── Discovery ──────────────────────────────────────────────────────────────────────────────────
+ *   Rides the metadata-catalog MECHANISM (no baked catalog): GET /services/rest/record/v1/metadata-catalog
+ *   enumerates the record types accessible to the credential; per-type field schema is fetched from the
+ *   same catalog (Accept: application/schema+json). DiscoverObjects UNIONS the Declared baseline (the 200+
+ *   standard record types + the sublist-access-path children, which the catalog never lists) with the live
+ *   catalog's record types — catalog slugs are name-aligned back to the Declared names via each IO's
+ *   Configuration.recordTypeSlug so a slug never duplicates an existing Declared object; unknown slugs pass
+ *   through as new customs. Discovery is NON-authoritative (DiscoveryIsAuthoritative=false): because the
+ *   catalog is a partial enumeration (no sublist children, slug-vs-humanized names), absence proves nothing
+ *   and nothing is ever deactivated. Standard baseline lives in the Declared metadata file; a credential
+ *   only ADDS the account's custom records on top.
  */
-import { createHmac, randomBytes } from 'crypto';
 import { RegisterClass } from '@memberjunction/global';
 import { Metadata } from '@memberjunction/core';
-import { BaseIntegrationConnector, BaseRESTIntegrationConnector, } from '@memberjunction/integration-engine';
+import { IntegrationEngineBase } from '@memberjunction/integration-engine-base';
+import { BaseIntegrationConnector, BaseRESTIntegrationConnector, OAuth1aSigner, OAuth2TokenManager, } from '@memberjunction/integration-engine';
+import { z } from 'zod';
 // ─── Constants ────────────────────────────────────────────────────────────
-const NS_PAGE_SIZE = 1000;
-const MAX_RETRIES = 3;
-const REQUEST_TIMEOUT_MS = 60_000;
-const MIN_REQUEST_INTERVAL_MS = 100;
-// Transaction record types in SuiteQL use the `transaction` table with a type filter.
-// Non-transaction records query their own table (same name as REST endpoint).
-const NS_TRANSACTION_TYPES = {
-    'salesorder': 'SalesOrd', 'invoice': 'CustInvc', 'purchaseorder': 'PurchOrd',
-    'journalentry': 'Journal', 'creditmemo': 'CustCred', 'vendorbill': 'VendBill',
-    'vendorcredit': 'VendCred', 'vendorpayment': 'VendPymt', 'customerpayment': 'CustPymt',
-    'customerrefund': 'CustRfnd', 'customerdeposit': 'CustDep', 'cashsale': 'CashSale',
-    'cashrefund': 'CashRfnd', 'check': 'Check', 'deposit': 'Deposit',
-    'expensereport': 'ExpRept', 'estimate': 'Estimate', 'returnauthorization': 'RtnAuth',
-    'itemfulfillment': 'ItemShip', 'itemreceipt': 'ItemRcpt', 'transferorder': 'TrnfrOrd',
-    'workorder': 'WorkOrd', 'assemblybuild': 'Build', 'inventoryadjustment': 'InvAdjst',
-    'inventorytransfer': 'InvTrnfr', 'depositapplication': 'DepAppl',
-};
+const NS_DEFAULT_PAGE_SIZE = 1000;
+const NS_MAX_RETRIES = 3;
+const NS_REQUEST_TIMEOUT_MS = 90_000;
+const NS_RECORD_BASE_PATH = '/services/rest/record/v1';
+const NS_SUITEQL_PATH = '/services/rest/query/v1/suiteql';
+const NS_METADATA_CATALOG_PATH = '/services/rest/record/v1/metadata-catalog';
+const NS_SERVERTIME_PATH = '/services/rest/system/v1/serverTime';
+// NetSuite REST media type for record bodies (per docs: application/vnd.oracle.resource+json).
+const NS_RECORD_MEDIA_TYPE = 'application/vnd.oracle.resource+json';
+// Concurrency-governed API (no RPS); the smallest documented tier is 5 concurrent. Stay well under it.
+const NS_MAX_CONCURRENCY = 4;
+// ─── Config (typed via Zod) ─────────────────────────────────────────────────
+/**
+ * The per-connection config the connector reads from the credential JSON or
+ * CompanyIntegration.Configuration. AccountID is always required; the auth fields
+ * present select the auth mode.
+ */
+const NetSuiteConfigSchema = z.object({
+    /** Per-account id, e.g. '1234567' or '1234567_SB1'. Builds the host subdomain. */
+    AccountID: z.string().min(1),
+    /**
+     * Optional explicit host-root override (no trailing slash). When set, it is used verbatim
+     * instead of deriving `https://{accountId}.suitetalk.api.netsuite.com` from AccountID.
+     * Production normally leaves this UNSET (host derives from AccountID). It exists for a custom
+     * gateway/proxy and for pointing the connector at a mock vendor in credential-free e2e tests —
+     * the same `BaseURL`-from-config hook iMIS/Hivebrite/GrowthZone expose.
+     */
+    HostBaseURL: z.string().url().optional(),
+    /** Explicit auth mode; inferred when absent. */
+    AuthFlow: z.enum(['oauth1-tba', 'oauth2']).optional(),
+    // OAuth 1.0a TBA
+    ConsumerKey: z.string().optional(),
+    ConsumerSecret: z.string().optional(),
+    TokenID: z.string().optional(),
+    TokenSecret: z.string().optional(),
+    // OAuth 2.0 bearer
+    BearerToken: z.string().optional(),
+    AccessToken: z.string().optional(),
+    RefreshToken: z.string().optional(),
+    ClientID: z.string().optional(),
+    ClientSecret: z.string().optional(),
+    TokenURL: z.string().optional(),
+});
 // ─── Connector ────────────────────────────────────────────────────────────
 let NetSuiteConnector = class NetSuiteConnector extends BaseRESTIntegrationConnector {
     constructor() {
         super(...arguments);
-        this.lastRequestTime = 0;
-        /** Cache of discovered record types: lowercase name → { name, href } */
-        this.recordTypeCache = new Map();
+        this.oauth2Manager = new OAuth2TokenManager();
     }
+    // ── Identity + capabilities ──────────────────────────────────────────
     get IntegrationName() { return 'NetSuite'; }
     get SupportsCreate() { return true; }
     get SupportsUpdate() { return true; }
     get SupportsDelete() { return true; }
-    GetIntegrationObjects() {
-        // Returns discovered objects with minimal fields — DiscoverFields() fills the rest
-        const objects = [];
-        for (const [, item] of this.recordTypeCache) {
-            objects.push({
-                Name: item.name,
-                DisplayName: this.FormatDisplayName(item.name),
-                Description: `NetSuite ${this.FormatDisplayName(item.name)} record`,
-                SupportsWrite: true,
-                Fields: [
-                    { Name: 'id', DisplayName: 'Internal ID', Type: 'string', IsRequired: false, IsReadOnly: true, IsPrimaryKey: true, Description: 'NetSuite internal record ID' },
-                    { Name: 'lastmodifieddate', DisplayName: 'Last Modified', Type: 'datetime', IsRequired: false, IsReadOnly: true, IsPrimaryKey: false, Description: 'Last modification date' },
-                ],
-            });
+    /**
+     * NON-authoritative for deactivation (deliberately false — the T3-deadlock-safe posture).
+     *
+     * The metadata-catalog enumerates the Record-Service record types (standard + custom) — but it is
+     * NOT the complete gamut of this connector's emitted IOs: the contract retains sublist-access-path
+     * children (InvoiceItem, SalesOrderItem) that are reachable as nested graph children and NEVER
+     * appear in the record-type catalog (SublistScopeExtension). It also returns lowercase record-type
+     * SLUGS (`phonecall`) while Declared standard objects are humanized (`Phone Call`). An authoritative
+     * (deactivating) refresh would therefore wrongly Disable every Declared sublist child and any object
+     * whose catalog slug doesn't byte-match the Declared name. Per the convention rule — a partial/scoped
+     * enumeration is NEVER authoritative — absence here proves nothing, so we deactivate nothing. The
+     * standard universe is the Declared metadata baseline; a credential only ADDS the account's customs.
+     */
+    get DiscoveryIsAuthoritative() { return false; }
+    /**
+     * NetSuite governs by CONCURRENT-request limit (5–50 by tier), not requests/sec. We cap inner
+     * concurrency conservatively below the smallest tier; the engine's adaptive controller ramps within it.
+     */
+    get MaxConcurrencyHint() { return NS_MAX_CONCURRENCY; }
+    /** No documented RPS policy — concurrency-governed. Return null so the engine derives a conservative rate. */
+    get RateLimitPolicy() { return null; }
+    /**
+     * SuiteQL fetches in `ORDER BY lastModifiedDate` and an updated record always re-surfaces at a new,
+     * higher modstamp — so the last batch's max IS the true high-water mark. Safe for the engine to use
+     * the returned watermark to narrow the next incremental.
+     */
+    get MonotonicWatermark() { return true; }
+    /**
+     * For watermark-less objects, NetSuite's universal numeric `id` is a stable monotonic ordering key
+     * usable for keyset/seek resume.
+     */
+    StableOrderingKey(_objectName) { return 'id'; }
+    /** Parse NetSuite's 429 Retry-After (seconds) into ms; concurrency limit errors carry no precise hint. */
+    ExtractRetryAfterMs(error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        const m = msg.match(/retry-after[:\s]+(\d+)/i);
+        if (m)
+            return parseInt(m[1], 10) * 1000;
+        return undefined;
+    }
+    // ── Config / credential parsing ──────────────────────────────────────
+    async ParseConfig(companyIntegration, contextUser, provider) {
+        // Credential JSON takes precedence over the non-secret Configuration JSON.
+        if (companyIntegration.CredentialID) {
+            const md = provider ?? new Metadata();
+            const cred = await md.GetEntityObject('MJ: Credentials', contextUser);
+            const loaded = await cred.Load(companyIntegration.CredentialID);
+            if (loaded && cred.Values) {
+                return this.ValidateConfig(JSON.parse(cred.Values));
+            }
+        }
+        if (companyIntegration.Configuration) {
+            return this.ValidateConfig(JSON.parse(companyIntegration.Configuration));
+        }
+        throw new Error('NetSuite connector requires a CredentialID or Configuration JSON carrying AccountID + auth credentials.');
+    }
+    ValidateConfig(raw) {
+        const parsed = NetSuiteConfigSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new Error(`NetSuite Configuration is invalid: ${parsed.error.issues.map(i => i.message).join('; ')}`);
         }
-        return objects;
-    }
-    GetActionGeneratorConfig() {
-        const config = super.GetActionGeneratorConfig();
-        if (!config)
-            return null;
-        config.IconClass = 'fa-solid fa-file-invoice-dollar';
-        config.CategoryDescription = 'NetSuite ERP — all record types discovered dynamically via metadata catalog';
-        config.ParentCategoryName = 'ERP/Finance';
-        config.IncludeSearch = true;
-        config.IncludeList = true;
-        return config;
-    }
-    // ─── Discovery (DYNAMIC via metadata-catalog) ──────────────────────
+        return parsed.data;
+    }
+    /** Determines the auth mode from explicit AuthFlow or the credential keys present. */
+    ResolveAuthMode(config) {
+        if (config.AuthFlow === 'oauth2')
+            return 'oauth2';
+        if (config.AuthFlow === 'oauth1-tba')
+            return 'oauth1-tba';
+        if (config.BearerToken || config.AccessToken || config.RefreshToken)
+            return 'oauth2';
+        return 'oauth1-tba';
+    }
+    // ── Auth ─────────────────────────────────────────────────────────────
+    async Authenticate(companyIntegration, contextUser) {
+        const config = await this.ParseConfig(companyIntegration, contextUser);
+        const mode = this.ResolveAuthMode(config);
+        const subdomain = config.AccountID.toLowerCase().replace(/_/g, '-');
+        // Host derives from AccountID by default; an explicit Configuration.HostBaseURL (custom
+        // gateway / mock vendor in e2e) wins when present. Trailing slash trimmed so APIPath joins clean.
+        const hostBaseURL = (config.HostBaseURL && config.HostBaseURL.trim().length > 0)
+            ? config.HostBaseURL.replace(/\/+$/, '')
+            : `https://${subdomain}.suitetalk.api.netsuite.com`;
+        const realm = config.AccountID.replace(/-/g, '_').toUpperCase();
+        let bearerToken = '';
+        if (mode === 'oauth2') {
+            bearerToken = await this.ResolveBearerToken(config);
+        }
+        else {
+            this.AssertTBACredentials(config);
+        }
+        return {
+            Token: bearerToken,
+            TokenType: mode === 'oauth2' ? 'Bearer' : 'OAuth1',
+            Config: config,
+            Mode: mode,
+            HostBaseURL: hostBaseURL,
+            Realm: realm,
+            BearerToken: bearerToken,
+        };
+    }
+    AssertTBACredentials(config) {
+        if (!config.ConsumerKey || !config.ConsumerSecret || !config.TokenID || !config.TokenSecret) {
+            throw new Error('NetSuite TBA (OAuth 1.0a) requires ConsumerKey, ConsumerSecret, TokenID, and TokenSecret.');
+        }
+    }
+    /**
+     * Resolves a bearer token for OAuth2 mode. A pre-minted BearerToken/AccessToken is used directly
+     * (NetSuite OAuth2 access tokens are supplied by the operator). When a RefreshToken + TokenURL +
+     * client credentials are present, the shared OAuth2TokenManager refreshes — crypto-free token round-trip.
+     */
+    async ResolveBearerToken(config) {
+        const direct = config.BearerToken ?? config.AccessToken;
+        if (config.RefreshToken && config.TokenURL && config.ClientID && config.ClientSecret) {
+            const token = await this.oauth2Manager.GetAccessToken({
+                TokenURL: config.TokenURL,
+                ClientId: config.ClientID,
+                ClientSecret: config.ClientSecret,
+                RefreshToken: config.RefreshToken,
+            }, 'refresh_token');
+            return token.AccessToken;
+        }
+        if (direct)
+            return direct;
+        throw new Error('NetSuite OAuth2 mode requires either a BearerToken/AccessToken, or RefreshToken + TokenURL + ClientID + ClientSecret.');
+    }
+    // ── Headers ──────────────────────────────────────────────────────────
     /**
-     * Discovers ALL available record types by calling the NetSuite REST metadata-catalog API.
-     * This covers 100+ standard record types plus any custom records (customrecord_{id}).
+     * Base headers WITHOUT an Authorization value — the auth header is per-request (OAuth 1.0a signs
+     * each URL+method) so it's injected in MakeHTTPRequest, not here. The base class calls BuildHeaders
+     * for its generic CRUD / pagination GETs; MakeHTTPRequest stamps the signed/bearer Authorization.
+     */
+    BuildHeaders(_auth) {
+        return {
+            'Accept': 'application/json',
+            'User-Agent': 'MemberJunction-Integration/1.0',
+        };
+    }
+    /** Builds the Authorization header for a specific URL + method (TBA signs per request; OAuth2 is static). */
+    BuildAuthorizationHeader(auth, url, method) {
+        if (auth.Mode === 'oauth2') {
+            return `Bearer ${auth.BearerToken}`;
+        }
+        return OAuth1aSigner.BuildAuthorizationHeader({
+            ConsumerKey: auth.Config.ConsumerKey,
+            ConsumerSecret: auth.Config.ConsumerSecret,
+            TokenId: auth.Config.TokenID,
+            TokenSecret: auth.Config.TokenSecret,
+            Method: method,
+            Url: url,
+            Realm: auth.Realm,
+            SignatureMethod: 'HMAC-SHA256',
+        });
+    }
+    // ── URL building ─────────────────────────────────────────────────────
+    /** Base URL = host root; the IO's APIPath already carries the full /services/rest/... path. */
+    GetBaseURL(_companyIntegration, auth) {
+        return auth.HostBaseURL;
+    }
+    // ── HTTP transport ───────────────────────────────────────────────────
+    async MakeHTTPRequest(auth, url, method, headers, body) {
+        const nsAuth = auth;
+        const effectiveHeaders = { ...headers, 'Authorization': this.BuildAuthorizationHeader(nsAuth, url, method) };
+        if (body !== undefined && method !== 'GET' && method !== 'DELETE') {
+            // Record bodies use NetSuite's vendor media type unless a caller (SuiteQL) set its own.
+            if (!effectiveHeaders['Content-Type'])
+                effectiveHeaders['Content-Type'] = NS_RECORD_MEDIA_TYPE;
+        }
+        for (let attempt = 0; attempt <= NS_MAX_RETRIES; attempt++) {
+            let response;
+            try {
+                const opts = {
+                    method,
+                    headers: effectiveHeaders,
+                    signal: AbortSignal.timeout(NS_REQUEST_TIMEOUT_MS),
+                };
+                if (body !== undefined && method !== 'GET' && method !== 'DELETE') {
+                    opts.body = typeof body === 'string' ? body : JSON.stringify(body);
+                }
+                response = await fetch(url, opts);
+            }
+            catch (err) {
+                if (attempt < NS_MAX_RETRIES && this.IsTransientNetworkError(err)) {
+                    await this.Sleep(this.BackoffDelay(attempt));
+                    continue;
+                }
+                throw err;
+            }
+            // Concurrency-limit rejection (429) or transient 5xx — back off + retry within budget.
+            if ((response.status === 429 || response.status >= 500) && attempt < NS_MAX_RETRIES) {
+                const retryAfter = this.ParseRetryAfterHeader(response);
+                await this.Sleep(retryAfter ?? this.BackoffDelay(attempt));
+                continue;
+            }
+            return this.BuildRESTResponse(response);
+        }
+        throw new Error(`NetSuite request failed after ${NS_MAX_RETRIES + 1} attempts: ${url}`);
+    }
+    async BuildRESTResponse(response) {
+        const hdrs = {};
+        response.headers.forEach((v, k) => { hdrs[k.toLowerCase()] = v; });
+        const ct = hdrs['content-type'] ?? '';
+        let parsed;
+        if (ct.includes('json')) {
+            const text = await response.text();
+            parsed = text.length > 0 ? JSON.parse(text) : {};
+        }
+        else {
+            parsed = await response.text();
+        }
+        return { Status: response.status, Body: parsed, Headers: hdrs };
+    }
+    ParseRetryAfterHeader(response) {
+        const ra = response.headers.get('retry-after');
+        if (!ra)
+            return undefined;
+        const secs = parseInt(ra, 10);
+        return Number.isFinite(secs) ? secs * 1000 : undefined;
+    }
+    IsTransientNetworkError(err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return /econnreset|etimedout|enotfound|eai_again|socket hang up|network|fetch failed|timeout/i.test(msg);
+    }
+    BackoffDelay(attempt) {
+        return Math.min(1000 * Math.pow(2, attempt) + Math.floor(Math.random() * 500), 30_000);
+    }
+    Sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    // ── Response parsing ─────────────────────────────────────────────────
+    /** Strips the NetSuite HATEOAS envelope: { items: [...] } → the items array; bare object → [object]. */
+    NormalizeResponse(rawBody, _responseDataKey) {
+        if (Array.isArray(rawBody))
+            return rawBody;
+        if (!rawBody || typeof rawBody !== 'object')
+            return [];
+        const body = rawBody;
+        if (Array.isArray(body.items))
+            return body.items;
+        // A single-record GET returns the record object directly (with a `links` HATEOAS array).
+        if (Object.keys(body).length > 0)
+            return [body];
+        return [];
+    }
+    /** Offset pagination: hasMore flag + offset advance (or the next-link href when present). */
+    ExtractPaginationInfo(rawBody, _paginationType, _currentPage, currentOffset, pageSize) {
+        const body = (rawBody && typeof rawBody === 'object') ? rawBody : {};
+        const records = this.NormalizeResponse(rawBody, null);
+        // Prefer the explicit hasMore flag; fall back to "got a full page".
+        const hasMore = body.hasMore ?? (records.length >= (pageSize || NS_DEFAULT_PAGE_SIZE));
+        const nextOffset = this.NextOffsetFromLinks(body) ?? currentOffset + records.length;
+        return {
+            HasMore: hasMore,
+            NextOffset: nextOffset,
+            TotalRecords: body.totalResults,
+        };
+    }
+    /** Reads the `offset` query param from the HATEOAS rel='next' link when the envelope provides one. */
+    NextOffsetFromLinks(body) {
+        const next = body.links?.find(l => l.rel === 'next');
+        if (!next?.href)
+            return undefined;
+        const qIdx = next.href.indexOf('?');
+        if (qIdx === -1)
+            return undefined;
+        const off = new URLSearchParams(next.href.substring(qIdx + 1)).get('offset');
+        const n = off != null ? parseInt(off, 10) : NaN;
+        return Number.isFinite(n) ? n : undefined;
+    }
+    // ── TestConnection ───────────────────────────────────────────────────
+    /** Validates credentials + host by running a trivial SuiteQL probe (no record dependency). */
+    async TestConnection(companyIntegration, contextUser) {
+        try {
+            const auth = await this.Authenticate(companyIntegration, contextUser);
+            // serverTime is the cheapest authenticated read and seeds the incremental watermark.
+            const url = `${auth.HostBaseURL}${NS_SERVERTIME_PATH}`;
+            const headers = this.BuildHeaders(auth);
+            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+            if (response.Status >= 200 && response.Status < 300) {
+                const st = response.Body;
+                const t = st?.serverTime ?? st?.time ?? 'unknown';
+                return { Success: true, Message: `Connected to NetSuite (${auth.Mode}); server time ${t}` };
+            }
+            if (response.Status === 401 || response.Status === 403) {
+                return { Success: false, Message: `NetSuite authentication failed: HTTP ${response.Status}` };
+            }
+            return { Success: false, Message: `NetSuite returned HTTP ${response.Status} from ${NS_SERVERTIME_PATH}` };
+        }
+        catch (err) {
+            return { Success: false, Message: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    // ── Discovery (auth-gated metadata-catalog MECHANISM — no baked catalog) ──
+    /**
+     * Discovers objects by UNIONING the Declared baseline with the live metadata-catalog (case-2
+     * auth-gated discovery). The Declared metadata (200+ standard record types + the sublist-access-path
+     * children that the catalog never lists) is the floor — it is ALWAYS surfaced so a refresh can't drop
+     * it. The catalog's record-type SLUGS (`phonecall`) are name-aligned back to the Declared name via the
+     * cached Configuration.recordTypeSlug so a slug never duplicates an existing Declared object; an
+     * unknown slug passes through as a NEW custom record. Net: standard universe always present + tenant
+     * customs added. Non-authoritative (DiscoveryIsAuthoritative=false), so no object is ever deactivated.
      */
     async DiscoverObjects(companyIntegration, contextUser) {
+        const declared = await this.GetDeclaredObjects(companyIntegration, contextUser);
+        const slugToDeclaredName = this.BuildSlugToDeclaredNameMap(companyIntegration.IntegrationID);
+        const declaredNamesLower = new Set(declared.map(o => o.Name.toLowerCase()));
         const auth = await this.Authenticate(companyIntegration, contextUser);
-        const catalogURL = `${auth.RecordBaseURL}/metadata-catalog/`;
-        const headers = this.BuildRequestHeaders(auth, catalogURL, 'GET');
-        // Add header to request JSON-schema format with type listing
-        headers['Accept'] = 'application/schema+json';
-        const response = await this.MakeHTTPRequest(auth, catalogURL, 'GET', headers);
-        if (response.Status !== 200) {
-            console.warn(`[NetSuite] Metadata catalog returned ${response.Status}, falling back to SuiteQL discovery`);
-            return this.DiscoverObjectsViaSuiteQL(auth);
+        const url = `${auth.HostBaseURL}${NS_METADATA_CATALOG_PATH}`;
+        const headers = { ...this.BuildHeaders(auth), 'Accept': 'application/schema+json' };
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300) {
+            throw new Error(`NetSuite metadata-catalog returned HTTP ${response.Status} — cannot enumerate record types.`);
         }
-        const body = response.Body;
-        // The metadata-catalog returns { items: [{ name, href }, ...] } or { links: [...] }
-        const items = body['items']
-            ?? body['links']
-            ?? [];
-        this.recordTypeCache.clear();
-        const results = [];
-        for (const item of items) {
-            if (!item.name)
-                continue;
-            this.recordTypeCache.set(item.name.toLowerCase(), item);
-            results.push({
-                Name: item.name,
-                Label: this.FormatDisplayName(item.name),
-                Description: `NetSuite ${this.FormatDisplayName(item.name)} record`,
-                SupportsIncrementalSync: true, // All NS records support lastmodifieddate via SuiteQL
-                SupportsWrite: true, // All REST record types support full CRUD
+        const slugs = this.ExtractCatalogNames(response.Body);
+        const out = [...declared];
+        for (const slug of slugs) {
+            // Name-align to the Declared name this slug maps to; for an UNKNOWN slug (a new custom record)
+            // keep the slug VERBATIM as the Name — the slug is the API-addressable record-type identity, so
+            // it must survive untouched for the discovered custom's CRUD/SuiteQL paths. (Label is humanized.)
+            const name = slugToDeclaredName.get(slug.toLowerCase()) ?? slug;
+            if (declaredNamesLower.has(name.toLowerCase()))
+                continue; // already in the Declared floor
+            declaredNamesLower.add(name.toLowerCase());
+            out.push({
+                Name: name,
+                Label: this.HumanizeName(slug),
+                Description: `NetSuite ${this.HumanizeName(slug)} record`,
+                SupportsIncrementalSync: true,
+                SupportsWrite: true,
             });
         }
-        // If catalog returned nothing, fall back to SuiteQL
-        if (results.length === 0) {
-            return this.DiscoverObjectsViaSuiteQL(auth);
+        return out;
+    }
+    /**
+     * The Declared (cached) baseline objects — the floor DiscoverObjects always surfaces. Seam over the
+     * base class's cache read so the union logic is unit-testable without a DB-backed engine.
+     */
+    GetDeclaredObjects(companyIntegration, contextUser) {
+        return super.DiscoverObjects(companyIntegration, contextUser);
+    }
+    /** Maps each Declared IO's Configuration.recordTypeSlug → its Declared Name (for catalog name-alignment). */
+    BuildSlugToDeclaredNameMap(integrationID) {
+        const map = new Map();
+        const objects = IntegrationEngineBase.Instance.GetActiveIntegrationObjects(integrationID);
+        for (const obj of objects) {
+            const slug = this.ReadRecordTypeSlug(obj.Configuration);
+            if (slug)
+                map.set(slug.toLowerCase(), obj.Name);
         }
-        return results;
+        return map;
     }
     /**
-     * Fallback: discover record types via SuiteQL query against the recordType table.
+     * Resolves the metadata-catalog slug for an object name: the cached IO's Configuration.recordTypeSlug
+     * when present (the authoritative slug, e.g. `phonecall` for `Phone Call`), else a name collapse.
      */
-    async DiscoverObjectsViaSuiteQL(auth) {
-        const query = `SELECT scriptid, name FROM customrecordtype UNION ALL SELECT 'customer' as scriptid, 'Customer' as name FROM dual`;
-        const url = `${auth.QueryBaseURL}/suiteql?limit=1000&offset=0`;
-        const headers = this.BuildRequestHeaders(auth, url, 'POST', true);
+    ResolveRecordTypeSlug(integrationID, objectName) {
         try {
-            const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, { q: query });
-            if (response.Status === 200) {
-                const body = response.Body;
-                const results = [];
-                for (const item of (body.items ?? [])) {
-                    const name = String(item['scriptid'] ?? item['name'] ?? '');
-                    if (name) {
-                        this.recordTypeCache.set(name.toLowerCase(), { name, href: '' });
-                        results.push({
-                            Name: name, Label: this.FormatDisplayName(name),
-                            Description: `NetSuite ${this.FormatDisplayName(name)}`,
-                            SupportsIncrementalSync: true, SupportsWrite: true,
-                        });
-                    }
-                }
-                if (results.length > 0)
-                    return results;
-            }
+            const obj = this.GetCachedObject(integrationID, objectName);
+            const slug = this.ReadRecordTypeSlug(obj.Configuration);
+            if (slug)
+                return slug;
         }
         catch {
-            // Fall through to hardcoded fallback
+            // object not in cache (a freshly-discovered custom) — fall through to name collapse
+        }
+        return objectName.toLowerCase().replace(/\s+/g, '');
+    }
+    /** Tolerantly reads Configuration.recordTypeSlug from an IO's Configuration JSON. */
+    ReadRecordTypeSlug(configuration) {
+        if (!configuration)
+            return undefined;
+        try {
+            const cfg = JSON.parse(configuration);
+            return typeof cfg.recordTypeSlug === 'string' ? cfg.recordTypeSlug : undefined;
         }
-        // Last resort: return a well-known set so the connector is usable even if discovery fails
-        return this.GetFallbackObjects();
-    }
-    GetFallbackObjects() {
-        const knownTypes = [
-            'customer', 'vendor', 'employee', 'contact', 'partner', 'lead', 'prospect',
-            'salesorder', 'invoice', 'purchaseorder', 'journalentry', 'creditmemo',
-            'vendorbill', 'vendorcredit', 'vendorpayment', 'customerpayment', 'customerrefund',
-            'cashsale', 'cashrefund', 'check', 'deposit', 'estimate', 'opportunity',
-            'expensereport', 'returnauthorization', 'itemfulfillment', 'itemreceipt',
-            'transferorder', 'workorder', 'assemblybuild', 'inventoryadjustment',
-            'account', 'department', 'classification', 'location', 'subsidiary', 'currency',
-            'inventoryitem', 'noninventoryitem', 'serviceitem', 'otherchargeitem',
-            'discountitem', 'assemblyitem', 'kititem', 'giftcertificateitem',
-            'task', 'phonecall', 'calendarevent', 'note', 'message',
-            'supportcase', 'issue', 'solution',
-            'job', 'charge', 'timeentry',
-            'term', 'paymentmethod', 'salestaxitem',
-            'file', 'folder',
-        ];
-        for (const name of knownTypes) {
-            this.recordTypeCache.set(name, { name, href: '' });
+        catch {
+            return undefined;
         }
-        return knownTypes.map(name => ({
-            Name: name,
-            Label: this.FormatDisplayName(name),
-            Description: `NetSuite ${this.FormatDisplayName(name)} record`,
-            SupportsIncrementalSync: true,
-            SupportsWrite: true,
-        }));
+    }
+    /** Pulls record-type names from the catalog's `items[].name` or `links[].href` trailing segment. */
+    ExtractCatalogNames(body) {
+        const out = [];
+        for (const it of body.items ?? []) {
+            if (it.name)
+                out.push(it.name);
+        }
+        if (out.length === 0) {
+            for (const lk of body.links ?? []) {
+                if (lk.rel === 'self' || !lk.href)
+                    continue;
+                const seg = lk.href.split('/').filter(Boolean).pop();
+                if (seg)
+                    out.push(seg);
+            }
+        }
+        return out;
     }
     /**
-     * Discovers fields for a record type by fetching its metadata via the REST API.
-     * Falls back to fetching one sample record and inferring field names/types.
+     * Discovers fields for a record type from the metadata-catalog JSON-schema for that type. The schema
+     * `properties` map → fields; `required` → IsRequired; `readOnly`/computed markers → IsReadOnly; the
+     * universal numeric `id` is the PK. Falls back to the cached Declared fields when the catalog can't
+     * describe this type.
      */
     async DiscoverFields(companyIntegration, objectName, contextUser) {
         const auth = await this.Authenticate(companyIntegration, contextUser);
-        const recordType = objectName.toLowerCase();
-        // Try metadata endpoint first: GET /record/v1/metadata-catalog/{recordType}
-        try {
-            const metaURL = `${auth.RecordBaseURL}/metadata-catalog/${recordType}`;
-            const headers = this.BuildRequestHeaders(auth, metaURL, 'GET');
-            headers['Accept'] = 'application/schema+json';
-            const response = await this.MakeHTTPRequest(auth, metaURL, 'GET', headers);
-            if (response.Status === 200) {
-                return this.ParseFieldMetadata(response.Body);
-            }
-        }
-        catch {
-            // Fall through to sample-record approach
+        // Prefer the IO's Configuration.recordTypeSlug (authoritative slug); else collapse the name.
+        const slug = this.ResolveRecordTypeSlug(companyIntegration.IntegrationID, objectName);
+        const url = `${auth.HostBaseURL}${NS_METADATA_CATALOG_PATH}/${encodeURIComponent(slug)}`;
+        const headers = { ...this.BuildHeaders(auth), 'Accept': 'application/schema+json' };
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status >= 200 && response.Status < 300) {
+            const parsed = this.ParseFieldSchema(response.Body);
+            if (parsed.length > 0)
+                return parsed;
         }
-        // Fallback: fetch one record and infer fields from the response
-        return this.InferFieldsFromSample(auth, recordType);
+        // Could not describe via catalog — defer to the Declared metadata (cache) the base class returns.
+        return super.DiscoverFields(companyIntegration, objectName, contextUser);
     }
-    ParseFieldMetadata(body) {
+    /** Maps a JSON-schema describe body to ExternalFieldSchema[] (provable-only: only stated flags). */
+    ParseFieldSchema(body) {
+        if (!body || typeof body !== 'object')
+            return [];
         const schema = body;
-        const properties = schema['properties'];
-        if (!properties)
-            return this.DefaultFields();
+        if (!schema.properties)
+            return [];
+        const required = new Set(schema.required ?? []);
         const fields = [];
-        const requiredFields = schema['required'] ?? [];
-        for (const [name, prop] of Object.entries(properties)) {
-            const nsType = String(prop['type'] ?? prop['format'] ?? 'string');
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            const isId = name === 'id';
             fields.push({
                 Name: name,
-                Label: String(prop['title'] ?? name),
-                Description: String(prop['description'] ?? ''),
-                DataType: this.MapNSFieldType(nsType),
-                IsRequired: requiredFields.includes(name),
-                IsUniqueKey: name === 'id',
-                IsReadOnly: prop['readOnly'] === true,
+                Label: String(prop['title'] ?? this.HumanizeName(name)),
+                Description: typeof prop['description'] === 'string' ? prop['description'] : undefined,
+                DataType: this.MapSchemaType(prop),
+                IsRequired: required.has(name),
+                IsPrimaryKey: isId || undefined,
+                IsUniqueKey: isId,
+                IsReadOnly: prop['readOnly'] === true || isId,
             });
         }
-        // Ensure PK exists
         if (!fields.some(f => f.Name === 'id')) {
             fields.unshift({
                 Name: 'id', Label: 'Internal ID', Description: 'NetSuite internal record ID',
-                DataType: 'string', IsRequired: false, IsUniqueKey: true, IsReadOnly: true,
+                DataType: 'string', IsRequired: false, IsPrimaryKey: true, IsUniqueKey: true, IsReadOnly: true,
             });
         }
         return fields;
     }
-    async InferFieldsFromSample(auth, recordType) {
-        try {
-            const url = `${auth.RecordBaseURL}/${recordType}?limit=1`;
-            const headers = this.BuildRequestHeaders(auth, url, 'GET');
-            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
-            if (response.Status === 200) {
-                const body = response.Body;
-                const sample = (body.items ?? [])[0];
-                if (sample) {
-                    const fields = [];
-                    for (const [key, value] of Object.entries(sample)) {
-                        if (key === 'links')
-                            continue; // Skip HATEOAS links
-                        fields.push({
-                            Name: key,
-                            Label: this.FormatDisplayName(key),
-                            Description: '',
-                            DataType: this.InferTypeFromValue(value),
-                            IsRequired: false,
-                            IsUniqueKey: key === 'id',
-                            IsReadOnly: key === 'id' || key === 'lastmodifieddate' || key === 'datecreated',
-                        });
-                    }
-                    return fields;
-                }
-            }
-        }
-        catch {
-            // Fall through
-        }
-        return this.DefaultFields();
-    }
-    DefaultFields() {
-        return [
-            { Name: 'id', Label: 'Internal ID', Description: 'NetSuite internal record ID', DataType: 'string', IsRequired: false, IsUniqueKey: true, IsReadOnly: true },
-            { Name: 'lastmodifieddate', Label: 'Last Modified', Description: 'Last modification date', DataType: 'datetime', IsRequired: false, IsUniqueKey: false, IsReadOnly: true },
-        ];
-    }
-    MapNSFieldType(nsType) {
-        const lower = nsType.toLowerCase();
-        if (lower.includes('integer') || lower === 'int')
+    /** Maps a JSON-schema property to a generic source type. */
+    MapSchemaType(prop) {
+        const t = String(prop['type'] ?? '').toLowerCase();
+        const fmt = String(prop['format'] ?? '').toLowerCase();
+        if (fmt.includes('date') || fmt.includes('time'))
+            return 'datetime';
+        if (t === 'integer')
             return 'number';
-        if (lower.includes('float') || lower.includes('double') || lower.includes('currency') || lower.includes('decimal'))
+        if (t === 'number')
             return 'decimal';
-        if (lower.includes('boolean'))
+        if (t === 'boolean')
             return 'boolean';
-        if (lower.includes('date') || lower.includes('time'))
-            return 'datetime';
         return 'string';
     }
-    InferTypeFromValue(value) {
-        if (value === null || value === undefined)
-            return 'string';
-        if (typeof value === 'number')
-            return Number.isInteger(value) ? 'number' : 'decimal';
-        if (typeof value === 'boolean')
-            return 'boolean';
-        if (typeof value === 'string') {
-            if (/^\d{4}-\d{2}-\d{2}/.test(value))
-                return 'datetime';
-            return 'string';
-        }
-        return 'string';
-    }
-    FormatDisplayName(name) {
-        // Convert camelCase/lowercase to Title Case: "salesorder" → "Sales Order"
+    HumanizeName(name) {
         return name
-            .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase → camel Case
-            .replace(/([A-Z]+)/g, ' $1') // ABCDef → ABC Def
-            .replace(/[_-]/g, ' ') // snake_case → snake case
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/[_-]/g, ' ')
             .trim()
             .split(/\s+/)
-            .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-            .join(' ');
-    }
-    // ─── Auth ──────────────────────────────────────────────────────────
-    async Authenticate(companyIntegration, contextUser) {
-        const config = await this.ParseConfig(companyIntegration, contextUser);
-        const accountLower = config.AccountID.toLowerCase().replace('_', '-');
-        const recordBaseURL = `https://${accountLower}.suitetalk.api.netsuite.com/services/rest/record/v1`;
-        const queryBaseURL = `https://${accountLower}.suitetalk.api.netsuite.com/services/rest/query/v1`;
-        return {
-            Token: '', TokenType: 'OAuth1', Config: config,
-            RecordBaseURL: recordBaseURL, QueryBaseURL: queryBaseURL,
-        };
-    }
-    async ParseConfig(companyIntegration, contextUser, provider) {
-        const credentialID = companyIntegration.CredentialID;
-        if (credentialID) {
-            const md = provider ?? new Metadata();
-            const credential = await md.GetEntityObject('MJ: Credentials', contextUser);
-            const loaded = await credential.Load(credentialID);
-            if (loaded && credential.Values) {
-                const parsed = JSON.parse(credential.Values);
-                if (parsed['AccountID'] && parsed['ConsumerKey']) {
-                    return {
-                        AccountID: parsed['AccountID'], ConsumerKey: parsed['ConsumerKey'],
-                        ConsumerSecret: parsed['ConsumerSecret'] ?? '',
-                        TokenID: parsed['TokenID'] ?? '', TokenSecret: parsed['TokenSecret'] ?? '',
-                    };
-                }
-            }
-        }
-        const configJson = companyIntegration.Configuration;
-        if (configJson) {
-            const parsed = JSON.parse(configJson);
-            return {
-                AccountID: parsed['AccountID'] ?? '', ConsumerKey: parsed['ConsumerKey'] ?? '',
-                ConsumerSecret: parsed['ConsumerSecret'] ?? '',
-                TokenID: parsed['TokenID'] ?? '', TokenSecret: parsed['TokenSecret'] ?? '',
-            };
-        }
-        throw new Error('No NetSuite credentials found. Set AccountID, ConsumerKey, ConsumerSecret, TokenID, TokenSecret.');
-    }
-    // ─── OAuth 1.0 TBA Signature ────────────────────────────────────────
-    BuildOAuth1Header(config, method, url) {
-        const timestamp = Math.floor(Date.now() / 1000).toString();
-        const nonce = randomBytes(16).toString('hex');
-        const oauthParams = {
-            oauth_consumer_key: config.ConsumerKey, oauth_nonce: nonce,
-            oauth_signature_method: 'HMAC-SHA256', oauth_timestamp: timestamp,
-            oauth_token: config.TokenID, oauth_version: '1.0',
-        };
-        let baseURL = url;
-        const queryPart = {};
-        const qIdx = url.indexOf('?');
-        if (qIdx !== -1) {
-            baseURL = url.substring(0, qIdx);
-            new URLSearchParams(url.substring(qIdx + 1)).forEach((v, k) => { queryPart[k] = v; });
-        }
-        const allParams = { ...oauthParams, ...queryPart };
-        const normalizedParams = Object.keys(allParams).sort()
-            .map(k => `${this.PercentEncode(k)}=${this.PercentEncode(allParams[k])}`).join('&');
-        const sigBaseString = `${method.toUpperCase()}&${this.PercentEncode(baseURL)}&${this.PercentEncode(normalizedParams)}`;
-        const signingKey = `${this.PercentEncode(config.ConsumerSecret)}&${this.PercentEncode(config.TokenSecret)}`;
-        const signature = createHmac('sha256', signingKey).update(sigBaseString).digest('base64');
-        const accountRealm = config.AccountID.replace('-', '_').toUpperCase();
-        const headerParams = { ...oauthParams, oauth_signature: signature };
-        const parts = Object.entries(headerParams).map(([k, v]) => `${k}="${v}"`).join(', ');
-        return `OAuth realm="${accountRealm}", ${parts}`;
-    }
-    PercentEncode(str) {
-        return encodeURIComponent(str).replace(/!/g, '%21').replace(/'/g, '%27')
-            .replace(/\(/g, '%28').replace(/\)/g, '%29').replace(/\*/g, '%2A');
-    }
-    // ─── TestConnection ────────────────────────────────────────────────
-    async TestConnection(companyIntegration, contextUser) {
-        try {
-            const auth = await this.Authenticate(companyIntegration, contextUser);
-            const url = `${auth.RecordBaseURL}/customer?limit=1`;
-            const headers = this.BuildRequestHeaders(auth, url, 'GET');
-            const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
-            if (response.Status === 200) {
-                const body = response.Body;
-                return { Success: true, Message: `Connected to NetSuite — ${body.totalResults ?? 0} customers` };
-            }
-            return { Success: false, Message: `API returned ${response.Status}` };
-        }
-        catch (err) {
-            return { Success: false, Message: err instanceof Error ? err.message : String(err) };
-        }
-    }
-    // ─── URL Building ──────────────────────────────────────────────────
-    GetBaseURL(_companyIntegration, auth) {
-        return auth.RecordBaseURL;
-    }
-    BuildPaginatedURL(basePath, _obj, _page, offset, _cursor) {
-        const sep = basePath.includes('?') ? '&' : '?';
-        return `${basePath}${sep}limit=${NS_PAGE_SIZE}&offset=${offset}`;
-    }
-    // ─── Response Parsing ──────────────────────────────────────────────
-    NormalizeResponse(rawBody, _responseDataKey) {
-        if (Array.isArray(rawBody))
-            return rawBody;
-        const body = rawBody;
-        if (Array.isArray(body['items']))
-            return body['items'];
-        if (body && Object.keys(body).length > 0)
-            return [body];
-        return [];
-    }
-    ExtractPaginationInfo(rawBody, _paginationType, _currentPage, currentOffset, _pageSize) {
-        const body = rawBody;
-        const records = this.NormalizeResponse(rawBody, null);
-        return { HasMore: body.hasMore ?? false, NextOffset: currentOffset + records.length };
-    }
-    // ─── Headers ───────────────────────────────────────────────────────
-    BuildHeaders(_auth) {
-        return { 'Accept': 'application/json', 'User-Agent': 'MemberJunction-Integration/1.0' };
-    }
-    BuildRequestHeaders(auth, url, method, hasBody = false) {
-        const headers = {
-            'Authorization': this.BuildOAuth1Header(auth.Config, method, url),
-            'Accept': 'application/json', 'User-Agent': 'MemberJunction-Integration/1.0',
-        };
-        if (hasBody)
-            headers['Content-Type'] = 'application/json';
-        return headers;
-    }
-    // ─── FetchChanges — generic for ANY record type ────────────────────
+            .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(' ') || name;
+    }
+    // ── FetchChanges — SuiteQL (the one idiosyncratic override) ──────────
+    //
+    // OVERRIDE RATIONALE: NetSuite reads run through SuiteQL (POST with SQL in the body + the required
+    // `Prefer: transient` header) so the lastModifiedDate incremental predicate can be expressed — a
+    // shape the base class's generic GET path cannot produce. CRUD stays on the generic per-operation path.
     async FetchChanges(ctx) {
+        const obj = this.GetCachedObject(ctx.CompanyIntegration.IntegrationID, ctx.ObjectName);
+        const fields = this.GetCachedFields(obj.ID);
         const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
-        const recordType = ctx.ObjectName.toLowerCase();
+        const cfg = this.ReadIOConfig(obj);
+        // SuiteQL table = the IO's configured suiteQLTable; fall back to the catalog slug (collapsed name).
+        const table = cfg.suiteQLTable ?? this.ResolveRecordTypeSlug(ctx.CompanyIntegration.IntegrationID, ctx.ObjectName);
+        const watermarkField = obj.IncrementalWatermarkField ?? 'lastModifiedDate';
         const offset = ctx.CurrentOffset ?? 0;
-        // Determine SuiteQL table: transactions use `transaction` table with type filter
-        const transType = NS_TRANSACTION_TYPES[recordType];
-        const suiteqlTable = transType ? 'transaction' : recordType;
-        const conditions = [];
-        if (transType)
-            conditions.push(`type = '${transType}'`);
-        if (ctx.WatermarkValue)
-            conditions.push(`lastmodifieddate >= '${ctx.WatermarkValue}'`);
-        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
-        const query = `SELECT * FROM ${suiteqlTable}${whereClause} ORDER BY lastmodifieddate`;
-        const url = `${auth.QueryBaseURL}/suiteql?limit=${NS_PAGE_SIZE}&offset=${offset}`;
-        const headers = this.BuildRequestHeaders(auth, url, 'POST', true);
-        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, { q: query });
+        const pageSize = obj.DefaultPageSize ?? cfg.defaultPageSize ?? NS_DEFAULT_PAGE_SIZE;
+        const sql = this.BuildSuiteQL(table, watermarkField, ctx.WatermarkValue);
+        const url = `${auth.HostBaseURL}${NS_SUITEQL_PATH}?limit=${pageSize}&offset=${offset}`;
+        // SuiteQL bodies are plain JSON and REQUIRE the `Prefer: transient` header.
+        const headers = {
+            ...this.BuildHeaders(auth),
+            'Content-Type': 'application/json',
+            'Prefer': 'transient',
+        };
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, { q: sql });
         if (response.Status < 200 || response.Status >= 300) {
-            throw new Error(`NetSuite SuiteQL error for ${recordType}: ${response.Status}`);
+            throw new Error(`NetSuite SuiteQL read failed for "${ctx.ObjectName}": HTTP ${response.Status} — ${this.PreviewBody(response.Body)}`);
         }
         const body = response.Body;
-        const records = body.items ?? [];
-        const externalRecords = records.map(r => ({
-            ExternalID: String(r['id'] ?? ''), ObjectType: ctx.ObjectName, Fields: r,
-        }));
-        let newWatermark;
-        if (!body.hasMore) {
-            for (const r of records) {
-                const modified = r['lastmodifieddate'];
-                if (modified && (!newWatermark || modified > newWatermark))
-                    newWatermark = modified;
-            }
-        }
+        const rawRecords = this.NormalizeResponse(body, null);
+        const pkFieldNames = fields.filter(f => f.IsPrimaryKey).map(f => f.Name);
+        const records = rawRecords.map(raw => this.BuildExternalRecord(raw, ctx.ObjectName, pkFieldNames));
+        const hasMore = body.hasMore ?? (rawRecords.length >= pageSize);
+        // Track the max watermark and persist it ONLY when the full result set has been drained
+        // (partial-failure semantics: a mid-iteration stop leaves the watermark unchanged).
+        const newWatermark = !hasMore ? this.MaxWatermark(rawRecords, watermarkField) : undefined;
         return {
-            Records: externalRecords, HasMore: body.hasMore ?? false,
-            NextOffset: offset + records.length,
-            NewWatermarkValue: !body.hasMore ? newWatermark : undefined,
+            Records: records,
+            HasMore: hasMore,
+            NextOffset: offset + rawRecords.length,
+            NewWatermarkValue: newWatermark,
         };
     }
-    // ─── CRUD — generic for ANY record type ────────────────────────────
-    async CreateRecord(ctx) {
-        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
-        const endpoint = ctx.ObjectName.toLowerCase();
-        const url = `${auth.RecordBaseURL}/${endpoint}`;
-        const headers = this.BuildRequestHeaders(auth, url, 'POST', true);
-        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, ctx.Attributes);
-        if (response.Status >= 200 && response.Status < 300) {
-            const location = response.Headers?.['location'] ?? '';
-            const idMatch = location.match(/\/(\d+)$/);
-            const id = idMatch ? idMatch[1] : String(response.Body?.['id'] ?? '');
-            return { Success: true, ExternalID: id, StatusCode: response.Status };
+    /** Builds the SuiteQL SELECT, applying the incremental watermark predicate when a watermark exists. */
+    BuildSuiteQL(table, watermarkField, watermark) {
+        const where = watermark
+            ? ` WHERE ${watermarkField} > ${this.QuoteSuiteQLDate(watermark)}`
+            : '';
+        return `SELECT * FROM ${table}${where} ORDER BY ${watermarkField}`;
+    }
+    /** Quotes a watermark value for SuiteQL — wraps a NetSuite datetime in TO_DATE/quotes, escaping quotes. */
+    QuoteSuiteQLDate(value) {
+        const escaped = value.replace(/'/g, "''");
+        return `'${escaped}'`;
+    }
+    /** Returns the maximum value of the watermark field across the batch (string compare on ISO timestamps). */
+    MaxWatermark(records, field) {
+        let max;
+        for (const r of records) {
+            const v = r[field];
+            if (typeof v === 'string' && v.length > 0 && (!max || v > max))
+                max = v;
         }
-        return this.BuildCRUDError(response, 'CreateRecord', ctx.ObjectName);
+        return max;
     }
-    async UpdateRecord(ctx) {
-        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
-        const endpoint = ctx.ObjectName.toLowerCase();
-        const url = `${auth.RecordBaseURL}/${endpoint}/${ctx.ExternalID}`;
-        const headers = this.BuildRequestHeaders(auth, url, 'PATCH', true);
-        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);
-    }
-    async DeleteRecord(ctx) {
-        const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
-        const endpoint = ctx.ObjectName.toLowerCase();
-        const url = `${auth.RecordBaseURL}/${endpoint}/${ctx.ExternalID}`;
-        const headers = this.BuildRequestHeaders(auth, url, 'DELETE');
-        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);
-    }
-    BuildCRUDError(response, operation, objectName) {
-        const bodyStr = typeof response.Body === 'string' ? response.Body : JSON.stringify(response.Body);
+    /**
+     * Builds an ExternalRecord carrying the FULL source record in Fields (full-record pass-through, so the
+     * framework's custom-column capture sees every key) and the universal `id` as the ExternalID. Mirrors
+     * the base class's composite-PK + content-hash fallback at the connector boundary for hand-built records.
+     */
+    BuildExternalRecord(raw, objectType, pkFieldNames) {
+        const keys = pkFieldNames.length > 0 ? pkFieldNames : ['id'];
+        const parts = keys.map(k => {
+            const v = raw[k];
+            return v == null ? '' : String(v);
+        });
+        const allPresent = parts.every(p => p.length > 0);
+        const externalID = allPresent ? parts.join('|') : String(raw['id'] ?? '');
         return {
-            Success: false, ExternalID: '', StatusCode: response.Status,
-            ErrorMessage: `${operation} failed for ${objectName}: HTTP ${response.Status} — ${bodyStr?.substring(0, 300)}`,
+            ExternalID: externalID,
+            ObjectType: objectType,
+            Fields: raw,
         };
     }
-    // ─── HTTP Transport ────────────────────────────────────────────────
-    async MakeHTTPRequest(_auth, url, method, headers, body) {
-        await this.Throttle();
-        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            const response = await this.FetchWithTimeout(url, method, headers, body);
-            this.lastRequestTime = Date.now();
-            if (response.status === 429) {
-                const delay = Math.min(1000 * Math.pow(2, attempt) + Math.random() * 500, 60_000);
-                console.warn(`[NetSuite] Rate limited (429), backing off ${Math.round(delay)}ms`);
-                await this.Sleep(delay);
-                continue;
-            }
-            if (response.status >= 500 && attempt < MAX_RETRIES) {
-                const delay = Math.min(2000 * Math.pow(2, attempt), 60_000);
-                console.warn(`[NetSuite] Server error ${response.status}, retrying in ${delay}ms`);
-                await this.Sleep(delay);
-                continue;
-            }
-            const responseBody = await this.ParseBody(response);
-            return this.ToRESTResponse(response, responseBody);
-        }
-        throw new Error(`NetSuite request failed after ${MAX_RETRIES} retries: ${url}`);
-    }
-    async FetchWithTimeout(url, method, headers, body) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    /** Reads the IO's Configuration JSON (suiteQLTable, defaultPageSize) tolerantly. */
+    ReadIOConfig(obj) {
+        if (!obj.Configuration)
+            return {};
         try {
-            const opts = { method, headers, signal: controller.signal };
-            if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH'))
-                opts.body = JSON.stringify(body);
-            return await fetch(url, opts);
-        }
-        catch (err) {
-            if (err instanceof Error && err.name === 'AbortError')
-                throw new Error(`NetSuite request timed out: ${url}`);
-            throw err;
+            const cfg = JSON.parse(obj.Configuration);
+            return {
+                suiteQLTable: typeof cfg.suiteQLTable === 'string' ? cfg.suiteQLTable : undefined,
+                defaultPageSize: typeof cfg.defaultPageSize === 'number' ? cfg.defaultPageSize : undefined,
+            };
         }
-        finally {
-            clearTimeout(timeoutId);
+        catch {
+            return {};
         }
     }
-    async ParseBody(response) {
-        const ct = response.headers.get('content-type') ?? '';
-        if (ct.includes('json'))
-            return response.json();
-        return response.text();
-    }
-    ToRESTResponse(response, body) {
-        const hdrs = {};
-        response.headers.forEach((v, k) => { hdrs[k.toLowerCase()] = v; });
-        return { Status: response.status, Body: body, Headers: hdrs };
-    }
-    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));
-    }
-    // ─── Default Field Mappings ────────────────────────────────────────
-    GetDefaultFieldMappings(objectName) {
-        // Dynamic — uses discovered fields from cache or returns PK-only default
-        return [{ SourceFieldName: 'id', DestinationFieldName: 'id', IsKeyField: true }];
+    PreviewBody(body) {
+        const s = typeof body === 'string' ? body : JSON.stringify(body);
+        return s ? s.substring(0, 300) : '';
     }
 };
 NetSuiteConnector = __decorate([
     RegisterClass(BaseIntegrationConnector, 'NetSuiteConnector')
 ], NetSuiteConnector);
 export { NetSuiteConnector };
-// Tree-shaking prevention — REQUIRED
+// Tree-shaking prevention — REQUIRED so @RegisterClass survives bundling.
 export function LoadNetSuiteConnector() { }
 //# sourceMappingURL=NetSuiteConnector.js.map