@memberjunction/integration-engine 5.38.0 → 5.40.0

package/dist/BaseIntegrationConnector.js

@@ -32,15 +32,6 @@ export async function WithTimeout(promise, timeoutMs, operationName) {
         }
     }
 }
-/**
- * Abstract base class for integration connectors.
- * Each external system (HubSpot, Salesforce, etc.) implements this class
- * to provide system-specific data access and discovery.
- *
- * Subclasses declare their capabilities via the `SupportsX` getters.
- * Callers can interrogate a connector instance to determine which
- * operations it supports before attempting them.
- */
 export class BaseIntegrationConnector {
     // ─── Capability Getters ──────────────────────────────────────────
     // Override in subclasses to declare which operations the connector supports.
@@ -51,6 +42,11 @@ export class BaseIntegrationConnector {
     get SupportsCreate() { return false; }
     /** Whether this connector supports updating existing records in the external system. */
     get SupportsUpdate() { return false; }
+    /**
+     * Whether this connector supports idempotent upserts (create-or-update keyed
+     * by a unique business property). Connectors override this AND `Upsert` to enable it.
+     */
+    get SupportsUpsert() { return false; }
     /** Whether this connector supports deleting records from the external system. */
     get SupportsDelete() { return false; }
     /** Whether this connector supports searching/querying records with filters. */
@@ -76,6 +72,15 @@ export class BaseIntegrationConnector {
     async UpdateRecord(_ctx) {
         throw new Error(`UpdateRecord is not supported by ${this.constructor.name}`);
     }
+    /**
+     * Upserts a record — a single idempotent create-or-update keyed by a unique
+     * business property (e.g. email), eliminating the search-then-create race window.
+     * Override in subclasses whose external system exposes a keyed upsert primitive.
+     * Check `SupportsUpsert` before calling.
+     */
+    async Upsert(_ctx) {
+        throw new Error(`Upsert is not supported by ${this.constructor.name}`);
+    }
     /**
      * Deletes a record from the external system.
      * Override in subclasses that support delete operations.
@@ -107,6 +112,79 @@ export class BaseIntegrationConnector {
     async ListRecords(_ctx) {
         throw new Error(`ListRecords is not supported by ${this.constructor.name}`);
     }
+    /**
+     * Builds a CRUDResult for a record CREATE, failing LOUDLY when the external system returned
+     * no usable record ID. A 2xx response with an empty/undefined ID means the create did not
+     * durably produce a record we can track — returning Success:true there silently loses the
+     * record and causes duplicate creates on the next sync (the HubSpot-association class of bug,
+     * fixed in next commit 9f718a7e). This makes that failure explicit at the connector boundary.
+     */
+    BuildCreatedResult(externalID, statusCode, objectName) {
+        const id = externalID == null ? '' : String(externalID).trim();
+        if (id.length === 0) {
+            return {
+                Success: false,
+                StatusCode: statusCode,
+                ErrorMessage: `Create of "${objectName}" returned HTTP ${statusCode} but the response contained no record ID — treating as a failure to avoid silently losing the record (and duplicate creates on the next sync).`,
+            };
+        }
+        return { Success: true, StatusCode: statusCode, ExternalID: id };
+    }
+    // ─── §7/§10/§12 Sync-efficiency contract (composable; connector fills in) ─────────
+    // Optional hooks the universal sync engine consumes for peak-aware rate limiting, adaptive
+    // parallelism, keyset/no-watermark resume, aggressive batch writes, and type-driven
+    // post-processing. EVERY member has a safe default, so existing connectors are unaffected; a
+    // connector "fills out the contract" by overriding what its source supports (plan.md §7/§10/§12).
+    /**
+     * Token-bucket rate-limit policy for this connector's source API (plan.md §7 peak-aware rate
+     * limiting). `null` → the engine derives a conservative rate from Integration.BatchRequestWaitTime.
+     * Override to push to the source's real limits.
+     */
+    get RateLimitPolicy() { return null; }
+    /**
+     * Parse a Retry-After / rate-limit signal out of a failed response or thrown error into
+     * milliseconds so the engine can back off precisely. Return `undefined` when the error is not a
+     * throttle (or carries no hint).
+     */
+    ExtractRetryAfterMs(_error) { return undefined; }
+    /**
+     * Highest SAFE per-layer concurrency the source tolerates (plan.md §7 peak parallelization) — the
+     * ceiling the engine's adaptive controller ramps toward. `null` → use configured syncConcurrency.
+     */
+    get MaxConcurrencyHint() { return null; }
+    /**
+     * Name of a stable, monotonic ordering key (PK/identity) usable for KEYSET/seek resume on
+     * watermark-less objects (plan.md §7 — resume from last-seen key, robust to mid-stream
+     * insert/delete). `null` → keyset resume unavailable for this object.
+     */
+    StableOrderingKey(_objectName) { return null; }
+    /** Whether this connector supports batched target writes (plan.md §7 aggressive batching). */
+    get SupportsBatchWrite() { return false; }
+    /** Batch-create. Default loops single-record CreateRecord, so the engine may always call the batch form. */
+    async BatchCreateRecords(ctxs) {
+        return this.runBatchViaSingles(ctxs, c => this.CreateRecord(c));
+    }
+    /** Batch-update. Default loops single-record UpdateRecord. */
+    async BatchUpdateRecords(ctxs) {
+        return this.runBatchViaSingles(ctxs, c => this.UpdateRecord(c));
+    }
+    /** Batch-delete. Default loops single-record DeleteRecord. */
+    async BatchDeleteRecords(ctxs) {
+        return this.runBatchViaSingles(ctxs, c => this.DeleteRecord(c));
+    }
+    async runBatchViaSingles(ctxs, one) {
+        const out = [];
+        for (const c of ctxs)
+            out.push(await one(c));
+        return out;
+    }
+    /**
+     * Type-driven post-processing hook (plan.md §10): a connector may normalize/enforce a record's
+     * values to the resolved column formats AFTER transform/normalize and BEFORE write. Default
+     * returns the record unchanged. (Named for this system — NOT MCP, not `take`.) The engine ALSO
+     * applies target-type constraint enforcement; this is the connector-side complement.
+     */
+    PostProcessRecord(record) { return record; }
     /**
      * Returns suggested default field mappings for an external object to MJ entity.
      * Override in subclasses to provide intelligent defaults.
@@ -209,6 +287,14 @@ export class BaseIntegrationConnector {
                 if (myIdx >= total)
                     return;
                 const obj = objects[myIdx];
+                const objStart = Date.now();
+                console.log(JSON.stringify({
+                    ts: new Date().toISOString(),
+                    event: 'introspect.object.start',
+                    objectIndex: myIdx + 1,
+                    total,
+                    objectName: obj.Name,
+                }));
                 let fields;
                 try {
                     fields = await this.DiscoverFields(companyIntegration, obj.Name, contextUser);
@@ -216,9 +302,29 @@ export class BaseIntegrationConnector {
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     console.warn(`WARNING: Skipping object "${obj.Name}" — DiscoverFields failed: ${msg}`);
+                    console.log(JSON.stringify({
+                        ts: new Date().toISOString(),
+                        event: 'introspect.object.skipped',
+                        objectIndex: myIdx + 1,
+                        total,
+                        objectName: obj.Name,
+                        error: msg,
+                        durationMs: Date.now() - objStart,
+                    }));
                     skipped++;
                     continue;
                 }
+                console.log(JSON.stringify({
+                    ts: new Date().toISOString(),
+                    event: 'introspect.object.complete',
+                    objectIndex: myIdx + 1,
+                    total,
+                    objectName: obj.Name,
+                    fieldsDiscovered: fields.length,
+                    primaryKeyFields: fields.filter(f => f.IsPrimaryKey).map(f => f.Name),
+                    foreignKeyFields: fields.filter(f => f.IsForeignKey).length,
+                    durationMs: Date.now() - objStart,
+                }));
                 result.Objects.push({
                     ExternalName: obj.Name,
                     ExternalLabel: obj.Label,
@@ -229,15 +335,24 @@ export class BaseIntegrationConnector {
                         Description: f.Description,
                         SourceType: f.DataType,
                         IsRequired: f.IsRequired,
+                        AllowsNull: f.AllowsNull,
                         MaxLength: f.MaxLength ?? null,
                         Precision: f.Precision ?? null,
                         Scale: f.Scale ?? null,
                         DefaultValue: f.DefaultValue ?? null,
-                        IsPrimaryKey: f.IsUniqueKey,
+                        IsPrimaryKey: f.IsPrimaryKey ?? false,
+                        IsUniqueKey: f.IsUniqueKey,
+                        IsReadOnly: f.IsReadOnly,
                         IsForeignKey: f.IsForeignKey ?? false,
                         ForeignKeyTarget: f.ForeignKeyTarget ?? null,
                     })),
-                    PrimaryKeyFields: fields.filter(f => f.IsUniqueKey).map(f => f.Name),
+                    // Honest PK selection: only IsPrimaryKey=true fields qualify.
+                    // Prior behavior used IsUniqueKey which is wrong — an object
+                    // can have multiple unique fields (e.g. email + phone) of which
+                    // only one is the PK. Connectors that don't yet set IsPrimaryKey
+                    // on their DiscoverFields output will return an empty PrimaryKeyFields;
+                    // the runtime PK classifier (Phase 0 D2/D4) handles the residual.
+                    PrimaryKeyFields: fields.filter(f => f.IsPrimaryKey).map(f => f.Name),
                     Relationships: fields
                         .filter(f => (f.IsForeignKey ?? false) && f.ForeignKeyTarget)
                         .map(f => ({

package/dist/BaseIntegrationConnector.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseIntegrationConnector.js","sourceRoot":"","sources":["../src/BaseIntegrationConnector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseIntegrationConnector.js","sourceRoot":"","sources":["../src/BaseIntegrationConnector.ts"],"names":[],"mappings":"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"}

package/dist/BaseRESTIntegrationConnector.d.ts

@@ -1,7 +1,7 @@
 import { type UserInfo } from '@memberjunction/core';
 import type { MJCompanyIntegrationEntity, MJIntegrationObjectEntity, MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
 import { BaseIntegrationConnector, type ExternalObjectSchema, type ExternalFieldSchema, type FetchContext, type FetchBatchResult } from './BaseIntegrationConnector.js';
-import type { SourceSchemaInfo } from './types.js';
+import type { ExternalRecord, SourceSchemaInfo, CreateRecordContext, UpdateRecordContext, DeleteRecordContext, GetRecordContext, CRUDResult } from './types.js';
 /** Authentication context returned by Authenticate(). Concrete connectors extend this. */
 export interface RESTAuthContext {
     /** Bearer or session token */
@@ -88,6 +88,20 @@ export declare abstract class BaseRESTIntegrationConnector extends BaseIntegrati
      * Combined with the object's APIPath to form the full request URL.
      */
     protected abstract GetBaseURL(companyIntegration: MJCompanyIntegrationEntity, auth: RESTAuthContext): string;
+    /**
+     * Optional per-record CUSTOMIZATION hook called between NormalizeResponse
+     * (vendor envelope-stripping) and ToExternalRecord (composite-PK assembly).
+     *
+     * Distinct from NormalizeResponse — that strips the vendor's response envelope
+     * to expose individual records. This hook is for vendor-specific record-level
+     * customization the standard pipeline shouldn't carry: nested-field flattening,
+     * empty-string→null coercion for date columns, computed fields, removing vendor
+     * metadata blobs (e.g. Salesforce 'attributes'), etc.
+     *
+     * Default is identity (no transform). Override only when a concrete connector
+     * needs vendor-specific shape changes.
+     */
+    protected TransformRecord(raw: Record<string, unknown>, _obj: MJIntegrationObjectEntity, _fields: MJIntegrationObjectFieldEntity[]): Record<string, unknown>;
     /**
      * Discovers available objects from the IntegrationEngineBase cache.
      */
@@ -107,33 +121,84 @@ export declare abstract class BaseRESTIntegrationConnector extends BaseIntegrati
      * Handles both flat endpoints and template-variable (per-parent) endpoints.
      */
     FetchChanges(ctx: FetchContext): Promise<FetchBatchResult>;
+    /** Generic create: reads CreateAPIPath/Method/BodyShape/BodyKey/IDLocation from the IO row. */
+    CreateRecord(ctx: CreateRecordContext): Promise<CRUDResult>;
+    /** Generic update: reads UpdateAPIPath/Method/BodyShape/BodyKey/IDLocation from the IO row. */
+    UpdateRecord(ctx: UpdateRecordContext): Promise<CRUDResult>;
+    /** Generic delete: reads DeleteAPIPath/DeleteMethod/DeleteIDLocation from the IO row. */
+    DeleteRecord(ctx: DeleteRecordContext): Promise<CRUDResult>;
+    /** Generic get-one: hits APIPath/{ID} via GET. Override if API uses non-standard get shape. */
+    GetRecord(ctx: GetRecordContext): Promise<ExternalRecord | null>;
+    /**
+     * Build the operation request body per BodyShape:
+     *  - 'flat'    → body = attributes verbatim
+     *  - 'wrapped' → body = { [BodyKey]: attributes }
+     *  - 'literal' → connector should have overridden the operation; fall back to flat as safety net
+     *  - null      → default to flat (most common shape)
+     */
+    protected BuildOperationBody(attributes: Record<string, unknown>, bodyShape: string | null, bodyKey: string | null): unknown;
+    /**
+     * Substitute the ExternalID into a URL path template at runtime. Path templates
+     * may use {ID}, {id}, or {ExternalID} as the placeholder; for symmetry with
+     * FetchChanges template-var handling, any unsubstituted {var} in the template
+     * is left in place (caller's responsibility to ensure consistency).
+     *
+     * For IDLocation='body' or 'header' the ID is not substituted into the path
+     * (caller must handle separately); we just return the raw path.
+     */
+    protected SubstituteIDInPath(path: string, externalID: string, idLocation: string | null): string;
+    /** Best-effort error message extraction from a vendor response. Override for vendor-specific shapes. */
+    protected ExtractErrorMessage(response: RESTResponse): string | undefined;
+    /** Extract the new record's external ID from a create response per IDLocation. */
+    protected ExtractIDFromResponse(response: RESTResponse, idLocation: string | null): string | undefined;
     /**
      * Fetches records from a flat endpoint (no template variable substitution).
      */
     private FetchFlat;
     /**
-     * Fetches records from a template-variable endpoint by iterating over parent records.
-     * Identifies the parent object from FK field metadata, loads parent IDs from the
-     * local database, then fetches child records per parent.
+     * Fetches records from a template-variable endpoint, generalized to MULTI-LEVEL
+     * (nested / chained) paths such as `/orgs/{OrgID}/depts/{DeptID}/employees`.
+     *
+     * Each `{var}` is resolved to a parent IntegrationObject; the engine then walks the
+     * FK dependency graph in path order (outermost first), loading each level's parent
+     * IDs — filtered by the OUTER parent via FK when one links them (true nested
+     * semantics, avoids a cartesian 404 storm), or unfiltered when the vars are
+     * independent — substituting them into the path until it is flat, then fetching.
+     * This is the connector-side realization of the topological traversal the engine
+     * already uses for sync ORDER. A single-var path behaves exactly as before.
      */
     private FetchWithTemplateVars;
     /**
-     * Resolves which template variable maps to which FK field + parent object.
+     * Recursive descent over the ordered template-var resolutions, one layer per level.
+     *
+     * Each layer's records are constrained to the valid SUBSET of the combinations of
+     * ALL prior layers: this level's parent is filtered by an FK to EVERY prior-layer
+     * parent it links to (AND-combined). A prior layer this parent has no FK to leaves
+     * that axis unconstrained (cartesian). So `outerStack` carries every prior layer's
+     * (objectID, idValue) — not just the immediate parent — which is what makes a
+     * layer-2 endpoint depending on both layer-0 and layer-1 prune correctly. At the leaf
+     * (all vars substituted) it fetches with pagination and tags each record with the
+     * resolved parent FK values.
+     */
+    private DescendTemplateVars;
+    /**
+     * Resolves a SINGLE template variable to its parent object + FK field.
      *
-     * Resolution strategy (in order):
-     * 1. Explicit: FK field with RelatedIntegrationObjectID that matches a template var name
-     * 2. PK fallback: finds a sibling integration object whose primary key field name
-     *    matches the template var, allowing resolution without explicit FK metadata
+     * Strategy (in order):
+     * 1. Explicit: an FK field (RelatedIntegrationObjectID) whose name matches the var.
+     * 2. PK fallback: a sibling integration object whose primary-key field name matches
+     *    the var (e.g. {ProfileID} → the Members object whose PK field is "ProfileID"),
+     *    allowing resolution without explicit FK metadata.
      *
-     * Returns null if no match is found by either strategy.
+     * Returns null when neither strategy matches.
      */
-    private ResolveParentInfo;
+    private ResolveParentForVar;
     /**
-     * Fallback resolution: finds a sibling integration object whose primary key
-     * field name matches one of the template variables (case-insensitive).
-     * E.g., {ProfileID} matches Members object which has PK field "ProfileID".
+     * Finds the FK column on `innerObjectID` that points at `outerObjectID` — used to
+     * filter a child level by its parent in a nested path. Returns null when no FK links
+     * them, in which case that level loads unfiltered (independent vars / cartesian).
      */
-    private ResolveParentByPKMatch;
+    private FindFKColumnToParent;
     /**
      * Loads parent record IDs from the local MJ database.
      * Uses IntegrationEngineBase cache for object/field metadata lookups,

package/dist/BaseRESTIntegrationConnector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseRESTIntegrationConnector.d.ts","sourceRoot":"","sources":["../src/BaseRESTIntegrationConnector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseRESTIntegrationConnector.d.ts","sourceRoot":"","sources":["../src/BaseRESTIntegrationConnector.ts"],"names":[],"mappings":"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"}