@memberjunction/integration-engine 6.1.0-edge.3 → 6.1.0-edge.5

package/dist/BatchIdentity.js

@@ -0,0 +1,78 @@
+/**
+ * Within-batch identity: no two records in one batch may share an ExternalID.
+ *
+ * ExternalID *is* the identity the record map keys on, so two records carrying the same one are two
+ * observations of a single source record, never two rows. The write path cannot discover this on its
+ * own: it decides insert-vs-update by asking whether the identity already exists in the DATABASE,
+ * and for a first-time record neither copy does — so both insert, and the pair re-inserts on every
+ * subsequent sync. Nothing downstream can repair it either, because both rows then map to the same
+ * ExternalID and no later run can tell which to keep.
+ *
+ * Observed in the field: an object whose duplicate groups were byte-identical on every captured
+ * column AND written inside the same second — meaning the source itself listed the same element
+ * twice within one batch, rather than a re-read delivering it again. The whole-batch fingerprint
+ * guard nearby catches a batch REPEATED in full (the infinite-loop case); it cannot see duplicates
+ * inside a single batch.
+ *
+ * Last-wins matches upsert semantics: when two entries share an identity but differ, the later
+ * entry is the more recent observation of that record's state, which is exactly what a single
+ * upsert would have left behind had they arrived in separate batches.
+ */
+/** How many repeated identities to name in the warning. */
+const SAMPLE_LIMIT = 5;
+/**
+ * Collapses records sharing an ExternalID within one batch, keeping the LAST occurrence in its
+ * original position. Returns the input array unchanged (same reference) when every identity is
+ * already unique, so the ordinary path allocates nothing.
+ *
+ * A record with an empty or missing ExternalID is passed through untouched: identity-less records
+ * are a separate defect with a separate guard, and silently collapsing them here would merge
+ * unrelated rows.
+ */
+export function CollapseDuplicateIdentities(records) {
+    if (records.length < 2) {
+        return { Records: records, Collapsed: 0, SampleIDs: [] };
+    }
+    // First pass: find which identities repeat, without allocating a copy of the batch.
+    const counts = new Map();
+    let duplicates = 0;
+    for (const r of records) {
+        const id = r?.ExternalID;
+        if (!id)
+            continue;
+        const seen = counts.get(id);
+        if (seen === undefined) {
+            counts.set(id, 1);
+        }
+        else {
+            counts.set(id, seen + 1);
+            duplicates++;
+        }
+    }
+    if (duplicates === 0) {
+        return { Records: records, Collapsed: 0, SampleIDs: [] };
+    }
+    const sample = [];
+    for (const [id, n] of counts) {
+        if (n > 1 && sample.length < SAMPLE_LIMIT)
+            sample.push(id);
+        if (sample.length >= SAMPLE_LIMIT)
+            break;
+    }
+    // Second pass: keep the LAST occurrence of each repeated identity, in its original slot.
+    const lastIndexByID = new Map();
+    for (let i = 0; i < records.length; i++) {
+        const id = records[i]?.ExternalID;
+        if (id)
+            lastIndexByID.set(id, i);
+    }
+    const out = [];
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        const id = r?.ExternalID;
+        if (!id || lastIndexByID.get(id) === i)
+            out.push(r);
+    }
+    return { Records: out, Collapsed: records.length - out.length, SampleIDs: sample };
+}
+//# sourceMappingURL=BatchIdentity.js.map

package/dist/BatchIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchIdentity.js","sourceRoot":"","sources":["../src/BatchIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAoBH,2DAA2D;AAC3D,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B,CAA0B,OAAyB;IAC1F,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,OAAc,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IACpE,CAAC;IAED,oFAAoF;IACpF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,CAAC,EAAE,UAAU,CAAC;QACzB,IAAI,CAAC,EAAE;YAAE,SAAS;QAClB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACJ,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;YACzB,UAAU,EAAE,CAAC;QACjB,CAAC;IACL,CAAC;IACD,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,OAAc,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IACpE,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,YAAY;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3D,IAAI,MAAM,CAAC,MAAM,IAAI,YAAY;YAAE,MAAM;IAC7C,CAAC;IAED,yFAAyF;IACzF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;QAClC,IAAI,EAAE;YAAE,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,MAAM,EAAE,GAAG,CAAC,EAAE,UAAU,CAAC;QACzB,IAAI,CAAC,EAAE,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACvF,CAAC"}

