@memberjunction/integration-connectors 5.38.0 → 5.39.0

package/dist/HubSpotConnector.js

@@ -17,6 +17,12 @@ const MAX_RETRIES = 5;
 const REQUEST_TIMEOUT_MS = 30000;
 /** Minimum milliseconds between API requests (HubSpot: 100 req/10s for private apps) */
 const MIN_REQUEST_INTERVAL_MS = 100;
+/**
+ * HubSpot CRM search API hard cap: the opaque `after` offset cannot page beyond 10,000 results
+ * within a single query window. Incremental windows larger than this (and same-`hs_lastmodifieddate`
+ * clusters bigger than 10k from bulk imports) must re-anchor by keyset to be fetched completely.
+ */
+const HUBSPOT_SEARCH_WINDOW_CAP = 10_000;
 /**
  * Comprehensive HubSpot object metadata — single source of truth for both
  * action generation and API property requests.
@@ -31,6 +37,9 @@ const HUBSPOT_OBJECTS = [
     {
         Name: 'contacts', DisplayName: 'Contact',
         Description: 'A person or lead in HubSpot CRM', SupportsWrite: true,
+        // Contacts upsert by email — the natural unique key. Drives the idempotent Upsert verb,
+        // which defines the contact-create collision race (409 Contact already exists) out of existence.
+        UpsertKey: 'email',
         Fields: [
             { Name: 'email', DisplayName: 'Email', Type: 'string', IsRequired: true, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact email address' },
             { Name: 'firstname', DisplayName: 'First Name', Type: 'string', IsRequired: false, IsReadOnly: false, IsPrimaryKey: false, Description: 'Contact first name' },
@@ -915,6 +924,8 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         this._config = null;
         /** Cached auth context — reused within a session to avoid redundant credential loads */
         this._cachedAuth = null;
+        /** Cache of resolved default association typeIds, keyed by `${fromType}/${toType}`. */
+        this._assocTypeIdCache = new Map();
     }
     static { HubSpotConnector_1 = this; }
     // ── Per-instance config accessors (fall back to module-level defaults) ──
@@ -924,10 +935,31 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
     // ─── Capability Getters ──────────────────────────────────────────────
     get SupportsCreate() { return true; }
     get SupportsUpdate() { return true; }
+    get SupportsUpsert() { return true; }
     get SupportsDelete() { return true; }
     get SupportsSearch() { return true; }
     get SupportsListing() { return true; }
     get IntegrationName() { return 'HubSpot'; }
+    // ─── §7 sync-efficiency contract (HubSpot = the full reference implementation) ──────────
+    // The engine consumes these for adaptive rate limiting, peak parallelization, and precise 429
+    // back-off. HubSpot's public limit is ~100-110 requests / 10s per Private App; the connector's
+    // MinRequestIntervalMs (default 100ms) is the sustained pace.
+    /** ~10 req/s sustained (honors MinRequestIntervalMs config) with a ~100-request burst window. */
+    get RateLimitPolicy() {
+        const interval = this.effectiveMinRequestIntervalMs;
+        return {
+            TokensPerSec: Math.max(1, Math.round(1000 / (interval > 0 ? interval : 100))),
+            Burst: 100,
+            ThrottleBackoffFactor: 0.5,
+        };
+    }
+    /** HubSpot rate-limits on a rolling 10-second window; on a 429 that escaped internal retries, back off ~10s. */
+    ExtractRetryAfterMs(error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return /\b429\b|rate.?limit|too many requests/i.test(msg) ? 10_000 : undefined;
+    }
+    /** HubSpot tolerates modest object-level parallelism; the engine's AIMD controller ramps toward this, with the token-bucket as the real backstop. */
+    get MaxConcurrencyHint() { return 4; }
     // ─── Action Metadata ─────────────────────────────────────────────────
     GetIntegrationObjects() {
         return HUBSPOT_OBJECTS;
@@ -1087,7 +1119,8 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
      */
     static { this.ASSOCIATION_OBJECTS = [
         { name: 'assoc_contacts_companies', label: 'Contact ↔ Company', description: 'Associations between contacts and companies', apiPath: '/crm/v4/associations/contacts/companies', pkFields: ['contact_id', 'company_id'] },
-        { name: 'assoc_contacts_deals', label: 'Contact ↔ Deal', description: 'Associations between contacts and deals', apiPath: '/crm/v4/associations/contacts/deals', pkFields: ['contact_id', 'deal_id'] },
+        // deal->contact = 3 (HUBSPOT_DEFINED, verified via /labels). Wire from=deal even though stored key is contact|deal.
+        { name: 'assoc_contacts_deals', label: 'Contact ↔ Deal', description: 'Associations between contacts and deals', apiPath: '/crm/v4/associations/contacts/deals', pkFields: ['contact_id', 'deal_id'], fromType: 'deals', toType: 'contacts', fromPkField: 'deal_id', toPkField: 'contact_id', associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 },
         { name: 'assoc_contacts_tickets', label: 'Contact ↔ Ticket', description: 'Associations between contacts and tickets', apiPath: '/crm/v4/associations/contacts/tickets', pkFields: ['contact_id', 'ticket_id'] },
         { name: 'assoc_contacts_calls', label: 'Contact ↔ Call', description: 'Associations between contacts and calls', apiPath: '/crm/v4/associations/contacts/calls', pkFields: ['contact_id', 'call_id'] },
         { name: 'assoc_contacts_emails', label: 'Contact ↔ Email', description: 'Associations between contacts and emails', apiPath: '/crm/v4/associations/contacts/emails', pkFields: ['contact_id', 'email_id'] },
@@ -1095,7 +1128,8 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         { name: 'assoc_contacts_notes', label: 'Contact ↔ Note', description: 'Associations between contacts and notes', apiPath: '/crm/v4/associations/contacts/notes', pkFields: ['contact_id', 'note_id'] },
         { name: 'assoc_contacts_tasks', label: 'Contact ↔ Task', description: 'Associations between contacts and tasks', apiPath: '/crm/v4/associations/contacts/tasks', pkFields: ['contact_id', 'task_id'] },
         { name: 'assoc_contacts_feedback_submissions', label: 'Contact ↔ Feedback Submission', description: 'Associations between contacts and feedback submissions', apiPath: '/crm/v4/associations/contacts/feedback_submissions', pkFields: ['contact_id', 'feedback_submission_id'] },
-        { name: 'assoc_companies_deals', label: 'Company ↔ Deal', description: 'Associations between companies and deals', apiPath: '/crm/v4/associations/companies/deals', pkFields: ['company_id', 'deal_id'] },
+        // No hardcoded typeId — resolved at runtime via /labels (deals/companies exposes multiple HUBSPOT_DEFINED defaults).
+        { name: 'assoc_companies_deals', label: 'Company ↔ Deal', description: 'Associations between companies and deals', apiPath: '/crm/v4/associations/companies/deals', pkFields: ['company_id', 'deal_id'], fromType: 'companies', toType: 'deals', fromPkField: 'company_id', toPkField: 'deal_id', associationCategory: 'HUBSPOT_DEFINED' },
         { name: 'assoc_companies_tickets', label: 'Company ↔ Ticket', description: 'Associations between companies and tickets', apiPath: '/crm/v4/associations/companies/tickets', pkFields: ['company_id', 'ticket_id'] },
         { name: 'assoc_companies_calls', label: 'Company ↔ Call', description: 'Associations between companies and calls', apiPath: '/crm/v4/associations/companies/calls', pkFields: ['company_id', 'call_id'] },
         { name: 'assoc_companies_emails', label: 'Company ↔ Email', description: 'Associations between companies and emails', apiPath: '/crm/v4/associations/companies/emails', pkFields: ['company_id', 'email_id'] },
@@ -1233,11 +1267,16 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
             IsUniqueKey: false, // hasUniqueValue is HubSpot field-level uniqueness, not the record PK; only hs_object_id is the true unique key
             IsReadOnly: p.modificationMetadata?.readOnlyValue === true || p.calculated,
         }));
