@mj-biz-apps/common-activity-sync 0.0.0 → 5.37.0

package/dist/BaseActivitySyncExtension.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview The in-process enrichment contract — how a downstream app adds to an Activity
+ * without Common knowing it exists.
+ *
+ * ── WHY IN-STREAM AND NOT AN ENTITY ACTION ─────────────────────────────────────────────────────
+ *
+ * MJ's `Entity Actions` bind declaratively to `AfterCreate` and are the right tool for most
+ * after-the-fact work. They are the wrong tool here for one reason: they fire AFTER the commit, in
+ * a separate transaction. An activity's links are what make it reachable — every read starts from a
+ * link — so an activity that commits without its deal link is briefly, and observably, unattributed.
+ * Running extensions inside the write transaction keeps "the activity and everything that explains
+ * it" a single atomic fact.
+ *
+ * ── EXTENSIONS ENRICH; THEY NEVER VETO ─────────────────────────────────────────────────────────
+ *
+ * Qualification is the engine's job and has already run by the time an extension sees anything. If
+ * an extension could reject an activity, whether a message got captured would depend on which apps
+ * happened to be installed on the host — precisely the coupling this design exists to prevent. An
+ * extension that wants an activity gone should record why, not suppress it.
+ *
+ * Registered by `DriverClass`, enabled and ordered by an `ActivitySyncExtension` row the consumer
+ * app ships in its OWN metadata:
+ *
+ * ```ts
+ * @RegisterClass(BaseActivitySyncExtension, 'Sales.DealLinker')
+ * export class DealLinkerExtension extends BaseActivitySyncExtension { ... }
+ * ```
+ *
+ * @module @mj-biz-apps/common-activity-sync
+ */
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import type { mjBizAppsCommonActivityEntity, mjBizAppsCommonActivityLinkEntity } from '@mj-biz-apps/common-entities';
+import type { ActivityIdentityKind, ActivityLinkRole, NormalizedItem } from './types.js';
+/** A party the engine matched to a Common record. */
+export interface ResolvedParty {
+    Kind: 'Person' | 'Organization';
+    RecordID: string;
+    Role: ActivityLinkRole;
+}
+/** A party the engine could not match, recorded so a later sweep can resolve it. */
+export interface UnresolvedParty {
+    Kind: ActivityIdentityKind;
+    Value: string;
+    Role: ActivityLinkRole;
+}
+/**
+ * What an extension is handed.
+ *
+ * The activity is already saved and the transaction is still open, so an extension adds rows that
+ * commit or roll back with it.
+ */
+export interface ActivityWriteContext {
+    /** The saved activity. Mutating and re-saving it is allowed; deleting it is not. */
+    Activity: mjBizAppsCommonActivityEntity;
+    /** Links written by the engine so far, in write order. */
+    Links: mjBizAppsCommonActivityLinkEntity[];
+    /** The source item, for anything the entity does not carry. */
+    Item: NormalizedItem;
+    ResolvedParties: ResolvedParty[];
+    UnresolvedParties: UnresolvedParty[];
+    ConnectionID: string;
+    ProviderTypeCode: string;
+    ContextUser: UserInfo;
+    /**
+     * The provider the engine is writing through.
+     *
+     * Carried rather than left to the extension to obtain, because an extension MUST write through
+     * the same provider as the engine or its rows land outside the write transaction — which is the
+     * one guarantee an in-stream extension exists to give. It is also how an extension resolves an
+     * `EntityID` for a link (`Provider.Entities`).
+     */
+    Provider: IMetadataProvider;
+    /**
+     * Cooperative cancellation for the registration's TimeoutMS.
+     *
+     * WithTimeout races; it does not kill the work. A timed-out Enrich keeps running inside
+     * the open write transaction unless it watches this signal. Abort the remaining work
+     * when `Signal.aborted` is set — otherwise a Skip loop can still be mid-Save when
+     * Commit or Rollback runs.
+     */
+    Signal?: AbortSignal;
+}
+export declare abstract class BaseActivitySyncExtension {
+    /**
+     * Add whatever this app knows to the activity, inside its transaction.
+     *
+     * Throwing is a legitimate way to report failure. What happens next is the REGISTRATION's
+     * choice, not this class's: `FailurePolicy = 'Skip'` (the default) records the error and lets
+     * the activity commit without the enrichment; `'Abort'` rolls the whole write back. Skip is the
+     * default because the activity is worth more than the enrichment, and one buggy consumer app
+     * must not be able to halt ingestion for every other app on the host.
+     *
+     * Keep it inside the registration's `TimeoutMS`: this runs with the write transaction open.
+     * Timeout is cooperative — watch `context.Signal` and return or throw when it aborts.
+     * `WithTimeout` rejects the waiter; it does not cancel the promise.
+     */
+    abstract Enrich(context: ActivityWriteContext): Promise<void>;
+}
+//# sourceMappingURL=BaseActivitySyncExtension.d.ts.map