package/dist/DeclaredSampleMerge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Merging what a connector DECLARED about an object with what STREAMING THE SOURCE observed.
+ *
+ * ## Why sampling has to be unconditional
+ *
+ * Discovery used to stream records only when an object arrived with no fields — later widened to
+ * "no fields, or no key". Both are gates on the wrong question, because sampling answers three
+ * questions and a declaration can only pre-answer one of them:
+ *
+ * | question | can a declaration answer it? |
+ * |---|---|
+ * | what is the primary key? | **yes** — a declared key is authoritative |
+ * | which fields does the source actually send? | no — a catalog lists what the vendor documents |
+ * | how wide are the values? | no — only the data knows |
+ *
+ * So an object declared with fields AND a key was never sampled, and its undeclared columns arrived
+ * later through the overflow path one sync at a time, while its widths were whatever the catalog
+ * guessed. A column declared 100 wide against data that is 900 wide is not a slow discovery — it is
+ * a truncation or a migration written by hand afterwards.
+ *
+ * ## The merge is per-attribute, and it is one-directional
+ *
+ * Sampling never overrides a deliberate declaration; it only fills gaps and widens:
+ *
+ * - **Primary key** — declared wins outright. An observed key is adopted only when none was declared.
+ * - **New fields** — an observed field absent from the declaration is ADDED, so the column exists at
+ *   RSU time instead of appearing in overflow after a sync.
+ * - **Widths** — effective length is `max(declared, observed)`, and an unbounded declaration always
+ *   wins over any measured number. Never shrink: shrinking is the one outcome that loses data.
+ * - **Everything else** — labels, descriptions, types, nullability, FK targets — the declaration
+ *   stands. A sampled type is inferred from a handful of values; a declared one was written down.
+ *
+ * The asymmetry is deliberate. A declaration that is WRONG about a width is corrected by the data;
+ * a declaration that is RIGHT about a description is not second-guessed by a sample.
+ */
+/**
+ * The only three attributes the merge reasons about. Declared fields and sampled fields are
+ * different shapes elsewhere in the pipeline (`SourceType` vs `DataType`), and neither shape is
+ * this module's business — the caller normalizes to one and gets the same one back.
+ */
+export interface MergeableField {
+    Name: string;
+    MaxLength?: number | null;
+    IsPrimaryKey?: boolean;
+}
+/** A field's length where `null` means unbounded — the widest thing there is, never narrowed. */
+export type FieldLength = number | null | undefined;
+/**
+ * Effective length for a field the source both declared and was observed producing.
+ *
+ * `null` (unbounded) beats every number, on either side: a declaration of "unbounded" is a
+ * deliberate statement that no width is safe, and an observation that exceeded the bounded ceiling
+ * is the data saying the same thing. Otherwise the larger wins, and a missing side yields to the
+ * present one.
+ */
+export declare function MergeLength(declared: FieldLength, observed: FieldLength): FieldLength;
+/** The outcome of merging one object's declared fields with a sample, for logging and tests. */
+export interface MergeOutcome<TField extends MergeableField> {
+    Fields: TField[];
+    /** Fields the sample found that the declaration never mentioned. */
+    AddedFieldNames: string[];
+    /** Fields whose declared length was too narrow for the observed data. */
+    WidenedFieldNames: string[];
+    /** Key columns adopted from the sample because none was declared. */
+    AdoptedKeyNames: string[];
+}
+/**
+ * Merges an observed field set into a declared one under the rules above.
+ *
+ * `declared` is returned unchanged in shape and order, with new fields appended — order carries
+ * meaning to a reader comparing a catalog against a table, so observed fields do not interleave.
+ */
+export declare function MergeDeclaredWithSample<TField extends MergeableField>(declared: ReadonlyArray<TField>, observed: ReadonlyArray<TField>): MergeOutcome<TField>;
+//# sourceMappingURL=DeclaredSampleMerge.d.ts.map

package/dist/DeclaredSampleMerge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclaredSampleMerge.d.ts","sourceRoot":"","sources":["../src/DeclaredSampleMerge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW,CAKrF;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,cAAc;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,qEAAqE;IACrE,eAAe,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,cAAc,EACjE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAC/B,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAChC,YAAY,CAAC,MAAM,CAAC,CA6CtB"}

package/dist/DeclaredSampleMerge.js