-        // Ensure hs_object_id is the unique key — HubSpot's Properties API sets
+        // Ensure hs_object_id is the record PK — HubSpot's Properties API sets
         // hasUniqueValue=false for hs_object_id even though it IS the record identifier,
-        // so we must override it regardless of what the API reports.
+        // AND the API never returns an IsPrimaryKey signal at all (PK lives in the
+        // response envelope, not in property metadata).  We must therefore stamp
+        // IsPrimaryKey + IsUniqueKey + IsReadOnly on this field explicitly.  Without
+        // the IsPrimaryKey stamp, UpsertField's new-field path persists it without a
+        // PK flag and the downstream SoftPKClassifier becomes our only safety net.
         const pkField = fields.find(f => f.Name === 'hs_object_id');
         if (pkField) {
+            pkField.IsPrimaryKey = true;
             pkField.IsUniqueKey = true;
             pkField.IsReadOnly = true;
         }
@@ -1248,6 +1287,7 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                 Description: 'HubSpot internal object ID',
                 DataType: 'string',
                 IsRequired: true,
+                IsPrimaryKey: true,
                 IsUniqueKey: true,
                 IsReadOnly: true,
             });
@@ -1291,6 +1331,36 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                 IsReadOnly: true,
             }];
     }
+    /**
+     * Priority-ordered list of HubSpot "last changed" timestamp field names, used to
+     * populate SourceObjectInfo.IncrementalWatermarkField. Every name here is a field
+     * the connector ALREADY declares on its objects — CRM objects expose
+     * `hs_lastmodifieddate` (contacts use the legacy `lastmodifieddate`), while non-CRM
+     * REST objects expose `updatedAt`. Provable-only: the watermark is set on an object
+     * solely from that object's own declared field list, never invented.
+     */
+    static { this.WATERMARK_FIELD_CANDIDATES = [
+        'hs_lastmodifieddate',
+        'lastmodifieddate',
+        'updatedAt',
+    ]; }
+    /**
+     * Promotes an object's own declared "last changed" timestamp field into the
+     * IncrementalWatermarkField slot. Returns the first candidate present in the
+     * supplied field-name set, or undefined when the object declares none — an honest
+     * gap rather than a fabricated watermark. Matching is case-insensitive so a
+     * DB-cached field list (which may differ in casing) still resolves.
+     */
+    PickIncrementalWatermarkField(fieldNames) {
+        const present = new Set(fieldNames.map(n => n.toLowerCase()));
+        for (const candidate of HubSpotConnector_1.WATERMARK_FIELD_CANDIDATES) {
+            if (present.has(candidate.toLowerCase())) {
+                // Return the actually-declared name (preserve its real casing).
+                return fieldNames.find(n => n.toLowerCase() === candidate.toLowerCase());
+            }
+        }
+        return undefined;
+    }
     /**
      * Full schema introspection — discovers all objects and their fields from the live API.
      */