package/dist/BaseActivitySyncExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseActivitySyncExtension.d.ts","sourceRoot":"","sources":["../src/BaseActivitySyncExtension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EACR,6BAA6B,EAC7B,iCAAiC,EACpC,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzF,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,QAAQ,GAAG,cAAc,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC;CAC1B;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACjC,oFAAoF;IACpF,QAAQ,EAAE,6BAA6B,CAAC;IACxC,0DAA0D;IAC1D,KAAK,EAAE,iCAAiC,EAAE,CAAC;IAC3C,+DAA+D;IAC/D,IAAI,EAAE,cAAc,CAAC;IACrB,eAAe,EAAE,aAAa,EAAE,CAAC;IACjC,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,QAAQ,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,8BAAsB,yBAAyB;IAC3C;;;;;;;;;;;;OAYG;aACa,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CACvE"}

package/dist/BaseActivitySyncExtension.js

@@ -0,0 +1,3 @@
+export class BaseActivitySyncExtension {
+}
+//# sourceMappingURL=BaseActivitySyncExtension.js.map

package/dist/BaseActivitySyncExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseActivitySyncExtension.js","sourceRoot":"","sources":["../src/BaseActivitySyncExtension.ts"],"names":[],"mappings":"AA0FA,MAAM,OAAgB,yBAAyB;CAe9C"}

package/dist/BaseActivitySyncProvider.d.ts

@@ -0,0 +1,40 @@
+import type { ActivitySourceBatch, ActivitySourceKind, ActivitySourceQuery, NormalizedItem, RawBatch } from './types.js';
+export declare abstract class BaseActivitySyncProvider {
+    /** Which surface this reads. Selects the watermark basis — see `WatermarkBasisForKind`. */
+    abstract readonly Kind: ActivitySourceKind;
+    /** Must match an `ActivitySyncProviderType.Code`. */
+    abstract readonly ProviderTypeCode: string;
+    /**
+     * False for fixtures.
+     *
+     * Not decoration: the engine refuses to write `Source: 'Integration'` rows from a non-live
+     * provider without being told to, so a fixture run cannot be mistaken for a real one in the
+     * database.
+     */
+    abstract readonly IsLive: boolean;
+    /** Ask the transport for whatever it has. Raw payloads — no interpretation. */
+    protected abstract FetchRaw(query: ActivitySourceQuery): Promise<RawBatch>;
+    /** Map raw payloads into the engine's vocabulary. The one place a transport's shape is known. */
+    protected abstract Normalize(raw: RawBatch, query: ActivitySourceQuery): NormalizedItem[];
+    /**
+     * One sync pass. Template method — subclasses extend it through the hooks below, never by
+     * overriding this.
+     */
+    Fetch(query: ActivitySourceQuery): Promise<ActivitySourceBatch>;
+    /**
+     * The newest point this pass can honestly claim.
+     *
+     * Overridable for a transport that exposes a better signal than either item time or observation
+     * time (a provider `ModifiedAt`, a server-side cursor). Overriding it means taking on the rules
+     * in `watermark.ts` — read them first.
+     */
+    protected ComputeHighWatermark(items: readonly NormalizedItem[], observedAt: Date): Date | null;
+    /** Seam for tests. Everything stored is UTC; a JS Date is a UTC instant. */
+    protected Now(): Date;
+    protected OnBeforeFetch(_query: ActivitySourceQuery): Promise<void>;
+    protected OnAfterFetch(_raw: RawBatch, _query: ActivitySourceQuery): Promise<void>;
+    protected OnBeforeNormalize(_raw: RawBatch, _query: ActivitySourceQuery): Promise<void>;
+    protected OnAfterNormalize(_items: NormalizedItem[], _query: ActivitySourceQuery): Promise<void>;
+    protected OnError(_error: unknown, _query: ActivitySourceQuery): Promise<void>;
+}
+//# sourceMappingURL=BaseActivitySyncProvider.d.ts.map