@@ -0,0 +1,104 @@
+/**
+ * Merging what a connector DECLARED about an object with what STREAMING THE SOURCE observed.
+ *
+ * ## Why sampling has to be unconditional
+ *
+ * Discovery used to stream records only when an object arrived with no fields — later widened to
+ * "no fields, or no key". Both are gates on the wrong question, because sampling answers three
+ * questions and a declaration can only pre-answer one of them:
+ *
+ * | question | can a declaration answer it? |
+ * |---|---|
+ * | what is the primary key? | **yes** — a declared key is authoritative |
+ * | which fields does the source actually send? | no — a catalog lists what the vendor documents |
+ * | how wide are the values? | no — only the data knows |
+ *
+ * So an object declared with fields AND a key was never sampled, and its undeclared columns arrived
+ * later through the overflow path one sync at a time, while its widths were whatever the catalog
+ * guessed. A column declared 100 wide against data that is 900 wide is not a slow discovery — it is
+ * a truncation or a migration written by hand afterwards.
+ *
+ * ## The merge is per-attribute, and it is one-directional
+ *
+ * Sampling never overrides a deliberate declaration; it only fills gaps and widens:
+ *
+ * - **Primary key** — declared wins outright. An observed key is adopted only when none was declared.
+ * - **New fields** — an observed field absent from the declaration is ADDED, so the column exists at
+ *   RSU time instead of appearing in overflow after a sync.
+ * - **Widths** — effective length is `max(declared, observed)`, and an unbounded declaration always
+ *   wins over any measured number. Never shrink: shrinking is the one outcome that loses data.
+ * - **Everything else** — labels, descriptions, types, nullability, FK targets — the declaration
+ *   stands. A sampled type is inferred from a handful of values; a declared one was written down.
+ *
+ * The asymmetry is deliberate. A declaration that is WRONG about a width is corrected by the data;
+ * a declaration that is RIGHT about a description is not second-guessed by a sample.
+ */
+/**
+ * Effective length for a field the source both declared and was observed producing.
+ *
+ * `null` (unbounded) beats every number, on either side: a declaration of "unbounded" is a
+ * deliberate statement that no width is safe, and an observation that exceeded the bounded ceiling
+ * is the data saying the same thing. Otherwise the larger wins, and a missing side yields to the
+ * present one.
+ */
+export function MergeLength(declared, observed) {
+    if (declared === null || observed === null)
+        return null;
+    if (declared === undefined)
+        return observed;
+    if (observed === undefined)
+        return declared;
+    return Math.max(declared, observed);
+}
+/**
+ * Merges an observed field set into a declared one under the rules above.
+ *
+ * `declared` is returned unchanged in shape and order, with new fields appended — order carries
+ * meaning to a reader comparing a catalog against a table, so observed fields do not interleave.
+ */
+export function MergeDeclaredWithSample(declared, observed) {
+    const observedByLower = new Map(observed.map(f => [f.Name.toLowerCase(), f]));
+    const declaredNames = new Set(declared.map(f => f.Name.toLowerCase()));
+    const declaredHasKey = declared.some(f => f.IsPrimaryKey === true);
+    const widened = [];
+    const adoptedKeys = [];
+    const merged = declared.map(field => {
+        const seen = observedByLower.get(field.Name.toLowerCase());
+        if (!seen)
+            return field;
+        const length = MergeLength(field.MaxLength, seen.MaxLength);
+        const widenedHere = length !== field.MaxLength;
+        if (widenedHere)
+            widened.push(field.Name);
+        // The key is adopted only into a declaration that named none. A declared key is
+        // authoritative even when the sample would have nominated a different column.
+        const adoptKey = !declaredHasKey && seen.IsPrimaryKey === true;
+        if (adoptKey)
+            adoptedKeys.push(field.Name);
+        if (!widenedHere && !adoptKey)
+            return field;
+        return {
+            ...field,
+            MaxLength: length ?? null,
+            IsPrimaryKey: adoptKey ? true : field.IsPrimaryKey,
+        };
+    });
+    // Fields the vendor sends but never documented. Appended as-is: the sample is the only thing
+    // that knows anything about them, so there is nothing to defer to.
+    const added = [];
+    for (const seen of observed) {
+        if (declaredNames.has(seen.Name.toLowerCase()))
+            continue;
+        added.push(seen.Name);
+        merged.push({
+            ...seen,
+            // A key nominated on a field the declaration never mentioned is still only adopted
+            // when nothing was declared — same rule, applied to the appended half.
+            IsPrimaryKey: declaredHasKey ? false : seen.IsPrimaryKey,
+        });
+        if (!declaredHasKey && seen.IsPrimaryKey === true)
+            adoptedKeys.push(seen.Name);
+    }
+    return { Fields: merged, AddedFieldNames: added, WidenedFieldNames: widened, AdoptedKeyNames: adoptedKeys };
+}
+//# sourceMappingURL=DeclaredSampleMerge.js.map