@@ -1367,6 +1437,7 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                     Fields: sourceFields,
                     PrimaryKeyFields: pkFields.map(f => f.Name),
                     Relationships: [],
+                    IncrementalWatermarkField: this.PickIncrementalWatermarkField(sourceFields.map(f => f.Name)),
                 });
             }
             catch (err) {
@@ -1404,6 +1475,7 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                             Fields: sourceFields,
                             PrimaryKeyFields: pkFields.map(f => f.Name),
                             Relationships: [],
+                            IncrementalWatermarkField: this.PickIncrementalWatermarkField(sourceFields.map(f => f.Name)),
                         });
                         console.log(`[HubSpot] Used ${dbFields.length} DB-cached fields for "${obj.Name}" after exception`);
                         continue;
@@ -1489,6 +1561,64 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         }
         return this.BuildCRUDErrorResult(response, 'UpdateRecord', ctx.ObjectName);
     }
+    /**
+     * Idempotently creates-or-updates a record keyed by a unique business property
+     * (default: the object's `UpsertKey` metadata, e.g. 'email' for contacts).
+     *
+     * Uses HubSpot's batch/upsert endpoint with a batch of one. This is the ONLY HubSpot
+     * single-call idempotent path verified against the live API: the single-record
+     * PATCH .../{id}?idProperty=email does NOT create-on-missing (returns 404), while
+     * POST .../batch/upsert creates-on-missing and updates-on-existing with a 2xx (no 409).
+     * A batch of one sidesteps the documented batch caveats (whole-batch-409 on concurrent
+     * batches, no partial upserts) that only bite multi-input batches.
+     *
+     * This *defines the error out of existence*: a search-then-create sequence has a window in
+     * which a concurrent writer can create the same email-keyed contact, yielding
+     * `409 Contact already exists`. Rather than catch and special-case that 409, the single keyed
+     * upsert removes the window entirely — the collision is no longer a condition the caller (or
+     * this code) ever has to handle.
+     */
+    async Upsert(ctx) {
+        const idProperty = ctx.IDProperty ?? this.GetUpsertKey(ctx.ObjectName);
+        if (!idProperty) {
+            return {
+                Success: false,
+                StatusCode: 400,
+                ErrorMessage: `[HubSpot] Upsert on '${ctx.ObjectName}' has no upsert key — set ctx.IDProperty or declare UpsertKey in object metadata`,
+            };
+        }
+        const idValue = ctx.Attributes[idProperty];
+        if (idValue == null || String(idValue).length === 0) {
+            return {
+                Success: false,
+                StatusCode: 400,
+                ErrorMessage: `[HubSpot] Upsert on '${ctx.ObjectName}' is missing a value for the upsert key '${idProperty}' in Attributes`,
+            };
+        }
+        const companyIntegration = ctx.CompanyIntegration;
+        const contextUser = ctx.ContextUser;
+        const auth = await this.Authenticate(companyIntegration, contextUser);
+        const headers = this.BuildHeaders(auth);
+        const url = `${HUBSPOT_API_BASE}/crm/v3/objects/${ctx.ObjectName}/batch/upsert`;
+        // Batch of one: id is the upsert-key value; properties carry the full record.
+        const body = { inputs: [{ idProperty, id: String(idValue), properties: ctx.Attributes }] };
+        const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
+        // Never trust a bare 2xx — the batch envelope can report per-input errors with a 2xx.
+        const batchError = this.GetBatchUpsertError(response);
+        if (batchError) {
+            return {
+                Success: false,
+                StatusCode: response.Status,
+                ErrorMessage: `[HubSpot] Upsert on ${ctx.ObjectName}: ${batchError}`,
+            };
+        }
+        const upserted = response.Body.results?.[0];
+        return {
+            Success: true,
+            ExternalID: String(upserted?.id ?? ''),
+            StatusCode: response.Status,
+        };
+    }
     /**
      * Deletes (archives) a record in HubSpot by ExternalID.
      * Routes association objects to the v4 batch/archive endpoint instead of v3 objects.
@@ -1533,16 +1663,29 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                 ErrorMessage: `CreateAssociation ${objectName}: missing PK fields '${leftField}' or '${rightField}' in attributes`,
             };
         }
-        const pathParts = assocConfig.apiPath.split('/').filter(Boolean);
-        const fromType = pathParts[pathParts.length - 2];
-        const toType = pathParts[pathParts.length - 1];
+        // Wire direction is explicit config, decoupled from pkFields/apiPath order.
+        // attributes are keyed by pkField name, so map from/to via fromPkField/toPkField.
+        const { fromType, toType } = this.GetAssociationWireTypes(assocConfig);
+        const fromID = assocConfig.fromPkField ? String(attributes[assocConfig.fromPkField] ?? '') : leftID;
+        const toID = assocConfig.toPkField ? String(attributes[assocConfig.toPkField] ?? '') : rightID;
+        // typeId: hardcoded verified-only fast path; otherwise resolve from /labels.
+        const typeId = assocConfig.associationTypeId
+            ?? await this.ResolveAssociationTypeId(auth, headers, fromType, toType);
+        if (typeId == null) {
+            return { Success: false, ExternalID: '', StatusCode: 400, ErrorMessage: `CreateAssociation ${objectName}: could not resolve a HUBSPOT_DEFINED association typeId for ${fromType}->${toType}` };
+        }
+        const types = [{ associationCategory: assocConfig.associationCategory ?? 'HUBSPOT_DEFINED', associationTypeId: typeId }];
         const url = `${HUBSPOT_API_BASE}/crm/v4/associations/${fromType}/${toType}/batch/create`;
-        const body = { inputs: [{ from: { id: leftID }, to: { id: rightID }, types: [] }] };
+        const body = { inputs: [{ from: { id: fromID }, to: { id: toID }, types }] };
         const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
-        if (response.Status >= 200 && response.Status < 300) {
+        // Never trust a bare 2xx — HubSpot returns 2xx with numErrors/empty results on
+        // validation failures and on the old empty-types no-op.
+        const batchError = this.GetAssociationBatchError(response);
+        if (!batchError) {
+            // Stored ExternalID stays in pkFields order (left|right), NOT wire order.
             return { Success: true, ExternalID: `${leftID}|${rightID}`, StatusCode: response.Status };
         }
-        return this.BuildCRUDErrorResult(response, 'CreateAssociation', objectName);
+        return { Success: false, ExternalID: '', StatusCode: response.Status, ErrorMessage: `CreateAssociation ${objectName}: ${batchError}` };
     }
     /**
      * Removes an association in HubSpot using the v4 batch/archive endpoint.
@@ -1564,11 +1707,15 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         }
         const leftID = externalID.substring(0, pipeIndex);
         const rightID = externalID.substring(pipeIndex + 1);
-        const pathParts = assocConfig.apiPath.split('/').filter(Boolean);
-        const fromType = pathParts[pathParts.length - 2];
-        const toType = pathParts[pathParts.length - 1];
+        // Stored key is in pkFields order (left=pkFields[0], right=pkFields[1]). Map to the
+        // explicit wire direction so archive matches the create direction.
+        const { fromType, toType } = this.GetAssociationWireTypes(assocConfig);
+        const [leftPkField] = assocConfig.pkFields;
+        const idByPkField = { [leftPkField]: leftID, [assocConfig.pkFields[1]]: rightID };
+        const fromID = assocConfig.fromPkField ? idByPkField[assocConfig.fromPkField] : leftID;
+        const toID = assocConfig.toPkField ? idByPkField[assocConfig.toPkField] : rightID;
         const url = `${HUBSPOT_API_BASE}/crm/v4/associations/${fromType}/${toType}/batch/archive`;
-        const body = { inputs: [{ from: { id: leftID }, to: { id: rightID } }] };
+        const body = { inputs: [{ from: { id: fromID }, to: { id: toID } }] };
         const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, body);
         // batch/archive returns 204 No Content on success
         if (response.Status === 204 || (response.Status >= 200 && response.Status < 300)) {
@@ -1655,6 +1802,99 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
             throw new Error(`[HubSpot] ${operation} on ${objectName} failed (HTTP ${response.Status}): ${bodyPreview}`);
         }
     }
+    /**
+     * Resolves the v4 wire from/to object types for an association. Uses explicit fromType/toType
+     * config when present; otherwise falls back to apiPath segment order. Both
+     * CreateAssociation and DeleteAssociation share this so create and archive always agree.
+     */
+    GetAssociationWireTypes(assocConfig) {
+        const segments = assocConfig.apiPath.split('/').filter(Boolean);
+        return {
+            fromType: assocConfig.fromType ?? segments.at(-2),
+            toType: assocConfig.toType ?? segments.at(-1),
+        };
+    }
+    /**
+     * Resolves the default HUBSPOT_DEFINED association typeId for a (fromType, toType) pair via
+     * GET /crm/v4/associations/{fromType}/{toType}/labels, cached per pair for the connector's life.
+     * Picks the unlabeled HUBSPOT_DEFINED entry (label === null) as the plain default; if none is
+     * unlabeled, falls back to the sole/first HUBSPOT_DEFINED entry. Returns null on lookup failure
+     * or when no HUBSPOT_DEFINED entry exists — callers MUST treat null as a hard error (never
+     * silently send empty types).
+     */
+    async ResolveAssociationTypeId(auth, headers, fromType, toType) {
+        const cacheKey = `${fromType}/${toType}`;
+        const cached = this._assocTypeIdCache.get(cacheKey);
+        if (cached != null)
+            return cached;
+        const url = `${HUBSPOT_API_BASE}/crm/v4/associations/${fromType}/${toType}/labels`;
+        const response = await this.MakeHTTPRequest(auth, url, 'GET', headers);
+        if (response.Status < 200 || response.Status >= 300) {
+            console.warn(`[HubSpot] /labels lookup failed for ${cacheKey}: HTTP ${response.Status}`);
+            return null;
+        }
+        const body = response.Body;
+        const defined = (body?.results ?? []).filter(r => r.category === 'HUBSPOT_DEFINED' && r.typeId != null);
+        if (defined.length === 0)
+            return null;
+        const unlabeled = defined.find(r => r.label == null);
+        const chosen = (unlabeled ?? defined[0]).typeId;
+        this._assocTypeIdCache.set(cacheKey, chosen);
+        return chosen;
+    }
+    /**
+     * Validates a v4 association batch/create response BODY (not just the HTTP status).
+     * HubSpot returns 2xx even when zero associations are created — on the legacy empty-`types`
+     * no-op (empty results, no errors) and on validation failures (empty results + numErrors).
+     * Returns null when the operation genuinely completed; otherwise a human-readable error.
+     * Predicate verified against live HubSpot batch/create responses.
+     */
+    GetAssociationBatchError(response) {
+        if (response.Status < 200 || response.Status >= 300) {
+            const b = response.Body;
+            return b?.['message'] ? String(b['message']) : `HTTP ${response.Status}`;
+        }
+        const body = response.Body;
+        if (body?.numErrors || (body?.errors && body.errors.length > 0)) {
+            return body.errors?.[0]?.message ?? `HubSpot reported ${body?.numErrors ?? body?.errors?.length} association error(s)`;
+        }
+        if (body?.status && body.status !== 'COMPLETE') {
+            return `association batch status was '${body.status}', expected 'COMPLETE'`;
+        }
+        if (!body?.results || body.results.length === 0) {
+            return `HubSpot returned no association results (2xx but nothing linked)`;
+        }
+        return null;
+    }
+    /**
+     * Validates a v3 batch/upsert response BODY (not just the HTTP status). HubSpot's batch
+     * envelope can return a 2xx while reporting per-input failures via `numErrors`/`errors`,
+     * an incomplete `status`, or an empty `results` array. Returns null when the upsert
+     * genuinely produced a record; otherwise a human-readable error. Mirrors the
+     * GetAssociationBatchError precedent — never trust a bare 2xx on a batch endpoint.
+     */
+    GetBatchUpsertError(response) {
+        if (response.Status < 200 || response.Status >= 300) {
+            const b = response.Body;
+            return b?.['message'] ? String(b['message']) : `HTTP ${response.Status}`;
+        }
+        const body = response.Body;
+        if (body?.numErrors || (body?.errors && body.errors.length > 0)) {
+            return body.errors?.[0]?.message ?? `HubSpot reported ${body?.numErrors ?? body?.errors?.length} upsert error(s)`;
+        }
+        if (body?.status && body.status !== 'COMPLETE') {
+            return `upsert batch status was '${body.status}', expected 'COMPLETE'`;
+        }
+        if (!body?.results || body.results.length === 0) {
+            return `HubSpot returned no upsert results (2xx but nothing written)`;
+        }
+        // A 2xx result with no usable id means the write didn't really land — reporting success here
+        // would hand the caller an empty ExternalID and silently break any later lookup keyed on it.
+        if (body.results[0]?.id == null || String(body.results[0].id).length === 0) {
+            return `HubSpot upsert result is missing an object id (2xx but no id to link)`;
+        }
+        return null;
+    }
     /** Builds a CRUDResult for error responses. */
     BuildCRUDErrorResult(response, operation, objectName) {
         const bodyObj = response.Body;
@@ -1729,7 +1969,10 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
             }
             return this.BuildRESTResponse(response, responseBody);
         }
