@memberjunction/integration-engine 5.38.0 → 5.40.0

package/dist/HashDiff.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { computeContentHash } from './ContentHash.js';
+/**
+ * Partitioned / Merkle-style hash-diff (§7 "hash-diff / full-table compare to find changed
+ * partitions cheaply when no incremental cursor exists").
+ *
+ * The problem: some sources have NO usable watermark — they can't tell us "what changed since T"
+ * (e.g. YourMembership re-fetches every record every time). Per-record content hashing
+ * (`computeContentHash`) already lets us skip the per-record load+write for the unchanged majority,
+ * but we still have to FETCH every record to hash it. When the remote can expose a cheap per-PARTITION
+ * rollup hash (a folder digest, an aggregated checksum, or just a previously-stored snapshot of one),
+ * we can compare partition rollups first and only deep-fetch the partitions whose rollup moved.
+ *
+ * This module builds the local side of that comparison ON TOP of `computeContentHash`:
+ *   1. `partitionRecords`     — bucket records by an arbitrary partition key.
+ *   2. `partitionRollupHash`  — fold each bucket's per-record hashes into ONE order-independent digest.
+ *   3. `diffPartitions`       — compare two partition→rollup maps; only the differing partitions
+ *                               (changed/added/removed) need a deep re-sync.
+ *
+ * Everything here is pure, deterministic, and free of DB/network — it operates on in-memory
+ * record arrays and plain string→string maps, so it is cheaply unit-testable and reusable on either
+ * side of the comparison.
+ */
+/**
+ * Stable partition bucket for a record IDENTITY (e.g. its ExternalID). Hashing the identity (not the
+ * content) keeps a record in the SAME partition across syncs even when its content changes — so a
+ * content edit shows up as a *changed partition* rather than a record hopping buckets. SHA-256 of the
+ * id, first 4 bytes folded modulo `partitionCount`, gives an even, deterministic spread. Default 256
+ * buckets is a sane balance (few enough rollups to store, fine-grained enough to skip most work).
+ */
+export function partitionKeyForIdentity(identity, partitionCount = 256) {
+    const hex = createHash('sha256').update(identity).digest('hex').slice(0, 8);
+    return String(parseInt(hex, 16) % Math.max(1, partitionCount));
+}
+/**
+ * Buckets records by a partition key. `getKey` is accepted to keep the call shape symmetric with
+ * the rest of the diff pipeline (callers thread a stable record identity through partition + rollup);
+ * partitioning itself only needs `getPartition`. Returns a Map keyed by partition string, each value
+ * the array of records that fall in that partition. Records arrive in the order encountered — order
+ * is preserved within a bucket and never relied upon by the rollup (see `partitionRollupHash`).
+ */
+export function partitionRecords(records, getKey, getPartition) {
+    // getKey is part of the documented signature (callers pass a record-identity accessor) but
+    // bucketing is driven purely by partition; reference it so the contract stays explicit.
+    void getKey;
+    const buckets = new Map();
+    for (const record of records) {
+        const partition = getPartition(record);
+        const bucket = buckets.get(partition);
+        if (bucket) {
+            bucket.push(record);
+        }
+        else {
+            buckets.set(partition, [record]);
+        }
+    }
+    return buckets;
+}
+/**
+ * ORDER-INDEPENDENT rollup of a partition's records into a single hash. Each record's mapped fields
+ * are content-hashed via `computeContentHash`, the per-record hashes are SORTED, then the sorted list
+ * is concatenated and SHA-256'd. Sorting before combining is what makes the rollup stable regardless
+ * of the order records were fetched in — `[a,b]` and `[b,a]` produce the identical partition digest,
+ * so a re-fetch that merely reorders rows never spuriously flags the partition as changed.
+ *
+ * An empty partition rolls up to the SHA-256 of the empty string, a stable sentinel distinct from any
+ * non-empty partition.
+ */
+export function partitionRollupHash(records, fieldsOf) {
+    const recordHashes = records.map(record => computeContentHash(fieldsOf(record)));
+    recordHashes.sort();
+    // Length-prefix each hash so the concatenation is unambiguous and can't collide across different
+    // record counts. SHA-256 hex is fixed-width, but the prefix keeps the combine future-proof.
+    const combined = recordHashes.map(hash => `${hash.length}:${hash}`).join('');
+    return createHash('sha256').update(combined).digest('hex');
+}
+/**
+ * Compares two partition→rollup maps and reports which partitions diverge. Only `changed`/`added`/
+ * `removed` partitions need a deep re-sync; partitions whose rollup matches on both sides are proven
+ * identical and can be skipped entirely. The result arrays are sorted for deterministic output.
+ *
+ * - `changed` — key in BOTH maps, rollup values differ.
+ * - `added`   — key in `local` only.
+ * - `removed` — key in `remote` only.
+ */
+export function diffPartitions(local, remote) {
+    const changed = [];
+    const added = [];
+    for (const [partition, localRollup] of local) {
+        if (!remote.has(partition)) {
+            added.push(partition);
+        }
+        else if (remote.get(partition) !== localRollup) {
+            changed.push(partition);
+        }
+    }
+    const removed = [];
+    for (const partition of remote.keys()) {
+        if (!local.has(partition)) {
+            removed.push(partition);
+        }
+    }
+    changed.sort();
+    added.sort();
+    removed.sort();
+    return { changed, added, removed };
+}
+//# sourceMappingURL=HashDiff.js.map