package/dist/DeclaredSampleMerge.js.map

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

package/dist/DiscoveryWatchdog.d.ts

@@ -0,0 +1,103 @@
+/**
+ * A registry of in-flight discovery samples, reported periodically while any are running.
+ *
+ * From outside the process, a discovery that is working and one that is hung look identical:
+ * nothing is written between the run's start and its end, so a long-but-healthy sample of a slow
+ * source and a walk that will never terminate produce the same evidence — none. That is the whole
+ * difficulty of diagnosing discovery: the failure mode is silence, and silence is also what
+ * success looks like until it finishes.
+ *
+ * The watchdog turns silence into a statement. Every sample registers itself, notes what stage it
+ * is in as it goes, and deregisters when it ends; while anything is registered, a ticker names
+ * each object still in flight, how long it has been there, what it is waiting on, and how much it
+ * has actually pulled. Silence then means the process is gone — anything still running says so
+ * under its own name.
+ *
+ * Nothing here changes what discovery does; it only makes it visible. The ticker is unref'd, so it
+ * can never be the reason Node stays alive, and it exists only while samples are in flight.
+ */
+import { BaseSingleton, IShutdownable } from '@memberjunction/global';
+/** What one in-flight sample is doing right now. */
+export type DiscoveryWatchEntry = {
+    /** The external object being sampled. */
+    Object: string;
+    /** Epoch ms the sample started. */
+    StartedMs: number;
+    /** Free-text phase, e.g. `FetchChanges#3`. */
+    Stage: string;
+    /** Pages pulled from the source so far. */
+    Pages: number;
+    /** Records yielded to the inference so far. */
+    Records: number;
+    /** Epoch ms the sample must not outlive, when it has a deadline. */
+    DeadlineMs?: number;
+};
+/** Mutable fields a caller may update mid-flight. */
+export type DiscoveryWatchPatch = Partial<Pick<DiscoveryWatchEntry, 'Stage' | 'Pages' | 'Records'>>;
+export type DiscoveryWatchdogOptions = {
+    /** Report interval. `<= 0` disables reporting entirely (tracking still works). */
+    IntervalMs?: number;
+    /** Clock, injectable for tests. */
+    Now?: () => number;
+    /** Sink for the report line. */
+    Log?: (message: string) => void;
+    /** Timer factory, injectable for tests. Must return something `Clear` accepts. */
+    SetInterval?: (fn: () => void, ms: number) => unknown;
+    Clear?: (handle: unknown) => void;
+};
+/**
+ * Resolves the report interval: `MJ_INTEGRATION_DISCOVERY_WATCHDOG_MS`, default 15s, `0` to
+ * silence it. A malformed value falls back to the default rather than disabling the reporting an
+ * operator was trying to configure.
+ */
+export declare function ResolveWatchdogIntervalMs(env: string | undefined, defaultMs?: number): number;
+export declare class DiscoveryWatchdog extends BaseSingleton<DiscoveryWatchdog> implements IShutdownable {
+    /**
+     * Process-wide instance, resolved through the Global Object Store rather than a static field.
+     *
+     * That distinction matters here specifically: this package is one of the ones that can be
+     * loaded twice in a process (a bundled connector copy alongside the standalone one). A static
+     * field would then give each copy its OWN registry and its OWN ticker, so samples registered
+     * through one would be absent from the other's report — a watchdog that silently under-reports
+     * what is in flight, which is worse than no watchdog, because the whole contract is that
+     * silence means the process is gone.
+     */
+    static get Instance(): DiscoveryWatchdog;
+    readonly ShutdownName = "DiscoveryWatchdog";
+    private readonly inFlight;
+    private intervalMs;
+    private now;
+    private log;
+    private setIntervalFn;
+    private clearFn;
+    private ticker;
+    private keySeq;
+    protected constructor();
+    /**
+     * Overrides the defaults — the interval, and the clock/timer/log seams the tests drive.
+     * Mirrors {@link AgentRunWatchdog.Configure}: a singleton cannot take constructor arguments,
+     * because `BaseSingleton` returns the stored instance and would discard them.
+     *
+     * Restarts the ticker when one is already running, so a changed interval takes effect at once.
+     */
+    Configure(options?: DiscoveryWatchdogOptions): void;
+    /** Drops all in-flight state and stops the ticker. For tests, and for a clean shutdown. */
+    Reset(): void;
+    /** IShutdownable: a diagnostic ticker must not keep firing while the process drains. */
+    Shutdown(): Promise<void>;
+    /** Registers a sample and returns the key used to update and end it. */
+    Start(objectName: string, deadlineMs?: number): string;
+    /** Updates an in-flight sample. A key that has already ended is ignored. */
+    Note(key: string | undefined, patch: DiscoveryWatchPatch): void;
+    /** Deregisters a sample. Stops the ticker once nothing is left in flight. */
+    End(key: string | undefined): void;
+    /** Read-only view of what is in flight, for callers that want the numbers at the end. */
+    Peek(key: string | undefined): Readonly<DiscoveryWatchEntry> | undefined;
+    /** The report line, or `null` when nothing is in flight. Pure — this is what the ticker logs. */
+    BuildReport(): string | null;
+    /** Emits one report immediately. Exposed so the ticker and tests drive the same path. */
+    Tick(): void;
+    private ensureTicker;
+    private stopTicker;
+}
+//# sourceMappingURL=DiscoveryWatchdog.d.ts.map

