@memberjunction/connector-hubspot 1.1.0

package/dist/HubSpotConnector.d.ts

@@ -0,0 +1,522 @@
+import { type UserInfo } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity } from '@memberjunction/core-entities';
+import { BaseRESTIntegrationConnector, type RESTAuthContext, type RESTResponse, type PaginationState, type PaginationType, type ConnectionTestResult, type DefaultFieldMapping, type DefaultIntegrationConfig, type FetchContext, type FetchBatchResult, type ExternalRecord, type CRUDResult, type CreateRecordContext, type UpdateRecordContext, type UpsertRecordContext, type DeleteRecordContext, type GetRecordContext, type SearchContext, type SearchResult, type ListContext, type ListResult, type IntegrationObjectInfo, type ActionGeneratorConfig, type ExternalObjectSchema, type ExternalFieldSchema, type SourceSchemaInfo, type RateLimitPolicy } from '@memberjunction/integration-engine';
+/** Connection configuration parsed from CompanyIntegration.Configuration JSON */
+export interface HubSpotConnectionConfig {
+    /** HubSpot Private App access token (API Key auth — Bearer header). */
+    AccessToken: string;
+    /** API version string. Default: 'v3' */
+    ApiVersion: string;
+    /** Maximum retries for rate-limited or failed requests. Default: 5 */
+    MaxRetries?: number;
+    /** HTTP request timeout in milliseconds. Default: 30000 */
+    RequestTimeoutMs?: number;
+    /** Minimum milliseconds between API requests (HubSpot: 100 req/10s for private apps). Default: 100 */
+    MinRequestIntervalMs?: number;
+}
+/** HubSpot property definition (from /crm/v3/properties/{objectType}) */
+interface HubSpotPropertyDef {
+    name: string;
+    label: string;
+    type: string;
+    fieldType: string;
+    groupName: string;
+    description: string;
+    hasUniqueValue: boolean;
+    calculated: boolean;
+    externalOptions: boolean;
+    hidden?: boolean;
+    modificationMetadata?: {
+        readOnlyValue: boolean;
+    };
+}
+/**
+ * Within-scan resume state for the search-based incremental fetch (FetchChangesViaSearch).
+ * Serialized into FetchBatchResult.NextCursor so the engine threads it back via
+ * FetchContext.CurrentCursor on the next call.
+ *
+ * - `after` paginates WITHIN a single ≤10k HubSpot search window (the API's own opaque offset).
+ * - `anchorDateMs` + `anchorId` re-anchor the NEXT window by a (dateField, hs_object_id) keyset
+ *   once the 10k cap is hit, so a window larger than 10k — including a >10k cluster that all shares
+ *   one modified-date — is paged completely instead of stalling on a watermark that cannot advance.
+ */
+interface HubSpotSearchCursor {
+    after?: string;
+    anchorDateMs?: string;
+    anchorId?: string;
+}
+/**
+ * Connector for HubSpot CRM via the HubSpot REST API v3.
+ *
+ * Extends BaseRESTIntegrationConnector to leverage metadata-driven object/field
+ * discovery from IntegrationEngineBase cache and generic pagination handling.
+ *
+ * Uses Bearer token authentication with a HubSpot Private App access token (API Key auth).
+ * Supports cursor-based pagination and automatic response flattening.
+ *
+ * Configuration JSON (on CompanyIntegration) supports optional rate limit overrides:
+ * {
+ *   "accessToken": "...",
+ *   "MaxRetries": 5,              // optional, default: 5
+ *   "RequestTimeoutMs": 30000,    // optional, default: 30000
+ *   "MinRequestIntervalMs": 100   // optional, default: 100
+ * }
+ *
+ * Supports full CRUD: Get, Create, Update, Delete, Search, and List operations
+ * on all HubSpot CRM object types.
+ */
+export declare class HubSpotConnector extends BaseRESTIntegrationConnector {
+    /** Timestamp of the last API request, used for throttling */
+    private lastRequestTime;
+    /** Resolved config (populated after first Authenticate call) */
+    private _config;
+    /** Cached auth context — reused within a session to avoid redundant credential loads */
+    private _cachedAuth;
+    /** Cache of resolved default association typeIds, keyed by `${fromType}/${toType}`. */
+    private _assocTypeIdCache;
+    private get effectiveMaxRetries();
+    private get effectiveRequestTimeoutMs();
+    private get effectiveMinRequestIntervalMs();
+    get SupportsCreate(): boolean;
+    get SupportsUpdate(): boolean;
+    get SupportsUpsert(): boolean;
+    get SupportsDelete(): boolean;
+    get SupportsSearch(): boolean;
+    get SupportsListing(): boolean;
+    get IntegrationName(): string;
+    /** ~10 req/s sustained (honors MinRequestIntervalMs config) with a ~100-request burst window. */
+    get RateLimitPolicy(): RateLimitPolicy;
+    /** HubSpot rate-limits on a rolling 10-second window; on a 429 that escaped internal retries, back off ~10s. */
+    ExtractRetryAfterMs(error: unknown): number | 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(): number;
+    GetIntegrationObjects(): IntegrationObjectInfo[];
+    GetActionGeneratorConfig(): ActionGeneratorConfig | null;
+    /** Known standard HubSpot CRM object type IDs → API names. */
+    /**
+     * All standard CRM object type IDs → names.
+     * Fields discovered live via /crm/v3/properties/{objectType}.
+     * All support: GET, POST, PATCH, DELETE, search (incremental via hs_lastmodifieddate).
+     */
+    private static readonly STANDARD_OBJECTS;
+    /**
+     * Non-CRM API endpoints that don't follow the /crm/v3/objects pattern.
+     * Fields cannot be discovered via /crm/v3/properties — discovered dynamically
+     * by fetching one record and inferring fields from the response.
+     */
+    private static readonly NON_CRM_OBJECTS;
+    /**
+     * Association objects use the v4 per-object associations endpoint.
+     * Fields are fixed (two FK columns + association_type) — no live discovery API exists.
+     */
+    private static readonly ASSOCIATION_OBJECTS;
+    /**
+     * Discovers all HubSpot objects (standard + custom + non-CRM + associations) via live API and static lists.
+     */
+    DiscoverObjects(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<ExternalObjectSchema[]>;
+    /**
+     * Helper to check if an object name is a CRM object (has /crm/v3/properties endpoint).
+     */
+    private IsCRMObject;
+    /**
+     * Finds the non-CRM object config by name.
+     */
+    private GetNonCRMObject;
+    /**
+     * Returns association object config if objectName is an association table, null otherwise.
+     */
+    private GetAssociationObject;
+    /**
+     * Discovers all fields on a HubSpot object via the Properties API.
+     * Returns field types, constraints, PKs, and read-only flags from live metadata.
+     */
+    DiscoverFields(companyIntegration: MJCompanyIntegrationEntity, objectName: string, contextUser: UserInfo): Promise<ExternalFieldSchema[]>;
+    /**
+     * Discovers fields for non-CRM objects by fetching the first page of results
+     * and inferring field names/types from the response.
+     */
+    /**
+     * Non-CRM and association objects have fixed, documented schemas.
+     * - Association objects: return both composite PK fields from ASSOCIATION_OBJECTS config.
+     * - Non-CRM objects: return the PK field from NON_CRM_OBJECTS config.
+     * IntrospectSchema's DB-fallback supplements with the full field list from metadata.
+     * No live API sampling needed.
+     */
+    private DiscoverNonCRMFields;
+    /**
+     * 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.
+     */
+    private static readonly WATERMARK_FIELD_CANDIDATES;
+    /**
+     * 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.
+     */
+    private PickIncrementalWatermarkField;
+    /**
+     * Full schema introspection — discovers all objects and their fields from the live API.
+     */
+    IntrospectSchema(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<SourceSchemaInfo>;
+    /**
+     * Retrieves a single record by ExternalID (HubSpot object ID).
+     */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    /**
+     * Creates a new record in HubSpot.
+     * Routes association objects to the v4 batch/create endpoint instead of v3 objects.
+     */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /**
+     * Updates an existing record in HubSpot by ExternalID.
+     * For association objects, re-creates the association (idempotent in HubSpot).
+     */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /**
+     * 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.
+     */
+    Upsert(ctx: UpsertRecordContext): Promise<CRUDResult>;
+    /**
+     * Deletes (archives) a record in HubSpot by ExternalID.
+     * Routes association objects to the v4 batch/archive endpoint instead of v3 objects.
+     */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /**
+     * Creates an association in HubSpot using the v4 batch/create endpoint.
+     * ExternalID returned is "{leftID}|{rightID}" matching the pull ExternalID format.
+     */
+    private CreateAssociation;
+    /**
+     * Removes an association in HubSpot using the v4 batch/archive endpoint.
+     * ExternalID must be "{leftID}|{rightID}" — the same format stored by pull sync.
+     */
+    private DeleteAssociation;
+    /**
+     * Searches HubSpot objects using the CRM search API.
+     */
+    SearchRecords(ctx: SearchContext): Promise<SearchResult>;
+    /**
+     * Lists records from a HubSpot object with cursor-based pagination.
+     */
+    ListRecords(ctx: ListContext): Promise<ListResult>;
+    /** Converts a raw HubSpot API object to an ExternalRecord. */
+    private RawToExternalRecord;
+    /** Validates a CRUD response and throws on non-2xx status. */
+    private ValidateCRUDResponse;
+    /**
+     * 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.
+     */
+    private GetAssociationWireTypes;
+    /**
+     * 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).
+     */
+    private ResolveAssociationTypeId;
+    /**
+     * 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.
+     */
+    private GetAssociationBatchError;
+    /**
+     * 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.
+     */
+    private GetBatchUpsertError;
+    /** Builds a CRUDResult for error responses. */
+    private BuildCRUDErrorResult;
+    protected Authenticate(companyIntegration: MJCompanyIntegrationEntity, contextUser: UserInfo): Promise<RESTAuthContext>;
+    protected BuildHeaders(auth: RESTAuthContext): Record<string, string>;
+    protected MakeHTTPRequest(_auth: RESTAuthContext, url: string, method: string, headers: Record<string, string>, body?: unknown): Promise<RESTResponse>;
+    protected NormalizeResponse(rawBody: unknown, responseDataKey: string | null): Record<string, unknown>[];
+    protected ExtractPaginationInfo(rawBody: unknown, _paginationType: PaginationType, _currentPage: number, _currentOffset: number, _pageSize: number): PaginationState;
+    protected GetBaseURL(_companyIntegration: MJCompanyIntegrationEntity, _auth: RESTAuthContext): string;
+    /**
+     * Overrides base pagination URL building to use HubSpot's parameter names.
+     * HubSpot uses `after` for cursor pagination (not `cursor`), and needs
+     * `limit` instead of `pageSize`. Also appends `properties` query param.
+     */
+    protected BuildPaginatedURL(basePath: string, obj: MJIntegrationObjectEntity, _page: number, _offset: number, cursor?: string): string;
+    /** Tests connectivity by authenticating and fetching 1 contact. */
+    TestConnection(companyIntegration: MJCompanyIntegrationEntity, _contextUser: UserInfo): Promise<ConnectionTestResult>;
+    GetDefaultFieldMappings(objectName: string, _entityName: string): DefaultFieldMapping[];
+    GetDefaultConfiguration(): DefaultIntegrationConfig;
+    /** Converts a HubSpot property definition to ExternalFieldSchema format */
+    MapPropertyToField(prop: HubSpotPropertyDef): {
+        Name: string;
+        Label: string;
+        DataType: string;
+        IsRequired: boolean;
+        IsUniqueKey: boolean;
+        IsReadOnly: boolean;
+    };
+    /** Maps HubSpot type + fieldType to a simplified data type string */
+    MapHubSpotType(type: string, fieldType: string): string;
+    /**
+     * Builds a HubSpotConnectionConfig from credentials and optional overrides
+     * from the CompanyIntegration Configuration JSON.
+     */
+    private BuildConnectionConfig;
+    /**
+     * Parses optional performance overrides from Configuration JSON and applies
+     * them to the provided config object. Invalid/missing values are silently ignored.
+     */
+    private ApplyConfigOverrides;
+    /**
+     * Reads credentials from CompanyIntegration.CredentialID -> Credential.Values JSON,
+     * or falls back to CompanyIntegration Configuration JSON for backwards compat.
+     */
+    private LoadCredentials;
+    /** Loads credentials from a Credential entity by ID. */
+    private LoadFromCredentialEntity;
+    /** Parses a JSON string to extract HubSpot credentials. Returns null if no token found. */
+    private ParseCredentialJson;
+    /**
+     * Flattens a HubSpot CRM record from the nested format:
+     *   { id, properties: { field1, field2 }, createdAt, updatedAt, archived }
+     * into a flat record with all properties at the top level,
+     * plus system fields (hs_object_id, createdAt, updatedAt, archived).
+     */
+    private FlattenHubSpotRecord;
+    /**
+     * Overrides FetchChanges to support three fetch strategies:
+     *
+     * 1. **Association objects** → v4 per-object associations endpoint
+     * 2. **Incremental sync** (watermark set) → HubSpot search API with server-side
+     *    `hs_lastmodifieddate >= watermark` filter
+     * 3. **Full load** (no watermark / first sync) → standard list API via base class
+     */
+    FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * Full-load path for CRM objects (first sync, no watermark).
+     * Uses the CRM list endpoint with property expansion and FlattenHubSpotRecord so that
+     * ExternalID is correctly built from hs_object_id (mirroring FetchChangesViaSearch).
+     * The base class FetchChanges cannot be used here because it reads raw[field] without
+     * flattening, causing ExternalID="" for every record.
+     */
+    private FetchCRMFullLoad;
+    /**
+     * Fetches all pages from a single non-CRM API endpoint URL, accumulating all records.
+     * Used as a building block for both flat and parameterized endpoint fetches.
+     */
+    private FetchAllPagesFromURL;
+    /**
+     * Handles parameterized endpoints (apiPath with {placeholder}) by fan-out:
+     * fetches all parent records, then fetches children for each parent ID.
+     * All child records are accumulated and returned as a single batch (HasMore: false).
+     *
+     * Skips objects where parentObject is not found in NON_CRM_OBJECTS (config error).
+     * Skips objects with {appId} placeholder — these require Developer App configuration.
+     */
+    private FetchParameterizedChanges;
+    /**
+     * Fetches records from non-CRM HubSpot APIs (Marketing, CMS, Files, etc.).
+     * These endpoints use standard REST list pagination, not the CRM search API.
+     * Watermark filtering is client-side based on date fields in the response.
+     *
+     * Dispatches to FetchParameterizedChanges when apiPath contains {placeholder}.
+     */
+    private FetchNonCRMChanges;
+    /**
+     * Find the latest date value across common date fields in a set of records.
+     */
+    private FindLatestDateInFields;
+    /**
+     * 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).
+     */
+    protected FetchChangesViaSearch(ctx: FetchContext): Promise<FetchBatchResult>;
+    /**
+     * 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.
+     */
+    protected parseSearchCursor(raw: string | undefined): HubSpotSearchCursor;
+    /**
+     * 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.
+     */
+    private extractSearchAnchor;
+    /**
+     * 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.
+     */
+    private toEpochMs;
+    /**
+     * 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).
+     */
+    protected computeSearchResume(args: {
+        incoming: HubSpotSearchCursor;
+        pagingNextAfter: string | undefined;
+        total: number;
+        lastAnchorDateMs: string | undefined;
+        lastAnchorId: string | undefined;
+    }): {
+        nextCursor: HubSpotSearchCursor | undefined;
+        hasMore: boolean;
+        stalled?: boolean;
+    };
+    /**
+     * Detects archived (deleted) CRM records since the given watermark.
+     *
+     * Uses the HubSpot search API with `archived: true` so the same server-side
+     * GTE watermark filter applies — only records archived/modified since the last
+     * sync are returned. Returns them with `IsDeleted: true` so the integration
+     * engine routes them through the delete pipeline.
+     *
+     * Falls back to empty on any API error (e.g. object type doesn't support
+     * archived search) so delete detection degrades gracefully rather than
+     * blocking the active-record sync.
+     */
+    private FetchArchivedCRMChanges;
+    /** Returns the watermark date field name for a given object type. */
+    private GetWatermarkField;
+    /** Finds the latest date value across records for a given field name. */
+    private FindLatestDate;
+    /**
+     * Fetches association records in batches by iterating over synced parent (from-side)
+     * objects and calling HubSpot's v4 per-object associations endpoint.
+     *
+     * Uses ctx.CurrentOffset to track parent position across batch calls, so the engine
+     * can page through all parents without truncating records.
+     */
+    /**
+     * Fetches association records using the HubSpot v4 batch/read endpoint.
+     * Batches up to 100 parent IDs per request instead of one GET per parent,
+     * reducing API calls from O(n) to O(n/100).
+     */
+    private FetchAssociationChanges;
+    /**
+     * Calls POST /crm/v4/associations/{fromType}/{toType}/batch/read with up to 100 parent IDs.
+     * Response format: { results: [{ from: { id }, to: [{ toObjectId, associationTypes }] }] }
+     */
+    private FetchAssociationBatch;
+    /**
+     * Converts a HubSpot v4 association result item into a flat record suitable for storage.
+     * v4 format: { toObjectId: number, associationTypes: [{ label, typeId, category }] }
+     */
+    private FlattenAssociationRecord;
+    /**
+     * Parses a v4 associations APIPath to extract from/to object type names.
+     * E.g., "/crm/v4/associations/contacts/companies" → { fromType: "contacts", toType: "companies" }
+     */
+    private ParseAssociationPath;
+    /**
+     * Loads hs_object_id values for all synced records of a given HubSpot object type
+     * by finding its entity map and querying the local MJ entity.
+     */
+    private LoadAssociationParentIDs;
+    /**
+     * Extracts the HubSpot object name from an API path.
+     * E.g., "/crm/v3/objects/contacts" -> "contacts"
+     */
+    private ExtractObjectNameFromPath;
+    /**
+     * Returns the known field names for a HubSpot object type, derived from
+     * the HUBSPOT_OBJECTS metadata (single source of truth).
+     */
+    private GetObjectFieldNames;
+    /**
+     * 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.
+     */
+    private GetUpsertKey;
+    /**
+     * Returns the effective property list for a HubSpot CRM request.
+     *
+     * When `requestedFields` (from FetchContext.RequestedSourceFields) is provided it
+     * contains the source fields from active field maps, including any custom properties.
+     * We merge those with the essential system properties so watermark tracking always works.
+     *
+     * Falls back to the static HUBSPOT_OBJECTS field list when no requestedFields are given.
+     *
+     * Note: hs_object_id is NOT included — it's the top-level `id` field on every HubSpot
+     * response and is injected by FlattenHubSpotRecord regardless of `?properties=`.
+     * Essential system properties (always included):
+     * - GetWatermarkField(objectName) — the per-object modified-date property (object-specific;
+     *   contacts use 'lastmodifieddate', all others use 'hs_lastmodifieddate')
+     * - createdate — creation timestamp
+     */
+    private BuildEffectiveProperties;
+    /**
+     * Builds the `properties` query parameter for a HubSpot object type.
+     * Accepts optional `requestedFields` from FetchContext to include custom-mapped properties.
+     * Returns empty string if no properties are configured for the object.
+     */
+    private BuildPropertiesParam;
+    /** Executes an HTTP request with a timeout and optional JSON body. */
+    private FetchWithTimeout;
+    /** Calculates retry delay from Retry-After header or exponential backoff. */
+    private CalculateRetryDelay;
+    /** Converts a fetch Response + parsed body into a RESTResponse. */
+    private BuildRESTResponse;
+    /** Returns a promise that resolves after the specified number of milliseconds. */
+    private Sleep;
+}
+export {};