package/dist/HashDiff.js.map

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

package/dist/IntegrationActionGenerator.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview On-demand Integration-as-Actions PERSISTER service.
+ *
+ * Where `ActionMetadataGenerator` produces mj-sync JSON for the design-time CLI,
+ * this service generates AND persists a single strongly-typed Action (for one
+ * integration / object / verb) directly to the MJ database via BaseEntity.Save().
+ *
+ * It is the runtime, idempotent counterpart used when an agent/workflow needs an
+ * integration action created on the fly:
+ *
+ *   1. Load the IntegrationObject + its IntegrationObjectFields from the DB.
+ *   2. Map them into ActionMetadataGenerator's IntegrationObjectInfo shape.
+ *   3. Run the SAME generator the CLI uses, then pick the requested verb's record.
+ *   4. Find-or-create the Action Category, then upsert the Action + its params +
+ *      result codes (idempotent on the deterministic Action Name).
+ *
+ * The generated Action uses DriverClass='IntegrationActionExecutor' and stores
+ * routing info ({IntegrationName, ObjectName, Verb}) in Action.Config_ — the
+ * IntegrationActionExecutor (CoreActions) is the single runtime dispatcher.
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+/** CRUD verb that an integration action can dispatch to */
+export type IntegrationActionVerb = 'Get' | 'Create' | 'Update' | 'Delete' | 'Upsert' | 'Search' | 'List';
+/** Result of generating+persisting a single integration action */
+export interface GenerateIntegrationActionResult {
+    Success: boolean;
+    ActionID?: string;
+    ActionName?: string;
+    Verb: IntegrationActionVerb;
+    ObjectName: string;
+    /** True if a matching action already existed and was reused (idempotent reuse) */
+    AlreadyExisted: boolean;
+    Message: string;
+}
+/**
+ * Generates and persists strongly-typed integration actions on demand.
+ * Idempotent: reuses an existing Action with the same deterministic Name and
+ * reconciles its params/result codes rather than duplicating.
+ */
+export declare class IntegrationActionGenerator {
+    /** All verbs in canonical order, used by GenerateActionsForObject */
+    private static readonly AllVerbs;
+    /**
+     * Generate + persist ONE strongly-typed action for (integration, object, verb).
+     * Idempotent on the deterministic Name "<Integration> - <Verb> <DisplayName>".
+     */
+    GenerateAction(integrationName: string, objectName: string, verb: IntegrationActionVerb, contextUser: UserInfo, provider?: IMetadataProvider): Promise<GenerateIntegrationActionResult>;
+    /**
+     * Generate all applicable verbs for an object. Get/Search/List are always
+     * applicable; Create/Update/Delete/Upsert only when the object SupportsWrite.
+     */
+    GenerateActionsForObject(integrationName: string, objectName: string, contextUser: UserInfo, provider?: IMetadataProvider): Promise<GenerateIntegrationActionResult[]>;
+    private resolveProvider;
+    private applicableVerbs;
+    /**
+     * Loads the IntegrationObject (by integration name + object name) and its
+     * fields from the DB, mapping them into the generator's IntegrationObjectInfo.
+     */
+    private loadObjectInfo;
+    private loadObjectFields;
+    private mapField;
+    /**
+     * Runs ActionMetadataGenerator for this single object and returns the
+     * generated record for the requested verb (matched by its Config.Verb).
+     * Returns null if the verb isn't produced (e.g., write verb on read-only object).
+     */
+    private buildActionRecord;
+    /** Find-or-create the flat "<IntegrationName> Integration" Action Category. */
+    private ensureCategory;
+    private categoryName;
+    /**
+     * Upserts the Action: reuses an existing one with the same deterministic Name
+     * (AlreadyExisted=true, params/result codes reconciled) or creates a new one.
+     */
+    private persistAction;
+    private findExistingAction;
+    private applyActionFields;
+    /**
+     * Persists Action Params. On reuse, deletes the existing params first so the
+     * recreated set stays exactly in sync with the freshly generated metadata.
+     */
+    private persistParams;
+    /**
+     * Persists Action Result Codes. On reuse, deletes the existing ones first to
+     * keep them in sync with the generated metadata.
+     */
+    private persistResultCodes;
+    /** Loads and deletes all rows of a child entity linked to the given ActionID. */
+    private deleteRelated;
+    private escape;
+    private failure;
+}
+//# sourceMappingURL=IntegrationActionGenerator.d.ts.map