package/dist/BaseActivitySyncProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseActivitySyncProvider.d.ts","sourceRoot":"","sources":["../src/BaseActivitySyncProvider.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EACR,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,QAAQ,EACX,MAAM,YAAY,CAAC;AAEpB,8BAAsB,wBAAwB;IAC1C,2FAA2F;IAC3F,kBAAyB,IAAI,EAAE,kBAAkB,CAAC;IAElD,qDAAqD;IACrD,kBAAyB,gBAAgB,EAAE,MAAM,CAAC;IAElD;;;;;;OAMG;IACH,kBAAyB,MAAM,EAAE,OAAO,CAAC;IAEzC,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAE1E,iGAAiG;IACjG,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,EAAE;IAEzF;;;OAGG;IACU,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6B5E;;;;;;OAMG;IACH,SAAS,CAAC,oBAAoB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI;IAI/F,4EAA4E;IAC5E,SAAS,CAAC,GAAG,IAAI,IAAI;cAML,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cACzD,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cACxE,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAC7E,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cACtF,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CACvF"}

package/dist/BaseActivitySyncProvider.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview The provider plugin base class.
+ *
+ * A BASE CLASS rather than an interface, deliberately. The parts of a sync pass that every provider
+ * gets wrong in the same way — the watermark, issue collection, hook ordering — live here once and
+ * are not a subclass's to reimplement. A subclass supplies only what is genuinely specific to its
+ * transport: how to fetch, how to map, and (where it disagrees with the default) how to compute its
+ * own high-water mark.
+ *
+ * Providers WRAP existing plumbing rather than reinventing transport: MJ Communication providers
+ * for Gmail and Microsoft Graph, Twilio for SMS and WhatsApp, MJ Actions for social feeds. A
+ * provider's job is to speak its transport in this engine's vocabulary.
+ *
+ * Registered by `DriverClass`, matching every other plugin surface in MJ:
+ *
+ * ```ts
+ * @RegisterClass(BaseActivitySyncProvider, 'Microsoft365')
+ * export class MSGraphActivitySyncProvider extends BaseActivitySyncProvider { ... }
+ * ```
+ *
+ * @module @mj-biz-apps/common-activity-sync
+ */
+import { LogError } from '@memberjunction/core';
+import { ResolveHighWatermark } from './watermark.js';
+export class BaseActivitySyncProvider {
+    /**
+     * One sync pass. Template method — subclasses extend it through the hooks below, never by
+     * overriding this.
+     */
+    async Fetch(query) {
+        const observedAt = this.Now();
+        try {
+            await this.OnBeforeFetch(query);
+            const raw = await this.FetchRaw(query);
+            await this.OnAfterFetch(raw, query);
+            await this.OnBeforeNormalize(raw, query);
+            const items = this.Normalize(raw, query);
+            await this.OnAfterNormalize(items, query);
+            return {
+                Items: items,
+                HighWatermark: this.ComputeHighWatermark(items, observedAt),
+                Issues: raw.Issues,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`BaseActivitySyncProvider.Fetch failed for provider "${this.ProviderTypeCode}" ` +
+                `on mailbox "${query.Mailbox}": ${message}`);
+            await this.OnError(error, query);
+            // Failed, not empty. An empty mailbox is a successful look that found nothing; a
+            // throw means we saw nothing and must not report SUCCESS or clear LastError.
+            return { Items: [], HighWatermark: null, Issues: [message], Failed: true };
+        }
+    }
+    /**
+     * The newest point this pass can honestly claim.
+     *
+     * Overridable for a transport that exposes a better signal than either item time or observation
+     * time (a provider `ModifiedAt`, a server-side cursor). Overriding it means taking on the rules
+     * in `watermark.ts` — read them first.
+     */
+    ComputeHighWatermark(items, observedAt) {
+        return ResolveHighWatermark(this.Kind, items, observedAt);
+    }
+    /** Seam for tests. Everything stored is UTC; a JS Date is a UTC instant. */
+    Now() {
+        return new Date();
+    }
+    // ── Hooks. All no-ops; override any subset. ────────────────────────────────────────────────
+    async OnBeforeFetch(_query) { }
+    async OnAfterFetch(_raw, _query) { }
+    async OnBeforeNormalize(_raw, _query) { }
+    async OnAfterNormalize(_items, _query) { }
+    async OnError(_error, _query) { }
+}
+//# sourceMappingURL=BaseActivitySyncProvider.js.map