-        throw new Error(`HubSpot API request failed after ${maxRetries} retries: ${url}`);
+        // The loop only retries on 429 (every other status returns above), so exhausting retries here
+        // means sustained 429 rate-limiting. Carry the "429 rate limit" marker so ClassifyError →
+        // RATE_LIMIT_EXCEEDED and the engine's adaptive limiter / ExtractRetryAfterMs react correctly.
+        throw new Error(`HubSpot 429 rate limit: request failed after ${maxRetries} retries (sustained throttling): ${url}`);
     }
     NormalizeResponse(rawBody, responseDataKey) {
         const body = rawBody;
@@ -2319,6 +2562,26 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
     /**
      * Fetches changed records using the HubSpot search API with server-side date filtering.
      * Much more efficient than fetching ALL records and filtering client-side.
+     *
+     * Handles the search API's 10,000-results-per-window hard cap by keyset re-anchoring: results
+     * are sorted by (dateField, hs_object_id) ASCENDING, paginated within a window by the API's
+     * opaque `after` offset, and once that offset hits the 10k cap the NEXT window re-anchors with a
+     * compound filter `(dateField > anchor) OR (dateField == anchor AND hs_object_id > anchorId)`.
+     * This makes an incremental window — or a bulk-import cluster of >10k records that all share one
+     * `hs_lastmodifieddate` — page through completely in a single sync, instead of the watermark
+     * stalling on a same-timestamp cluster it can never advance past (which silently lost records).
+     * The date GTE watermark remains the primary filter throughout, so incremental sync is preserved.
+     *
+     * LIVE-VERIFY (confirm during the credentialed run against a real >10k same-timestamp cluster):
+     *  1. hs_object_id GT/EQ comparison in v3 search is NUMERIC, not lexicographic. HIGHEST STAKES — if
+     *     lexicographic, '2' > '10000' and the keyset would skip records. (hs_object_id is a sequential
+     *     64-bit integer / number-typed property, so numeric is expected, but prove it across an
+     *     id-magnitude boundary, e.g. ids 9, 10, 100, 1000 within one timestamp cluster.)
+     *  2. Datetime filter values accept epoch-millis-as-string for EQ/GT/GTE (the pre-existing GTE
+     *     watermark filter already relies on this, so a regression here would also break prior behavior).
+     *  3. The compound (dateField ASC, hs_object_id ASC) sort is honored deterministically across pages
+     *     and object types, so the last raw result is the true (date,id)-max keyset boundary.
+     *  4. `total` reflects the CURRENT filterGroups per re-anchored query (not a cached original count).
      */
     async FetchChangesViaSearch(ctx) {
         const companyIntegration = ctx.CompanyIntegration;
@@ -2329,36 +2592,40 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         const watermarkMs = new Date(ctx.WatermarkValue).getTime();
         const properties = this.BuildEffectiveProperties(ctx.ObjectName, ctx.RequestedSourceFields);
         const pageSize = Math.min(ctx.BatchSize ?? 100, 100); // HubSpot search API max is 100
+        const cursor = this.parseSearchCursor(ctx.CurrentCursor);
+        const isReanchored = cursor.anchorDateMs != null && cursor.anchorId != null;
+        // When re-anchored past a 10k window, the keyset predicate replaces the plain GTE filter.
+        // anchorDateMs is always >= watermarkMs (we only ever advance), so the keyset predicate
+        // subsumes the original watermark filter — incremental scope is never widened.
+        const filterGroups = isReanchored
+            ? [
+                { filters: [{ propertyName: dateField, operator: 'GT', value: cursor.anchorDateMs }] },
+                { filters: [
+                        { propertyName: dateField, operator: 'EQ', value: cursor.anchorDateMs },
+                        { propertyName: 'hs_object_id', operator: 'GT', value: cursor.anchorId },
+                    ] },
+            ]
+            : [{ filters: [{ propertyName: dateField, operator: 'GTE', value: String(watermarkMs) }] }];
         const searchBody = {
-            filterGroups: [{
-                    filters: [{
-                            propertyName: dateField,
-                            operator: 'GTE',
-                            value: String(watermarkMs),
-                        }],
-                }],
-            sorts: [{ propertyName: dateField, direction: 'ASCENDING' }],
+            filterGroups,
+            // Secondary sort on hs_object_id is REQUIRED: it makes ordering deterministic within a
+            // same-timestamp cluster so the keyset anchor (last record's id) is well-defined and the
+            // next window can never skip or re-emit a record at the boundary.
+            sorts: [
+                { propertyName: dateField, direction: 'ASCENDING' },
+                { propertyName: 'hs_object_id', direction: 'ASCENDING' },
+            ],
             properties,
             limit: pageSize,
         };
-        if (ctx.CurrentCursor) {
-            searchBody['after'] = ctx.CurrentCursor;
+        if (cursor.after) {
+            searchBody['after'] = cursor.after;
         }
         const url = `${HUBSPOT_API_BASE}/crm/v3/objects/${ctx.ObjectName}/search`;
         const response = await this.MakeHTTPRequest(auth, url, 'POST', headers, searchBody);
         this.ValidateCRUDResponse(response, 'FetchChangesViaSearch', ctx.ObjectName);
         const body = response.Body;
-        // HubSpot Search API hard limit: 10,000 results maximum per query window.
-        // If total > 10K, only the oldest-modified records (sorted ASCENDING) are returned.
-        // The watermark advances to the batch's max date each cycle, so subsequent syncs
-        // pick up the remainder — no records are permanently lost, but multiple sync cycles
-        // are needed to catch up. Log a warning so operators can monitor.
         const searchTotal = body.total ?? 0;
-        if (searchTotal > 10_000) {
-            console.warn(`[HubSpot] ${ctx.ObjectName}: Search API returned total=${searchTotal} but is capped at 10,000 results. ` +
-                `Sync will require ${Math.ceil(searchTotal / 10_000)} cycles to catch up from watermark ${ctx.WatermarkValue}. ` +
-                `Consider reducing the sync interval or enabling continuous sync for this object.`);
-        }
         const rawResults = body.results ?? [];
         const records = rawResults.map(r => {
             const raw = r;
@@ -2369,10 +2636,32 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                 Fields: flat,
             };
         });
-        const nextCursor = body.paging?.next?.after;
-        const hasMore = nextCursor != null;
-        // On the final page of active records, also fetch archived (deleted) records
-        // since the watermark so they flow through the engine's delete pipeline.
+        // Keyset anchor for the NEXT window = the last record in (date, id) sort order.
+        const anchor = this.extractSearchAnchor(rawResults, dateField);
+        const { nextCursor, hasMore, stalled } = this.computeSearchResume({
+            incoming: cursor,
+            pagingNextAfter: body.paging?.next?.after,
+            total: searchTotal,
+            lastAnchorDateMs: anchor.dateMs,
+            lastAnchorId: anchor.id,
+        });
+        if (stalled) {
+            // total exceeds the window cap but we couldn't form a keyset anchor to page past it. Fail
+            // LOUD rather than silently dropping the remainder: the engine catches this, marks the
+            // fetch incomplete, and leaves the watermark un-advanced so the next sync retries the gap.
+            throw new Error(`HubSpot ${ctx.ObjectName}: search reported total=${searchTotal} (beyond the ` +
+                `${HUBSPOT_SEARCH_WINDOW_CAP}-record window cap) but the last page returned no keyset anchor, ` +
+                `so the scan cannot advance without risking silent record loss. Aborting this fetch; the ` +
+                `watermark is left un-advanced and the remainder is retried on the next sync.`);
+        }
+        if (searchTotal > HUBSPOT_SEARCH_WINDOW_CAP && !cursor.after && !isReanchored) {
+            // Informational only — the keyset re-anchor below pages through the whole window in this
+            // sync; this is no longer a multi-cycle stall, just a large object worth noting.
+            console.log(`[HubSpot] ${ctx.ObjectName}: ${searchTotal} records since watermark exceed the 10k search window; ` +
+                `keyset-paginating by (${dateField}, hs_object_id) to fetch them all in this sync.`);
+        }
+        // On the final page of the entire scan, also fetch archived (deleted) records since the
+        // watermark so they flow through the engine's delete pipeline.
         if (!hasMore) {
             const archived = await this.FetchArchivedCRMChanges(auth, headers, ctx.ObjectName, dateField, watermarkMs, properties);
             if (archived.length > 0) {
@@ -2389,10 +2678,103 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         return {
             Records: records,
             HasMore: hasMore,
-            NextCursor: nextCursor,
+            NextCursor: nextCursor ? JSON.stringify(nextCursor) : undefined,
             NewWatermarkValue: newWatermark,
         };
     }
+    /**
+     * Parses the {@link HubSpotSearchCursor} threaded via FetchContext.CurrentCursor. Tolerates a
+     * legacy raw `after` string (pre-keyset format) by treating it as a plain window offset, so an
+     * in-flight sync mid-upgrade degrades gracefully rather than throwing.
+     */
+    parseSearchCursor(raw) {
+        if (!raw)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object')
+                return parsed;
+            // Parsed to a primitive (e.g. a bare numeric `after` like "9900" from the pre-keyset
+            // format) — treat the raw value as a plain window offset.
+            return { after: raw };
+        }
+        catch {
+            return { after: raw };
+        }
+    }
+    /**
+     * Extracts the keyset anchor (the last record's dateField-as-epoch-ms and hs_object_id) from a
+     * batch of raw search results. Because results are sorted (dateField, hs_object_id) ASCENDING,
+     * the last element is the maximum position and therefore the resume point for the next window.
+     * Returns undefined fields when the batch is empty or the values can't be parsed.
+     */
+    extractSearchAnchor(rawResults, dateField) {
+        if (rawResults.length === 0)
+            return {};
+        const lastFlat = this.FlattenHubSpotRecord(rawResults[rawResults.length - 1]);
+        const id = lastFlat['hs_object_id'];
+        const result = {};
+        if (id != null && String(id).length > 0)
+            result.id = String(id);
+        const dateMs = this.toEpochMs(lastFlat[dateField]);
+        if (dateMs != null)
+            result.dateMs = dateMs;
+        return result;
+    }
+    /**
+     * Normalizes a HubSpot datetime property value to an epoch-millis string for use in a search
+     * filter. Accepts both an ISO-8601 string (the usual v3 shape) and a bare epoch-millis numeric
+     * string (some endpoints/properties). Returns undefined when unparseable — callers then skip
+     * re-anchoring rather than seeking from a NaN position.
+     */
+    toEpochMs(dateVal) {
+        if (dateVal == null)
+            return undefined;
+        const s = String(dateVal);
+        const iso = new Date(s).getTime();
+        if (!Number.isNaN(iso))
+            return String(iso);
+        const epoch = Number(s);
+        if (!Number.isNaN(epoch) && epoch > 0)
+            return String(epoch);
+        return undefined;
+    }
+    /**
+     * Pure decision for the next search window, given this page's pagination + total. No network.
+     *
+     * - If more pages remain inside the current ≤10k window, advance the API `after` offset and keep
+     *   the same anchor.
+     * - Otherwise the window is exhausted (the API stopped returning `after`, or it reached the 10k
+     *   cap). If records still match the current filter (`total > cap`), re-anchor the next window on
+     *   the last record's (dateField, hs_object_id) keyset; else the scan is complete.
+     *
+     * `total` is the count matching the CURRENT filter, so after each re-anchor it shrinks by roughly
+     * one window until it falls to/under the cap — guaranteeing termination with no skipped records
+     * (the anchor's id strictly increases) and no duplicates (the keyset predicate excludes it).
+     */
+    computeSearchResume(args) {
+        const { incoming, pagingNextAfter, total, lastAnchorDateMs, lastAnchorId } = args;
+        const cap = HUBSPOT_SEARCH_WINDOW_CAP;
+        const withinWindow = pagingNextAfter != null && Number(pagingNextAfter) < cap;
+        if (withinWindow) {
+            return {
+                nextCursor: { after: pagingNextAfter, anchorDateMs: incoming.anchorDateMs, anchorId: incoming.anchorId },
+                hasMore: true,
+            };
+        }
+        if (total > cap) {
+            if (lastAnchorId != null && lastAnchorDateMs != null) {
+                return { nextCursor: { anchorDateMs: lastAnchorDateMs, anchorId: lastAnchorId }, hasMore: true };
+            }
+            // total exceeds the 10k window cap but this page produced no usable keyset anchor — which
+            // means HubSpot returned a total > 0 with an empty/anchorless page (a contract violation).
+            // Re-anchoring is impossible; silently stopping here would DROP the remaining records — the
+            // exact silent-loss this fix exists to prevent. Flag it so the caller aborts loudly and
+            // leaves the watermark un-advanced (the next sync retries the gap) instead of skipping it.
+            return { nextCursor: undefined, hasMore: false, stalled: true };
+        }
+        return { nextCursor: undefined, hasMore: false };
+    }
     /**
      * Detects archived (deleted) CRM records since the given watermark.
      *
@@ -2418,7 +2800,13 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
                                 value: String(watermarkMs),
                             }],
                     }],
-                sorts: [{ propertyName: dateField, direction: 'ASCENDING' }],
+                // Secondary sort on hs_object_id matches the active-record path: bulk deletions often
+                // share one hs_lastmodifieddate, so without a tie-breaker the opaque `after` pages of
+                // this archived scan have undefined intra-cluster order and could skip/duplicate.
+                sorts: [
+                    { propertyName: dateField, direction: 'ASCENDING' },
+                    { propertyName: 'hs_object_id', direction: 'ASCENDING' },
+                ],
                 properties,
                 limit: 100,
                 archived: true,
@@ -2478,7 +2866,14 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         const parsed = this.ParseAssociationPath(obj.APIPath);
         if (!parsed) {
             console.warn(`[HubSpot] Cannot parse association path: ${obj.APIPath}`);
-            return { Records: [], HasMore: false };
+            return {
+                Records: [], HasMore: false,
+                Warnings: [{
+                        Code: 'ASSOCIATION_PATH_UNPARSEABLE',
+                        Message: `Association '${obj.Name}' has an unparseable APIPath '${obj.APIPath}' — cannot determine the from/to object types, so 0 associations were fetched (not a real "no data" result).`,
+                        Data: { object: obj.Name, apiPath: obj.APIPath },
+                    }],
+            };
         }
         const { fromType, toType } = parsed;
         const auth = await this.Authenticate(ctx.CompanyIntegration, ctx.ContextUser);
@@ -2490,6 +2885,23 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         const parentIDs = await this.LoadAssociationParentIDs(fromType, ctx);
         const parentOffset = ctx.CurrentOffset ?? 0;
         const BATCH_LIMIT = 100; // HubSpot v4 batch/read max inputs per request
+        // Zero parents on the FIRST page = the silent-empty case for a second-layer object: there is
+        // no parent `fromType` data in MJ to read associations from (parent not synced/mapped, or its
+        // entity-map disabled, or DAG ordered this before its parent). Surface it as a structured
+        // FetchWarning so the engine records it in the run artifact (visible over GraphQL) instead
+        // of a quiet zero-record "success". Subsequent pages legitimately exhaust to 0 — not flagged.
+        if (parentOffset === 0 && parentIDs.length === 0) {
+            console.warn(`[HubSpot] Association '${obj.Name}': 0 parent ${fromType} records in MJ — nothing to associate.`);
+            return {
+                Records: [],
+                HasMore: false,
+                Warnings: [{
+                        Code: 'ZERO_PARENTS',
+                        Message: `Association '${obj.Name}' has no parent ${fromType} records in MJ to read associations from — '${fromType}' was not synced/mapped this run (or its entity-map is disabled). 0 associations fetched.`,
+                        Data: { object: obj.Name, parentType: fromType },
+                    }],
+            };
+        }
         if (parentOffset === 0) {
             console.log(`[HubSpot] Fetching ${obj.Name}: ${parentIDs.length} parent ${fromType} via batch API (100/request)`);
         }
@@ -2515,8 +2927,10 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         if (response.Status < 200 || response.Status >= 300) {
             const respBody = response.Body;
             const msg = respBody?.message ?? respBody?.error ?? JSON.stringify(respBody);
-            console.warn(`[HubSpot] Association batch read failed for ${objectName}: HTTP ${response.Status} — ${msg}`);
-            return [];
+            // Surface as a real error (the engine's fetch handler records it as sync.record.error in
+            // the run artifact) instead of a swallowed console.warn + empty result that reads as a
+            // successful "no associations" — a non-2xx batch/read is a failure, not absence of data.
+            throw new Error(`[HubSpot] Association batch read failed for ${objectName}: HTTP ${response.Status} — ${msg}`);
         }
         const respBody = response.Body;
         const records = [];
@@ -2605,6 +3019,14 @@ let HubSpotConnector = class HubSpotConnector extends BaseRESTIntegrationConnect
         const obj = HUBSPOT_OBJECTS.find(o => o.Name === objectName);
         return obj ? obj.Fields.map(f => f.Name) : [];
     }
+    /**
+     * Returns the configured upsert key (unique business property to match on) for an
+     * object from HUBSPOT_OBJECTS metadata, or undefined if the object declares none.
+     * Used by Upsert to default the idProperty when the caller doesn't override it.
+     */
+    GetUpsertKey(objectName) {
+        return HUBSPOT_OBJECTS.find(o => o.Name === objectName)?.UpsertKey;
+    }
     /**
      * Returns the effective property list for a HubSpot CRM request.
      *