package/dist/IntegrationActionGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationActionGenerator.d.ts","sourceRoot":"","sources":["../src/IntegrationActionGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAqB,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAkBhG,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1G,kEAAkE;AAClE,MAAM,WAAW,+BAA+B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACnB;AAkBD;;;;GAIG;AACH,qBAAa,0BAA0B;IAEnC,qEAAqE;IACrE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAE9B;IAEF;;;OAGG;IACU,cAAc,CACvB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,qBAAqB,EAC3B,WAAW,EAAE,QAAQ,EACrB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,+BAA+B,CAAC;IAuB3C;;;OAGG;IACU,wBAAwB,CACjC,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,QAAQ,EACrB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,+BAA+B,EAAE,CAAC;IAkB7C,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,eAAe;IASvB;;;OAGG;YACW,cAAc;YA8Bd,gBAAgB;IAiB9B,OAAO,CAAC,QAAQ;IAchB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,+EAA+E;YACjE,cAAc;IA+B5B,OAAO,CAAC,YAAY;IAMpB;;;OAGG;YACW,aAAa;YAwCb,kBAAkB;IAgBhC,OAAO,CAAC,iBAAiB;IAiBzB;;;OAGG;YACW,aAAa;IA6B3B;;;OAGG;YACW,kBAAkB;IA0BhC,iFAAiF;YACnE,aAAa;IAwB3B,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,OAAO;CAOlB"}

package/dist/IntegrationActionGenerator.js