package/dist/BaseActivitySyncProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseActivitySyncProvider.js","sourceRoot":"","sources":["../src/BaseActivitySyncProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAStD,MAAM,OAAgB,wBAAwB;IAsB1C;;;OAGG;IACI,KAAK,CAAC,KAAK,CAAC,KAA0B;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAChC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACvC,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAEpC,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzC,MAAM,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAE1C,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,aAAa,EAAE,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,UAAU,CAAC;gBAC3D,MAAM,EAAE,GAAG,CAAC,MAAM;aACrB,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,QAAQ,CACJ,uDAAuD,IAAI,CAAC,gBAAgB,IAAI;gBAC5E,eAAe,KAAK,CAAC,OAAO,MAAM,OAAO,EAAE,CAClD,CAAC;YACF,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YACjC,iFAAiF;YACjF,6EAA6E;YAC7E,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC/E,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACO,oBAAoB,CAAC,KAAgC,EAAE,UAAgB;QAC7E,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IAC9D,CAAC;IAED,4EAA4E;IAClE,GAAG;QACT,OAAO,IAAI,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,8FAA8F;IAEpF,KAAK,CAAC,aAAa,CAAC,MAA2B,IAAkB,CAAC;IAClE,KAAK,CAAC,YAAY,CAAC,IAAc,EAAE,MAA2B,IAAkB,CAAC;IACjF,KAAK,CAAC,iBAAiB,CAAC,IAAc,EAAE,MAA2B,IAAkB,CAAC;IACtF,KAAK,CAAC,gBAAgB,CAAC,MAAwB,EAAE,MAA2B,IAAkB,CAAC;IAC/F,KAAK,CAAC,OAAO,CAAC,MAAe,EAAE,MAA2B,IAAkB,CAAC;CAC1F"}

package/dist/action-result.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Map a fleet run onto the Common.SyncActivities Action result codes.
+ *
+ * Lives next to FleetRunResult so the Action cannot re-invent a success path the engine
+ * already marked failed. The load-failed case (Success=false, ConnectionsAttempted=0) is
+ * not "no connections" — that is the same class of bug as treating a failed ViewLoad as [].
+ */
+export interface FleetSurfaceResult {
+    Fetched: number;
+    Included: number;
+    Duplicates: number;
+    Excluded: number;
+    Failed: number;
+}
+export interface FleetLike {
+    Success: boolean;
+    ConnectionsAttempted: number;
+    Issues: readonly string[];
+    Results: ReadonlyArray<{
+        Result: FleetSurfaceResult;
+    }>;
+}
+export interface FleetTotals {
+    Fetched: number;
+    Written: number;
+    Duplicates: number;
+    Excluded: number;
+    Failed: number;
+}
+export type SyncActionResultCode = 'SUCCESS' | 'PARTIAL' | 'NO_CONNECTIONS' | 'ERROR';
+export interface SyncActionResult {
+    Success: boolean;
+    ResultCode: SyncActionResultCode;
+    Message: string;
+}
+export declare function TotalsFromFleet(fleet: FleetLike): FleetTotals;
+export declare function ActionResultFromFleet(fleet: FleetLike, totals: FleetTotals): SyncActionResult;
+//# sourceMappingURL=action-result.d.ts.map

package/dist/action-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-result.d.ts","sourceRoot":"","sources":["../src/action-result.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,oBAAoB,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,CAW7D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,gBAAgB,CA0B7F"}

package/dist/action-result.js