package/dist/DiscoveryWatchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiscoveryWatchdog.d.ts","sourceRoot":"","sources":["../src/DiscoveryWatchdog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAoB,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAExF,oDAAoD;AACpD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC;AAEpG,MAAM,MAAM,wBAAwB,GAAG;IACnC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gCAAgC;IAChC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,kFAAkF;IAClF,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACtD,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,SAAS,GAAG,MAAM,CAK7F;AAED,qBAAa,iBAAkB,SAAQ,aAAa,CAAC,iBAAiB,CAAE,YAAW,aAAa;IAC5F;;;;;;;;;OASG;IACH,WAAkB,QAAQ,IAAI,iBAAiB,CAE9C;IAED,SAAgB,YAAY,uBAAuB;IAEnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,aAAa,CAA0C;IAC/D,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAK;IAEnB,SAAS;IAeT;;;;;;OAMG;IACI,SAAS,CAAC,OAAO,GAAE,wBAA6B,GAAG,IAAI;IAY9D,2FAA2F;IACpF,KAAK,IAAI,IAAI;IAMpB,wFAAwF;IAC3E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,wEAAwE;IACjE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAc7D,4EAA4E;IACrE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI;IAMtE,6EAA6E;IACtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAMzC,yFAAyF;IAClF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC,mBAAmB,CAAC,GAAG,SAAS;IAI/E,iGAAiG;IAC1F,WAAW,IAAI,MAAM,GAAG,IAAI;IAWnC,yFAAyF;IAClF,IAAI,IAAI,IAAI;IASnB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,UAAU;CAKrB"}

package/dist/DiscoveryWatchdog.js