@@ -0,0 +1,313 @@
+/**
+ * @fileoverview On-demand Integration-as-Actions PERSISTER service.
+ *
+ * Where `ActionMetadataGenerator` produces mj-sync JSON for the design-time CLI,
+ * this service generates AND persists a single strongly-typed Action (for one
+ * integration / object / verb) directly to the MJ database via BaseEntity.Save().
+ *
+ * It is the runtime, idempotent counterpart used when an agent/workflow needs an
+ * integration action created on the fly:
+ *
+ *   1. Load the IntegrationObject + its IntegrationObjectFields from the DB.
+ *   2. Map them into ActionMetadataGenerator's IntegrationObjectInfo shape.
+ *   3. Run the SAME generator the CLI uses, then pick the requested verb's record.
+ *   4. Find-or-create the Action Category, then upsert the Action + its params +
+ *      result codes (idempotent on the deterministic Action Name).
+ *
+ * The generated Action uses DriverClass='IntegrationActionExecutor' and stores
+ * routing info ({IntegrationName, ObjectName, Verb}) in Action.Config_ — the
+ * IntegrationActionExecutor (CoreActions) is the single runtime dispatcher.
+ */
+import { Metadata, RunView, LogError } from '@memberjunction/core';
+import { ActionMetadataGenerator, } from './ActionMetadataGenerator.js';
+// ─── Service ─────────────────────────────────────────────────────────
+/**
+ * Generates and persists strongly-typed integration actions on demand.
+ * Idempotent: reuses an existing Action with the same deterministic Name and
+ * reconciles its params/result codes rather than duplicating.
+ */
+export class IntegrationActionGenerator {
+    /** All verbs in canonical order, used by GenerateActionsForObject */
+    static { this.AllVerbs = [
+        'Get', 'Create', 'Update', 'Delete', 'Upsert', 'Search', 'List',
+    ]; }
+    /**
+     * Generate + persist ONE strongly-typed action for (integration, object, verb).
+     * Idempotent on the deterministic Name "<Integration> - <Verb> <DisplayName>".
+     */
+    async GenerateAction(integrationName, objectName, verb, contextUser, provider) {
+        const md = this.resolveProvider(provider);
+        try {
+            const objectInfo = await this.loadObjectInfo(md, integrationName, objectName, contextUser);
+            if (!objectInfo) {
+                return this.failure(verb, objectName, `IntegrationObject "${objectName}" not found for integration "${integrationName}"`);
+            }
+            const record = this.buildActionRecord(integrationName, objectInfo, verb);
+            if (!record) {
+                return this.failure(verb, objectName, `Verb "${verb}" is not applicable to object "${objectName}" (write not supported)`);
+            }
+            const categoryID = await this.ensureCategory(md, integrationName, contextUser);
+            return await this.persistAction(md, record, verb, objectName, categoryID, contextUser);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return this.failure(verb, objectName, `Unexpected error: ${msg}`);
+        }
+    }
+    /**
+     * Generate all applicable verbs for an object. Get/Search/List are always
+     * applicable; Create/Update/Delete/Upsert only when the object SupportsWrite.
+     */
+    async GenerateActionsForObject(integrationName, objectName, contextUser, provider) {
+        const md = this.resolveProvider(provider);
+        const objectInfo = await this.loadObjectInfo(md, integrationName, objectName, contextUser);
+        if (!objectInfo) {
+            return [this.failure('Get', objectName, `IntegrationObject "${objectName}" not found for integration "${integrationName}"`)];
+        }
+        const verbs = this.applicableVerbs(objectInfo.SupportsWrite);
+        const results = [];
+        for (const verb of verbs) {
+            results.push(await this.GenerateAction(integrationName, objectName, verb, contextUser, provider));
+        }
+        return results;
+    }
+    // ─── Provider ────────────────────────────────────────────────────
+    resolveProvider(provider) {
+        return provider ?? Metadata.Provider;
+    }
+    applicableVerbs(supportsWrite) {
+        return IntegrationActionGenerator.AllVerbs.filter(v => {
+            if (v === 'Create' || v === 'Update' || v === 'Delete' || v === 'Upsert')
+                return supportsWrite;
+            return true; // Get, Search, List always
+        });
+    }
+    // ─── Object Loading ──────────────────────────────────────────────
+    /**
+     * Loads the IntegrationObject (by integration name + object name) and its
+     * fields from the DB, mapping them into the generator's IntegrationObjectInfo.
+     */
+    async loadObjectInfo(md, integrationName, objectName, contextUser) {
+        const rv = RunView.FromMetadataProvider(md);
+        const objResult = await rv.RunView({
+            EntityName: 'MJ: Integration Objects',
+            ExtraFilter: `Integration='${this.escape(integrationName)}' AND Name='${this.escape(objectName)}'`,
+            MaxRows: 1,
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!objResult.Success || objResult.Results.length === 0) {
+            return null;
+        }
+        const obj = objResult.Results[0];
+        const fields = await this.loadObjectFields(md, obj.ID, contextUser);
+        return {
+            Name: obj.Name,
+            DisplayName: obj.DisplayName ?? obj.Name,
+            Description: obj.Description ?? undefined,
+            SupportsWrite: obj.SupportsWrite,
+            Fields: fields,
+        };
+    }
+    async loadObjectFields(md, integrationObjectID, contextUser) {
+        const rv = RunView.FromMetadataProvider(md);
+        const fieldResult = await rv.RunView({
+            EntityName: 'MJ: Integration Object Fields',
+            ExtraFilter: `IntegrationObjectID='${this.escape(integrationObjectID)}'`,
+            OrderBy: 'Sequence ASC, Name ASC',
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!fieldResult.Success)
+            return [];
+        return fieldResult.Results.map(f => this.mapField(f));
+    }
+    mapField(f) {
+        return {
+            Name: f.Name,
+            DisplayName: f.DisplayName ?? f.Name,
+            Description: f.Description ?? undefined,
+            Type: f.Type,
+            IsRequired: f.IsRequired,
+            IsReadOnly: f.IsReadOnly,
+            IsPrimaryKey: f.IsPrimaryKey,
+        };
+    }
+    // ─── Metadata Generation ─────────────────────────────────────────
+    /**
+     * Runs ActionMetadataGenerator for this single object and returns the
+     * generated record for the requested verb (matched by its Config.Verb).
+     * Returns null if the verb isn't produced (e.g., write verb on read-only object).
+     */
+    buildActionRecord(integrationName, objectInfo, verb) {
+        const config = {
+            IntegrationName: integrationName,
+            CategoryName: this.categoryName(integrationName),
+            Objects: [objectInfo],
+            // Search/List handled per-verb below; keep them in the generated set.
+            IncludeSearch: true,
+            IncludeList: true,
+            CreateCategory: false, // category is persisted separately via ensureCategory
+        };
+        const generated = new ActionMetadataGenerator().Generate(config);
+        const match = generated.ActionRecords.find(r => r.fields['Config']?.Verb === verb);
+        return match ?? null;
+    }
+    // ─── Category ────────────────────────────────────────────────────
+    /** Find-or-create the flat "<IntegrationName> Integration" Action Category. */
+    async ensureCategory(md, integrationName, contextUser) {
+        const name = this.categoryName(integrationName);
+        const rv = RunView.FromMetadataProvider(md);
+        const existing = await rv.RunView({
+            EntityName: 'MJ: Action Categories',
+            ExtraFilter: `Name='${this.escape(name)}'`,
+            MaxRows: 1,
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (existing.Success && existing.Results.length > 0) {
+            return existing.Results[0].ID;
+        }
+        const cat = await md.GetEntityObject('MJ: Action Categories', contextUser);
+        cat.NewRecord();
+        cat.Name = name;
+        cat.Description = `Actions for the ${integrationName} integration`;
+        cat.Status = 'Active';
+        const saved = await cat.Save();
+        if (!saved) {
+            LogError(`IntegrationActionGenerator: failed to create category '${name}': ${cat.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            return null;
+        }
+        return cat.ID;
+    }
+    categoryName(integrationName) {
+        return `${integrationName} Integration`;
+    }
+    // ─── Persistence (idempotent) ────────────────────────────────────
+    /**
+     * Upserts the Action: reuses an existing one with the same deterministic Name
+     * (AlreadyExisted=true, params/result codes reconciled) or creates a new one.
+     */
+    async persistAction(md, record, verb, objectName, categoryID, contextUser) {
+        const actionName = record.fields['Name'];
+        const existing = await this.findExistingAction(md, actionName, contextUser);
+        const action = existing ?? await md.GetEntityObject('MJ: Actions', contextUser);
+        const alreadyExisted = !!existing;
+        if (!alreadyExisted) {
+            action.NewRecord();
+        }
+        this.applyActionFields(action, record, categoryID);
+        const saved = await action.Save();
+        if (!saved) {
+            return this.failure(verb, objectName, `Failed to save action '${actionName}': ${action.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        await this.persistParams(md, action.ID, record, alreadyExisted, contextUser);
+        await this.persistResultCodes(md, action.ID, record, alreadyExisted, contextUser);
+        return {
+            Success: true,
+            ActionID: action.ID,
+            ActionName: actionName,
+            Verb: verb,
+            ObjectName: objectName,
+            AlreadyExisted: alreadyExisted,
+            Message: alreadyExisted
+                ? `Reused existing action '${actionName}' and reconciled its params/result codes`
+                : `Created action '${actionName}'`,
+        };
+    }
+    async findExistingAction(md, actionName, contextUser) {
+        const rv = RunView.FromMetadataProvider(md);
+        const result = await rv.RunView({
+            EntityName: 'MJ: Actions',
+            ExtraFilter: `Name='${this.escape(actionName)}'`,
+            MaxRows: 1,
+            ResultType: 'entity_object',
+        }, contextUser);
+        return result.Success && result.Results.length > 0 ? result.Results[0] : null;
+    }
+    applyActionFields(action, record, categoryID) {
+        action.Name = record.fields['Name'];
+        action.Description = record.fields['Description'] ?? '';
+        action.Type = 'Custom';
+        action.Status = 'Active';
+        action.DriverClass = record.fields['DriverClass'] ?? 'IntegrationActionExecutor';
+        const configObj = record.fields['Config'];
+        action.Config_ = typeof configObj === 'string' ? configObj : JSON.stringify(configObj);
+        if (categoryID)
+            action.CategoryID = categoryID;
+        const iconClass = record.fields['IconClass'];
+        if (iconClass)
+            action.IconClass = iconClass;
+    }
+    /**
+     * Persists Action Params. On reuse, deletes the existing params first so the
+     * recreated set stays exactly in sync with the freshly generated metadata.
+     */
+    async persistParams(md, actionID, record, alreadyExisted, contextUser) {
+        if (alreadyExisted) {
+            await this.deleteRelated(md, 'MJ: Action Params', actionID, contextUser);
+        }
+        const params = record.relatedEntities['MJ: Action Params'] ?? [];
+        for (const p of params) {
+            const param = await md.GetEntityObject('MJ: Action Params', contextUser);
+            param.NewRecord();
+            param.ActionID = actionID;
+            param.Name = p.fields['Name'];
+            param.Type = p.fields['Type'] ?? 'Input';
+            param.ValueType = (p.fields['ValueType'] ?? 'Scalar');
+            param.IsArray = p.fields['IsArray'] ?? false;
+            param.IsRequired = p.fields['IsRequired'] ?? false;
+            if (p.fields['Description'])
+                param.Description = p.fields['Description'];
+            const saved = await param.Save();
+            if (!saved) {
+                LogError(`IntegrationActionGenerator: failed to save param '${param.Name}' for action ${actionID}: ${param.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+    }
+    /**
+     * Persists Action Result Codes. On reuse, deletes the existing ones first to
+     * keep them in sync with the generated metadata.
+     */
+    async persistResultCodes(md, actionID, record, alreadyExisted, contextUser) {
+        if (alreadyExisted) {
+            await this.deleteRelated(md, 'MJ: Action Result Codes', actionID, contextUser);
+        }
+        const codes = record.relatedEntities['MJ: Action Result Codes'] ?? [];
+        for (const c of codes) {
+            const code = await md.GetEntityObject('MJ: Action Result Codes', contextUser);
+            code.NewRecord();
+            code.ActionID = actionID;
+            code.ResultCode = c.fields['ResultCode'];
+            code.IsSuccess = c.fields['IsSuccess'] ?? false;
+            if (c.fields['Description'])
+                code.Description = c.fields['Description'];
+            const saved = await code.Save();
+            if (!saved) {
+                LogError(`IntegrationActionGenerator: failed to save result code '${code.ResultCode}' for action ${actionID}: ${code.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+    }
+    /** Loads and deletes all rows of a child entity linked to the given ActionID. */
+    async deleteRelated(md, entityName, actionID, contextUser) {
+        const rv = RunView.FromMetadataProvider(md);
+        const result = await rv.RunView({
+            EntityName: entityName,
+            ExtraFilter: `ActionID='${this.escape(actionID)}'`,
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!result.Success)
+            return;
+        for (const row of result.Results) {
+            const deleted = await row.Delete();
+            if (!deleted) {
+                LogError(`IntegrationActionGenerator: failed to delete ${entityName} row ${row.ID}: ${row.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+    }
+    // ─── Helpers ─────────────────────────────────────────────────────
+    escape(value) {
+        return value.replace(/'/g, "''");
+    }
+    failure(verb, objectName, message) {
+        return { Success: false, Verb: verb, ObjectName: objectName, AlreadyExisted: false, Message: message };
+    }
+}
+//# sourceMappingURL=IntegrationActionGenerator.js.map

package/dist/IntegrationActionGenerator.js.map

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

package/dist/IntegrationConnectorCreationPipeline.d.ts

@@ -0,0 +1,86 @@
+import type { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import type { MJCompanyIntegrationEntity } from '@memberjunction/core-entities';
+import { type IntegrationRunManifest } from '@memberjunction/integration-progress-artifacts';
+import { type LLMOneShotCallback } from '@memberjunction/integration-pk-classifier';
+import { BaseIntegrationConnector } from './BaseIntegrationConnector.js';
+import { type PersistSchemaResult } from './IntegrationSchemaSync.js';
+import type { IntrospectSchemaOptions } from './types.js';
+/** Options for the creation/refresh pipeline run. */
+export interface ConnectorCreationPipelineOptions {
+    /** The connector instance to drive (already constructed by caller). */
+    Connector: BaseIntegrationConnector;
+    /** CompanyIntegration row to authenticate with. */
+    CompanyIntegration: MJCompanyIntegrationEntity;
+    /** User context for all entity operations. */
+    ContextUser: UserInfo;
+    /** Optional metadata provider override (multi-provider scenarios). */
+    Provider?: IMetadataProvider;
+    /** Optional subset filter — limits introspection to a named set of objects. */
+    IntrospectOptions?: IntrospectSchemaOptions;
+    /** Optional vendor-wide PK convention hint (e.g. "id" for HubSpot). */
+    UniversalPKConvention?: string;
+    /** Optional one-shot LLM callback for the PK classifier's last-resort step. */
+    LLMInference?: LLMOneShotCallback;
+    /** Optional pre-fetched sample rows per object for statistical PK detection. */
+    SampleRowsByObject?: Record<string, Array<Record<string, unknown>>>;
+    /**
+     * Directory for structured progress artifacts. Defaults to
+     * `<cwd>/logs/integration-runs`. Each run gets its own `<runID>/` subdir
+     * containing manifest.json, progress.jsonl, result.json.
+     */
+    ArtifactRootDir?: string;
+    /** Mirror progress to console (default false). */
+    ConsoleMirror?: boolean;
+    /**
+     * Optional explicit runID. When omitted, generated as `connector-<ts>-<rand>`.
+     * Supply your own when resuming a previously-killed run.
+     */
+    RunID?: string;
+    /** Trigger reason recorded in the manifest. */
+    TriggerType?: 'Manual' | 'Scheduled' | 'Webhook' | 'Pipeline' | 'Restart';
+}
+/** Outcome of a single pipeline invocation. */
+export interface ConnectorCreationPipelineResult {
+    RunID: string;
+    Success: boolean;
+    PersistResult?: PersistSchemaResult;
+    PKVerdicts: Array<{
+        ObjectName: string;
+        Confident: boolean;
+        Nominee?: string;
+        Confidence: number;
+        Strategy: string;
+        Reason: string;
+    }>;
+    /** Objects that ended the run with no PK — these won't be entity-generated. */
+    UnresolvedObjects: string[];
+    /** Manifest used to identify the run on disk (for resumption tools). */
+    Manifest: IntegrationRunManifest;
+    /** Final fail reason if Success=false. */
+    FailureMessage?: string;
+}
+/**
+ * The unified pipeline that drives connector creation / refresh end-to-end:
+ *
+ *   1. ConnectionTest stage  — verifies credentials before any heavy work
+ *   2. Introspect stage      — parallel describe via the connector
+ *   3. Persist stage         — bounded-concurrency upsert with overlay precedence
+ *   4. PKClassify stage      — soft PK classifier on objects still missing a PK
+ *
+ * Every stage emits structured events through IntegrationProgressEmitter so the
+ * stream is identical regardless of vendor. Stages also emit checkpoint events
+ * carrying enough resumableState that the orchestrator can pick up from a kill
+ * or container restart without re-running prior stages.
+ *
+ * The pipeline does NOT generate MJ entities itself — that gate (D7) lives in
+ * the CodeGen metadata layer: rows without a PK are simply not promoted to
+ * `__mj.Entity`. The pipeline emits `entity.skipped-no-pk` events for visibility.
+ */
+export declare class IntegrationConnectorCreationPipeline {
+    Run(opts: ConnectorCreationPipelineOptions): Promise<ConnectorCreationPipelineResult>;
+    private StageConnectionTest;
+    private StageIntrospect;
+    private StagePersist;
+    private StagePKClassify;
+}
+//# sourceMappingURL=IntegrationConnectorCreationPipeline.d.ts.map

package/dist/IntegrationConnectorCreationPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntegrationConnectorCreationPipeline.d.ts","sourceRoot":"","sources":["../src/IntegrationConnectorCreationPipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EACR,0BAA0B,EAG7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEH,KAAK,sBAAsB,EAC9B,MAAM,gDAAgD,CAAC;AACxD,OAAO,EAEH,KAAK,kBAAkB,EAC1B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,qDAAqD;AACrD,MAAM,WAAW,gCAAgC;IAC7C,uEAAuE;IACvE,SAAS,EAAE,wBAAwB,CAAC;IACpC,mDAAmD;IACnD,kBAAkB,EAAE,0BAA0B,CAAC;IAC/C,8CAA8C;IAC9C,WAAW,EAAE,QAAQ,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,uEAAuE;IACvE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;CAC7E;AAED,+CAA+C;AAC/C,MAAM,WAAW,+BAA+B;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,UAAU,EAAE,KAAK,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,sBAAsB,CAAC;IACjC,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oCAAoC;IAChC,GAAG,CAAC,IAAI,EAAE,gCAAgC,GAAG,OAAO,CAAC,+BAA+B,CAAC;YA4DpF,mBAAmB;YAiBnB,eAAe;YAiCf,YAAY;YAuCZ,eAAe;CAoFhC"}