@@ -0,0 +1,43 @@
+/**
+ * Map a fleet run onto the Common.SyncActivities Action result codes.
+ *
+ * Lives next to FleetRunResult so the Action cannot re-invent a success path the engine
+ * already marked failed. The load-failed case (Success=false, ConnectionsAttempted=0) is
+ * not "no connections" — that is the same class of bug as treating a failed ViewLoad as [].
+ */
+export function TotalsFromFleet(fleet) {
+    return fleet.Results.reduce((sum, run) => ({
+        Fetched: sum.Fetched + run.Result.Fetched,
+        Written: sum.Written + run.Result.Included,
+        Duplicates: sum.Duplicates + run.Result.Duplicates,
+        Excluded: sum.Excluded + run.Result.Excluded,
+        Failed: sum.Failed + run.Result.Failed,
+    }), { Fetched: 0, Written: 0, Duplicates: 0, Excluded: 0, Failed: 0 });
+}
+export function ActionResultFromFleet(fleet, totals) {
+    if (!fleet.Success && fleet.ConnectionsAttempted === 0) {
+        return {
+            Success: false,
+            ResultCode: 'ERROR',
+            Message: fleet.Issues.length
+                ? fleet.Issues.join(' | ')
+                : 'Activity sync failed before any connection was attempted.',
+        };
+    }
+    if (fleet.ConnectionsAttempted === 0) {
+        return {
+            Success: true,
+            ResultCode: 'NO_CONNECTIONS',
+            Message: 'No Active activity-sync connection exists, so nothing was read.',
+        };
+    }
+    return {
+        Success: fleet.Success,
+        ResultCode: fleet.Success ? 'SUCCESS' : 'PARTIAL',
+        Message: `${fleet.ConnectionsAttempted} connection(s): fetched ${totals.Fetched}, ` +
+            `written ${totals.Written}, duplicates ${totals.Duplicates}, ` +
+            `excluded ${totals.Excluded}, failed ${totals.Failed}.` +
+            (fleet.Issues.length ? ` Issues: ${fleet.Issues.join(' | ')}` : ''),
+    };
+}
+//# sourceMappingURL=action-result.js.map

package/dist/action-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-result.js","sourceRoot":"","sources":["../src/action-result.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiCH,MAAM,UAAU,eAAe,CAAC,KAAgB;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CACvB,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACX,OAAO,EAAE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO;QACzC,OAAO,EAAE,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ;QAC1C,UAAU,EAAE,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,UAAU;QAClD,QAAQ,EAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ;QAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM;KACzC,CAAC,EACF,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CACpE,CAAC;AACN,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAgB,EAAE,MAAmB;IACvE,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,oBAAoB,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO;YACH,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,OAAO;YACnB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;gBACxB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;gBAC1B,CAAC,CAAC,2DAA2D;SACpE,CAAC;IACN,CAAC;IACD,IAAI,KAAK,CAAC,oBAAoB,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO;YACH,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,gBAAgB;YAC5B,OAAO,EAAE,iEAAiE;SAC7E,CAAC;IACN,CAAC;IACD,OAAO;QACH,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACjD,OAAO,EACH,GAAG,KAAK,CAAC,oBAAoB,2BAA2B,MAAM,CAAC,OAAO,IAAI;YAC1E,WAAW,MAAM,CAAC,OAAO,gBAAgB,MAAM,CAAC,UAAU,IAAI;YAC9D,YAAY,MAAM,CAAC,QAAQ,YAAY,MAAM,CAAC,MAAM,GAAG;YACvD,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACN,CAAC"}

package/dist/entity-names.d.ts

@@ -0,0 +1,19 @@
+/** Entity names as CodeGen registered them. One place so the engine and writer cannot drift. */
+export declare const ACTIVITY_SYNC_ENTITIES: {
+    readonly Activities: "MJ_BizApps_Common: Activities";
+    readonly ActivityLinks: "MJ_BizApps_Common: Activity Links";
+    readonly ActivityTypes: "MJ_BizApps_Common: Activity Types";
+    readonly Connections: "MJ_BizApps_Common: Activity Sync Connections";
+    readonly ProviderTypes: "MJ_BizApps_Common: Activity Sync Provider Types";
+    readonly RuleSets: "MJ_BizApps_Common: Activity Sync Rule Sets";
+    readonly Rules: "MJ_BizApps_Common: Activity Sync Rules";
+    readonly ConnectionRuleSets: "MJ_BizApps_Common: Activity Sync Connection Rule Sets";
+    readonly Exclusions: "MJ_BizApps_Common: Activity Sync Exclusions";
+    readonly Runs: "MJ_BizApps_Common: Activity Sync Runs";
+    readonly RunDetails: "MJ_BizApps_Common: Activity Sync Run Details";
+    readonly Extensions: "MJ_BizApps_Common: Activity Sync Extensions";
+    readonly ContactMethods: "MJ_BizApps_Common: Contact Methods";
+    readonly People: "MJ_BizApps_Common: People";
+    readonly Organizations: "MJ_BizApps_Common: Organizations";
+};
+//# sourceMappingURL=entity-names.d.ts.map