@@ -0,0 +1,166 @@
+/**
+ * A registry of in-flight discovery samples, reported periodically while any are running.
+ *
+ * From outside the process, a discovery that is working and one that is hung look identical:
+ * nothing is written between the run's start and its end, so a long-but-healthy sample of a slow
+ * source and a walk that will never terminate produce the same evidence — none. That is the whole
+ * difficulty of diagnosing discovery: the failure mode is silence, and silence is also what
+ * success looks like until it finishes.
+ *
+ * The watchdog turns silence into a statement. Every sample registers itself, notes what stage it
+ * is in as it goes, and deregisters when it ends; while anything is registered, a ticker names
+ * each object still in flight, how long it has been there, what it is waiting on, and how much it
+ * has actually pulled. Silence then means the process is gone — anything still running says so
+ * under its own name.
+ *
+ * Nothing here changes what discovery does; it only makes it visible. The ticker is unref'd, so it
+ * can never be the reason Node stays alive, and it exists only while samples are in flight.
+ */
+import { BaseSingleton, ShutdownRegistry } from '@memberjunction/global';
+/**
+ * Resolves the report interval: `MJ_INTEGRATION_DISCOVERY_WATCHDOG_MS`, default 15s, `0` to
+ * silence it. A malformed value falls back to the default rather than disabling the reporting an
+ * operator was trying to configure.
+ */
+export function ResolveWatchdogIntervalMs(env, defaultMs = 15_000) {
+    if (env === undefined || env.trim() === '')
+        return defaultMs;
+    const parsed = Number.parseInt(env, 10);
+    if (!Number.isFinite(parsed))
+        return defaultMs;
+    return parsed <= 0 ? 0 : parsed;
+}
+export class DiscoveryWatchdog extends BaseSingleton {
+    /**
+     * Process-wide instance, resolved through the Global Object Store rather than a static field.
+     *
+     * That distinction matters here specifically: this package is one of the ones that can be
+     * loaded twice in a process (a bundled connector copy alongside the standalone one). A static
+     * field would then give each copy its OWN registry and its OWN ticker, so samples registered
+     * through one would be absent from the other's report — a watchdog that silently under-reports
+     * what is in flight, which is worse than no watchdog, because the whole contract is that
+     * silence means the process is gone.
+     */
+    static get Instance() {
+        return super.getInstance();
+    }
+    constructor() {
+        super();
+        this.ShutdownName = 'DiscoveryWatchdog';
+        this.inFlight = new Map();
+        this.ticker = null;
+        this.keySeq = 0;
+        this.intervalMs = ResolveWatchdogIntervalMs(process.env.MJ_INTEGRATION_DISCOVERY_WATCHDOG_MS);
+        this.now = () => Date.now();
+        this.log = message => console.log(message);
+        this.setIntervalFn = (fn, ms) => {
+            const handle = setInterval(fn, ms);
+            // Never hold the process open for a diagnostic.
+            if (typeof handle.unref === 'function')
+                handle.unref();
+            return handle;
+        };
+        this.clearFn = handle => clearInterval(handle);
+        ShutdownRegistry.Instance.Register(this);
+    }
+    /**
+     * Overrides the defaults — the interval, and the clock/timer/log seams the tests drive.
+     * Mirrors {@link AgentRunWatchdog.Configure}: a singleton cannot take constructor arguments,
+     * because `BaseSingleton` returns the stored instance and would discard them.
+     *
+     * Restarts the ticker when one is already running, so a changed interval takes effect at once.
+     */
+    Configure(options = {}) {
+        if (options.IntervalMs !== undefined)
+            this.intervalMs = options.IntervalMs;
+        if (options.Now)
+            this.now = options.Now;
+        if (options.Log)
+            this.log = options.Log;
+        if (options.SetInterval)
+            this.setIntervalFn = options.SetInterval;
+        if (options.Clear)
+            this.clearFn = options.Clear;
+        if (this.ticker !== null) {
+            this.stopTicker();
+            this.ensureTicker();
+        }
+    }
+    /** Drops all in-flight state and stops the ticker. For tests, and for a clean shutdown. */
+    Reset() {
+        this.inFlight.clear();
+        this.stopTicker();
+        this.keySeq = 0;
+    }
+    /** IShutdownable: a diagnostic ticker must not keep firing while the process drains. */
+    async Shutdown() {
+        this.stopTicker();
+    }
+    /** Registers a sample and returns the key used to update and end it. */
+    Start(objectName, deadlineMs) {
+        const key = `${objectName}#${++this.keySeq}`;
+        this.inFlight.set(key, {
+            Object: objectName,
+            StartedMs: this.now(),
+            Stage: 'starting',
+            Pages: 0,
+            Records: 0,
+            DeadlineMs: deadlineMs,
+        });
+        this.ensureTicker();
+        return key;
+    }
+    /** Updates an in-flight sample. A key that has already ended is ignored. */
+    Note(key, patch) {
+        if (!key)
+            return;
+        const entry = this.inFlight.get(key);
+        if (entry)
+            Object.assign(entry, patch);
+    }
+    /** Deregisters a sample. Stops the ticker once nothing is left in flight. */
+    End(key) {
+        if (!key)
+            return;
+        this.inFlight.delete(key);
+        if (this.inFlight.size === 0)
+            this.stopTicker();
+    }
+    /** Read-only view of what is in flight, for callers that want the numbers at the end. */
+    Peek(key) {
+        return key ? this.inFlight.get(key) : undefined;
+    }
+    /** The report line, or `null` when nothing is in flight. Pure — this is what the ticker logs. */
+    BuildReport() {
+        if (this.inFlight.size === 0)
+            return null;
+        const now = this.now();
+        const entries = [...this.inFlight.values()].sort((a, b) => a.StartedMs - b.StartedMs);
+        const oldestSec = Math.round((now - entries[0].StartedMs) / 1000);
+        const rows = entries.map(e => `"${e.Object}" ${Math.round((now - e.StartedMs) / 1000)}s stage=${e.Stage} pages=${e.Pages} records=${e.Records}` +
+            (e.DeadlineMs !== undefined ? ` deadlineIn=${Math.round((e.DeadlineMs - now) / 1000)}s` : ''));
+        return `[DiscoveryWatchdog] ${entries.length} object(s) still in flight, oldest ${oldestSec}s:\n    ${rows.join('\n    ')}`;
+    }
+    /** Emits one report immediately. Exposed so the ticker and tests drive the same path. */
+    Tick() {
+        if (this.inFlight.size === 0) {
+            this.stopTicker();
+            return;
+        }
+        const report = this.BuildReport();
+        if (report)
+            this.log(report);
+    }
+    ensureTicker() {
+        if (this.intervalMs <= 0 || this.ticker !== null)
+            return;
+        this.ticker = this.setIntervalFn(() => this.Tick(), this.intervalMs);
+    }
+    stopTicker() {
+        if (this.ticker === null)
+            return;
+        this.clearFn(this.ticker);
+        this.ticker = null;
+    }
+}
+//# sourceMappingURL=DiscoveryWatchdog.js.map