package/dist/entity-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-names.d.ts","sourceRoot":"","sources":["../src/entity-names.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;CAgBzB,CAAC"}

package/dist/entity-names.js

@@ -0,0 +1,19 @@
+/** Entity names as CodeGen registered them. One place so the engine and writer cannot drift. */
+export const ACTIVITY_SYNC_ENTITIES = {
+    Activities: 'MJ_BizApps_Common: Activities',
+    ActivityLinks: 'MJ_BizApps_Common: Activity Links',
+    ActivityTypes: 'MJ_BizApps_Common: Activity Types',
+    Connections: 'MJ_BizApps_Common: Activity Sync Connections',
+    ProviderTypes: 'MJ_BizApps_Common: Activity Sync Provider Types',
+    RuleSets: 'MJ_BizApps_Common: Activity Sync Rule Sets',
+    Rules: 'MJ_BizApps_Common: Activity Sync Rules',
+    ConnectionRuleSets: 'MJ_BizApps_Common: Activity Sync Connection Rule Sets',
+    Exclusions: 'MJ_BizApps_Common: Activity Sync Exclusions',
+    Runs: 'MJ_BizApps_Common: Activity Sync Runs',
+    RunDetails: 'MJ_BizApps_Common: Activity Sync Run Details',
+    Extensions: 'MJ_BizApps_Common: Activity Sync Extensions',
+    ContactMethods: 'MJ_BizApps_Common: Contact Methods',
+    People: 'MJ_BizApps_Common: People',
+    Organizations: 'MJ_BizApps_Common: Organizations',
+};
+//# sourceMappingURL=entity-names.js.map

package/dist/entity-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-names.js","sourceRoot":"","sources":["../src/entity-names.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,UAAU,EAAE,+BAA+B;IAC3C,aAAa,EAAE,mCAAmC;IAClD,aAAa,EAAE,mCAAmC;IAClD,WAAW,EAAE,8CAA8C;IAC3D,aAAa,EAAE,iDAAiD;IAChE,QAAQ,EAAE,4CAA4C;IACtD,KAAK,EAAE,wCAAwC;IAC/C,kBAAkB,EAAE,uDAAuD;IAC3E,UAAU,EAAE,6CAA6C;IACzD,IAAI,EAAE,uCAAuC;IAC7C,UAAU,EAAE,8CAA8C;IAC1D,UAAU,EAAE,6CAA6C;IACzD,cAAc,EAAE,oCAAoC;IACpD,MAAM,EAAE,2BAA2B;IACnC,aAAa,EAAE,kCAAkC;CAC3C,CAAC"}

package/dist/extensions.d.ts

@@ -0,0 +1,37 @@
+import { type ActivityWriteContext, type BaseActivitySyncExtension } from './BaseActivitySyncExtension.js';
+export interface ExtensionRegistration {
+    ID: string;
+    DriverClass: string;
+    Sequence: number;
+    FailurePolicy: 'Skip' | 'Abort';
+    TimeoutMS: number;
+    ActivitySyncConnectionID: string | null;
+    ActivitySyncProviderTypeID: string | null;
+}
+export interface ExtensionStamp {
+    ID: string;
+    LastError: string | null;
+}
+export interface ExtensionRunResult {
+    Aborted: boolean;
+    Errors: number;
+    Stamps: ExtensionStamp[];
+}
+/** Enabled rows that apply to this connection / provider type (null = global). */
+export declare function ExtensionsExtraFilter(connectionID: string, providerTypeID: string | null): string;
+/**
+ * Race `work` against TimeoutMS. This REJECTS THE WAITER; it does not cancel `work`.
+ *
+ * Pass an AbortController so Enrich can see `context.Signal.aborted` and stop. Work that
+ * ignores the signal keeps running inside the open write transaction.
+ */
+export declare function WithTimeout<T>(work: Promise<T>, timeoutMS: number, label: string, controller?: AbortController): Promise<T>;
+/**
+ * Run registered extensions in Sequence order.
+ *
+ * A missing DriverClass is a failure of that row, not a skip of the rest.
+ * Stamps are returned so LastError / LastRunAt persist OUTSIDE the activity
+ * transaction — an Abort rollback must not also erase the error that caused it.
+ */
+export declare function RunRegisteredExtensions(context: ActivityWriteContext, rows: readonly ExtensionRegistration[], create: (driverClass: string) => BaseActivitySyncExtension | null): Promise<ExtensionRunResult>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAQA,OAAO,EACH,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EACjC,MAAM,gCAAgC,CAAC;AAExC,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAOjG;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAC/B,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,eAAe,GAC7B,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,SAAS,qBAAqB,EAAE,EACtC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,yBAAyB,GAAG,IAAI,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAkC7B"}