package/dist/DiscoveryWatchdog.js.map

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

package/dist/FieldMapValidation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Start-of-run validation for the MJ side of a field map.
+ *
+ * A field map's `DestinationFieldName` is the MJ column, in BOTH directions — pull writes it,
+ * push reads it back out to build the external payload. Nothing checks that the column exists.
+ * `BaseEntity.Set` looks the field up and, when it finds nothing, returns without doing anything
+ * and without saying anything: the value is dropped for every record, the entity is never dirtied
+ * by it, the save succeeds, and the run reports the rows as written. The observable result is a
+ * column's worth of data that never arrives, on a sync that reports success — and if that field is
+ * a key field, every record is re-created on the next run because it can never be matched again.
+ *
+ * This is the cheap check that turns that into one warning per map per run: the map is metadata,
+ * so it is verifiable the moment the run knows its entity, long before the first record is fetched.
+ * The decision is kept pure so it is tested without a provider or an entity.
+ */
+/** The parts of a field map this validation reads. */
+export type ValidatableFieldMap = {
+    SourceFieldName: string;
+    DestinationFieldName: string;
+    Status?: string | null;
+    IsKeyField?: boolean | null;
+};
+/** One map that cannot bind, with the detail an operator needs to fix it. */
+export type UnbindableFieldMap = {
+    SourceFieldName: string;
+    DestinationFieldName: string;
+    IsKeyField: boolean;
+};
+/**
+ * Returns the ACTIVE field maps whose destination column does not exist on the target entity.
+ *
+ * Matching is case-insensitive, because `BaseEntity` resolves field names case-insensitively — a
+ * map that differs only in casing binds fine and is not a finding. An empty `entityFieldNames`
+ * means the caller could not resolve the entity at all; that is a different (already reported)
+ * condition, so nothing is returned rather than flagging every map.
+ */
+export declare function FindUnbindableFieldMaps(fieldMaps: readonly ValidatableFieldMap[], entityFieldNames: readonly string[]): UnbindableFieldMap[];
+/** The operator-facing sentence for a set of unbindable maps on one entity map. */
+export declare function DescribeUnbindableFieldMaps(unbindable: readonly UnbindableFieldMap[], externalObjectName: string, entityName: string): string;
+//# sourceMappingURL=FieldMapValidation.d.ts.map

package/dist/FieldMapValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldMapValidation.d.ts","sourceRoot":"","sources":["../src/FieldMapValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACnC,SAAS,EAAE,SAAS,mBAAmB,EAAE,EACzC,gBAAgB,EAAE,SAAS,MAAM,EAAE,GACpC,kBAAkB,EAAE,CAgBtB;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACvC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,GACnB,MAAM,CAaR"}