package/dist/extensions.js

@@ -0,0 +1,80 @@
+/**
+ * In-stream extension dispatch — Sequence order, timeout, Skip vs Abort.
+ *
+ * Runs inside the Activity write transaction. Skip records the error and lets
+ * the activity commit; Abort sets `Aborted` so the writer can roll the write
+ * back. Stamps are always returned so LastError survives an Abort rollback.
+ */
+import { RequireUUID } from './sql.js';
+/** Enabled rows that apply to this connection / provider type (null = global). */
+export function ExtensionsExtraFilter(connectionID, providerTypeID) {
+    const conn = RequireUUID(connectionID, 'ActivitySyncConnectionID');
+    const connClause = `(ActivitySyncConnectionID IS NULL OR ActivitySyncConnectionID = '${conn}')`;
+    const typeClause = providerTypeID
+        ? `(ActivitySyncProviderTypeID IS NULL OR ActivitySyncProviderTypeID = '${RequireUUID(providerTypeID, 'ActivitySyncProviderTypeID')}')`
+        : 'ActivitySyncProviderTypeID IS NULL';
+    return `IsEnabled = 1 AND ${connClause} AND ${typeClause}`;
+}
+/**
+ * Race `work` against TimeoutMS. This REJECTS THE WAITER; it does not cancel `work`.
+ *
+ * Pass an AbortController so Enrich can see `context.Signal.aborted` and stop. Work that
+ * ignores the signal keeps running inside the open write transaction.
+ */
+export async function WithTimeout(work, timeoutMS, label, controller) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller?.abort();
+            reject(new Error(`${label} timed out after ${timeoutMS}ms`));
+        }, timeoutMS);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Run registered extensions in Sequence order.
+ *
+ * A missing DriverClass is a failure of that row, not a skip of the rest.
+ * Stamps are returned so LastError / LastRunAt persist OUTSIDE the activity
+ * transaction — an Abort rollback must not also erase the error that caused it.
+ */
+export async function RunRegisteredExtensions(context, rows, create) {
+    const ordered = [...rows].sort((a, b) => a.Sequence - b.Sequence);
+    const result = { Aborted: false, Errors: 0, Stamps: [] };
+    for (const row of ordered) {
+        const instance = create(row.DriverClass);
+        if (!instance) {
+            const message = `No BaseActivitySyncExtension registered for DriverClass '${row.DriverClass}'.`;
+            result.Errors++;
+            result.Stamps.push({ ID: row.ID, LastError: message });
+            if (row.FailurePolicy === 'Abort') {
+                result.Aborted = true;
+                return result;
+            }
+            continue;
+        }
+        const controller = new AbortController();
+        const timed = { ...context, Signal: controller.signal };
+        try {
+            await WithTimeout(instance.Enrich(timed), row.TimeoutMS, row.DriverClass, controller);
+            result.Stamps.push({ ID: row.ID, LastError: null });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            result.Errors++;
+            result.Stamps.push({ ID: row.ID, LastError: message });
+            if (row.FailurePolicy === 'Abort') {
+                result.Aborted = true;
+                return result;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

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

package/dist/identity.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Participant address → Person / Organization.
+ *
+ * An unmatched address becomes an unresolved ActivityLink (IdentityKind + IdentityValue).
+ * This file never creates a Person.
+ */
+import { type UserInfo } from '@memberjunction/core';
+import type { ResolvedParty, UnresolvedParty } from './BaseActivitySyncExtension.js';
+import type { ItemParticipant } from './types.js';
+export interface KnownAddress {
+    Address: string;
+    PersonID: string | null;
+    OrganizationID: string | null;
+}
+export interface IdentityResolution {
+    Resolved: ResolvedParty[];
+    Unresolved: UnresolvedParty[];
+    Known: Map<string, KnownAddress>;
+    LookupFailed: boolean;
+}
+export declare class IdentityResolver {
+    /**
+     * ONE query for the whole batch. A failed read is LookupFailed — not "nobody matched" —
+     * because those two look the same and only one may advance the watermark.
+     */
+    Resolve(participants: readonly ItemParticipant[], contextUser: UserInfo): Promise<IdentityResolution>;
+    private lookup;
+}
+export declare function Quote(value: string): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAW,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjC,YAAY,EAAE,OAAO,CAAC;CACzB;AASD,qBAAa,gBAAgB;IACzB;;;OAGG;IACU,OAAO,CAChB,YAAY,EAAE,SAAS,eAAe,EAAE,EACxC,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,kBAAkB,CAAC;YA0ChB,MAAM;CAgCvB;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C"}

package/dist/identity.js

@@ -0,0 +1,90 @@
+/**
+ * Participant address → Person / Organization.
+ *
+ * An unmatched address becomes an unresolved ActivityLink (IdentityKind + IdentityValue).
+ * This file never creates a Person.
+ */
+import { RunView } from '@memberjunction/core';
+import { ACTIVITY_SYNC_ENTITIES } from './entity-names.js';
+import { EscapeText, InList } from './sql.js';
+export class IdentityResolver {
+    /**
+     * ONE query for the whole batch. A failed read is LookupFailed — not "nobody matched" —
+     * because those two look the same and only one may advance the watermark.
+     */
+    async Resolve(participants, contextUser) {
+        const addresses = [
+            ...new Set(participants.map((p) => p.Address.trim().toLowerCase()).filter(Boolean)),
+        ];
+        if (addresses.length === 0) {
+            return { Resolved: [], Unresolved: [], Known: new Map(), LookupFailed: false };
+        }
+        const { known, failed } = await this.lookup(addresses, contextUser);
+        const resolved = [];
+        const unresolved = [];
+        const seen = new Set();
+        for (const participant of participants) {
+            const address = participant.Address.trim().toLowerCase();
+            if (!address)
+                continue;
+            const hit = known.get(address);
+            if (hit?.PersonID) {
+                const key = `p:${hit.PersonID}:${participant.Role}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                resolved.push({ Kind: 'Person', RecordID: hit.PersonID, Role: participant.Role });
+            }
+            else if (hit?.OrganizationID) {
+                const key = `o:${hit.OrganizationID}:${participant.Role}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                resolved.push({ Kind: 'Organization', RecordID: hit.OrganizationID, Role: participant.Role });
+            }
+            else {
+                const key = `i:${participant.IdentityKind}:${address}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                unresolved.push({
+                    Kind: participant.IdentityKind,
+                    Value: address,
+                    Role: participant.Role,
+                });
+            }
+        }
+        return { Resolved: resolved, Unresolved: unresolved, Known: known, LookupFailed: failed };
+    }
+    async lookup(addresses, contextUser) {
+        const rv = new RunView();
+        const res = await rv.RunView({
+            EntityName: ACTIVITY_SYNC_ENTITIES.ContactMethods,
+            // Sargable equality. Literals are already lowercased. SQL Server CI collations
+            // match mixed-case stored values; wrapping the column in LOWER() would disable
+            // the index on the highest-cardinality lookup in a run. PostgreSQL is CS by
+            // default and wants citext or a functional index, not LOWER(Value) as a scan.
+            ExtraFilter: `Value IN (${InList(addresses)})`,
+            ResultType: 'simple',
+        }, contextUser);
+        if (!res.Success) {
+            return { known: new Map(), failed: true };
+        }
+        const known = new Map();
+        for (const row of res.Results ?? []) {
+            const address = String(row.Value ?? '').trim().toLowerCase();
+            if (!address)
+                continue;
+            known.set(address, {
+                Address: address,
+                PersonID: row.PersonID ?? null,
+                OrganizationID: row.OrganizationID ?? null,
+            });
+        }
+        return { known, failed: false };
+    }
+}
+export function Quote(value) {
+    return EscapeText(value);
+}
+//# sourceMappingURL=identity.js.map