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

package/dist/watermark.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview The two watermark rules, as enforced behaviour rather than advice.
+ *
+ * These live in the engine (and are consumed by {@link BaseActivitySyncProvider}) rather than being
+ * exported as helpers a provider may forget to call. Both failure modes are SILENT and PERMANENT,
+ * which is exactly the class of rule that must not be optional.
+ *
+ * @module @mj-biz-apps/common-activity-sync
+ */
+import { ActivitySourceKind, NormalizedItem } from './types.js';
+/** The per-item tallies a run produces, and the only input to whether the watermark may move. */
+export interface RunOutcome {
+    /** Passed qualification and was written (or was a duplicate — a duplicate has been seen). */
+    Settled: number;
+    /** Qualification said no. SEEN to a conclusion, so the watermark may pass it. */
+    Discarded: number;
+    /**
+     * Errored before reaching a conclusion. NOT seen.
+     *
+     * The distinction is the whole rule. Where a transport has no date filter, anything the
+     * watermark passes can never be re-fetched, so advancing over a failure loses the item
+     * permanently.
+     */
+    Failed: number;
+}
+/**
+ * The newest point this batch can honestly claim to have seen.
+ *
+ * @param kind        the surface — selects the basis (see {@link WatermarkBasisForKind})
+ * @param items       the batch's normalized items
+ * @param observedAt  when the provider looked; used by future-dated surfaces
+ * @returns the candidate watermark, or null when there is nothing to claim
+ */
+export declare function ResolveHighWatermark(kind: ActivitySourceKind, items: readonly NormalizedItem[], observedAt: Date): Date | null;
+/**
+ * Whether the run earned the right to move the watermark forward.
+ *
+ * Any failure withholds it. The cost of not advancing is re-fetching items the next run will
+ * recognise as duplicates; the cost of advancing wrongly is losing them for good. Those are not
+ * comparable, so this is deliberately not a threshold.
+ */
+export declare function CanAdvanceWatermark(outcome: RunOutcome): boolean;
+/**
+ * The watermark to persist after a run — the current value unless the run both earned an advance
+ * and actually moved forward.
+ *
+ * Never moves BACKWARDS. Two runs racing (a scheduled job whose `ConcurrencyMode` is not `Skip`)
+ * can otherwise leave the watermark behind where the earlier run reached, which silently re-reads
+ * a window on every subsequent pass.
+ */
+/** Calendar watermark lives in ActivitySyncConnection.Settings so it cannot hide behind LastSyncAt. */
+export declare const CALENDAR_WATERMARK_SETTING = "CalendarLastSyncAt";
+export declare function ParseConnectionSettings(settings: string | null | undefined): Record<string, unknown>;
+/**
+ * One watermark per surface. Messages use LastSyncAt; calendar uses Settings.
+ * A shared column takes the max of both, so a meeting older than the newest
+ * email is judged already-seen and skipped forever.
+ */
+export declare function SurfaceWatermark(kind: ActivitySourceKind, lastSyncAt: Date | string | null | undefined, settings: string | null | undefined): Date | null;
+/** Merge the calendar watermark into Settings without dropping other keys. */
+export declare function MergeCalendarWatermark(settings: string | null | undefined, at: Date): string;
+export declare function NextWatermark(current: Date | null, candidate: Date | null, outcome: RunOutcome): Date | null;
+//# sourceMappingURL=watermark.d.ts.map

package/dist/watermark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watermark.d.ts","sourceRoot":"","sources":["../src/watermark.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAEvF,iGAAiG;AACjG,MAAM,WAAW,UAAU;IACvB,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,UAAU,EAAE,IAAI,GACjB,IAAI,GAAG,IAAI,CAMb;AAaD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAE/D,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWpG;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,kBAAkB,EACxB,UAAU,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,IAAI,GAAG,IAAI,CAMb;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAI5F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAQ5G"}

package/dist/watermark.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview The two watermark rules, as enforced behaviour rather than advice.
+ *
+ * These live in the engine (and are consumed by {@link BaseActivitySyncProvider}) rather than being
+ * exported as helpers a provider may forget to call. Both failure modes are SILENT and PERMANENT,
+ * which is exactly the class of rule that must not be optional.
+ *
+ * @module @mj-biz-apps/common-activity-sync
+ */
+import { WatermarkBasisForKind } from './types.js';
+/**
+ * The newest point this batch can honestly claim to have seen.
+ *
+ * @param kind        the surface — selects the basis (see {@link WatermarkBasisForKind})
+ * @param items       the batch's normalized items
+ * @param observedAt  when the provider looked; used by future-dated surfaces
+ * @returns the candidate watermark, or null when there is nothing to claim
+ */
+export function ResolveHighWatermark(kind, items, observedAt) {
+    if (WatermarkBasisForKind(kind) === 'ObservationTime') {
+        // A future-dated surface reports when it LOOKED, not when its items happen.
+        return items.length > 0 ? observedAt : null;
+    }
+    return newestStartedAt(items);
+}
+/** The latest `StartedAt` across the batch, or null when the batch is empty. */
+function newestStartedAt(items) {
+    let newest = null;
+    for (const item of items) {
+        if (newest === null || item.StartedAt.getTime() > newest.getTime()) {
+            newest = item.StartedAt;
+        }
+    }
+    return newest;
+}
+/**
+ * Whether the run earned the right to move the watermark forward.
+ *
+ * Any failure withholds it. The cost of not advancing is re-fetching items the next run will
+ * recognise as duplicates; the cost of advancing wrongly is losing them for good. Those are not
+ * comparable, so this is deliberately not a threshold.
+ */
+export function CanAdvanceWatermark(outcome) {
+    return outcome.Failed === 0;
+}
+/**
+ * The watermark to persist after a run — the current value unless the run both earned an advance
+ * and actually moved forward.
+ *
+ * Never moves BACKWARDS. Two runs racing (a scheduled job whose `ConcurrencyMode` is not `Skip`)
+ * can otherwise leave the watermark behind where the earlier run reached, which silently re-reads
+ * a window on every subsequent pass.
+ */
+/** Calendar watermark lives in ActivitySyncConnection.Settings so it cannot hide behind LastSyncAt. */
+export const CALENDAR_WATERMARK_SETTING = 'CalendarLastSyncAt';
+export function ParseConnectionSettings(settings) {
+    if (!settings)
+        return {};
+    try {
+        const parsed = JSON.parse(settings);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* hand-edited JSON is treated as empty — re-read the window, let dedupe absorb it */
+    }
+    return {};
+}
+function asDate(value) {
+    if (value == null || value === '')
+        return null;
+    const d = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+/**
+ * One watermark per surface. Messages use LastSyncAt; calendar uses Settings.
+ * A shared column takes the max of both, so a meeting older than the newest
+ * email is judged already-seen and skipped forever.
+ */
+export function SurfaceWatermark(kind, lastSyncAt, settings) {
+    if (kind === 'Calendar') {
+        const raw = ParseConnectionSettings(settings)[CALENDAR_WATERMARK_SETTING];
+        return typeof raw === 'string' ? asDate(raw) : null;
+    }
+    return asDate(lastSyncAt);
+}
+/** Merge the calendar watermark into Settings without dropping other keys. */
+export function MergeCalendarWatermark(settings, at) {
+    const bag = ParseConnectionSettings(settings);
+    bag[CALENDAR_WATERMARK_SETTING] = at.toISOString();
+    return JSON.stringify(bag);
+}
+export function NextWatermark(current, candidate, outcome) {
+    if (!CanAdvanceWatermark(outcome) || candidate === null) {
+        return current;
+    }
+    if (current !== null && candidate.getTime() <= current.getTime()) {
+        return current;
+    }
+    return candidate;
+}
+//# sourceMappingURL=watermark.js.map

package/dist/watermark.js.map

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

package/dist/writer.d.ts

@@ -0,0 +1,132 @@
+/**
+ * One Activity plus N ActivityLink rows, atomically.
+ *
+ * ONE writer, TWO entry points (plans/mj-entity-action-workflow-adoption.md §3.2):
+ * - `Write` — the sync engine's path. Synced rows set Visibility = 'Private' explicitly and dispatch
+ *   registered extensions inside the write transaction.
+ * - `WriteManual` — the manual / declarative path (`Common.LogActivity`, UI logging). Visibility
+ *   defaults to the column's own 'Internal', no connection is stamped, and sync extensions do NOT
+ *   run — those fire on ingest, not on a record being logged (see §8 of the same plan).
+ *
+ * Both share the same transactional core, dedupe, link writing and type resolution, so the
+ * declarative path and the ingest path cannot drift.
+ *
+ * Unmatched participants become unresolved links — never a new Person.
+ */
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import type { mjBizAppsCommonActivityEntity, mjBizAppsCommonActivityLinkEntity } from '@mj-biz-apps/common-entities';
+import type { ResolvedParty, UnresolvedParty, ActivityWriteContext } from './BaseActivitySyncExtension.js';
+import type { ActivityDirection, ActivityIdentityKind, ActivityLinkRole, NormalizedItem } from './types.js';
+export type ActivitySourceValue = 'Manual' | 'System' | 'Integration';
+/** Mirrors `CK_Activity_Status`. */
+export type ActivityStatusValue = 'Logged' | 'Scheduled' | 'Completed' | 'Cancelled' | 'Failed';
+/** Mirrors `CK_Activity_Visibility`. */
+export type ActivityVisibilityValue = 'Internal' | 'Private';
+/** How much of an included body to persist. Default Snippet — Full is a per-connection opt-in. */
+export type StoreBodyPolicy = 'None' | 'Snippet' | 'Full';
+export declare const BODY_SNIPPET_CHARS = 500;
+/** Read StoreBody from ActivitySyncConnection.Settings. Missing / invalid / unparseable → Snippet. */
+export declare function StoreBodyFromSettings(settings: string | null | undefined): StoreBodyPolicy;
+export declare function BodyForStorage(body: string | null | undefined, policy?: StoreBodyPolicy): string | null;
+/**
+ * One link on an activity: either a resolved link to any entity's record (EntityName + RecordID)
+ * or an unresolved identity (IdentityKind + IdentityValue). Exactly one of the two shapes.
+ */
+export interface ActivityLinkSpec {
+    Role: ActivityLinkRole;
+    EntityName?: string;
+    RecordID?: string;
+    IdentityKind?: ActivityIdentityKind;
+    IdentityValue?: string;
+}
+export interface WriteActivityInput {
+    Item: NormalizedItem;
+    ConnectionID: string;
+    SourceSystem: string;
+    /** Integration for a live provider; System for a fixture — never Integration from a non-live source. */
+    Source: ActivitySourceValue;
+    Resolved: ResolvedParty[];
+    Unresolved: UnresolvedParty[];
+    /** Default Snippet. Independent of SkippedContentPolicy. */
+    StoreBody?: StoreBodyPolicy;
+}
+/**
+ * A manually or declaratively logged activity — no sync connection, no ingest item.
+ *
+ * Defaults follow the column defaults for a manual log: Visibility 'Internal' (the sync path's
+ * 'Private' is for mail nobody chose to share), Status 'Logged', Direction 'Internal',
+ * Source 'Manual'. 'Integration' is deliberately not accepted here — that word belongs to the
+ * sync engine's entry point.
+ */
+export interface WriteManualActivityInput {
+    /** `ActivityType.Code` — resolved by CODE so renaming a type never breaks callers. */
+    TypeCode: string;
+    Title: string;
+    StartedAt: Date;
+    EndedAt?: Date | null;
+    Description?: string | null;
+    Direction?: ActivityDirection;
+    Status?: ActivityStatusValue;
+    Visibility?: ActivityVisibilityValue;
+    Source?: Exclude<ActivitySourceValue, 'Integration'>;
+    Location?: string | null;
+    /** JSON extras that are not query predicates. Stringified into `Activity.Details`. */
+    Details?: Record<string, unknown> | null;
+    /**
+     * Optional idempotency pair. When BOTH are set, a second write with the same pair is a no-op
+     * that reports `AlreadyPresent` — the same dedupe the sync path uses. SourceSystem is required
+     * whenever ExternalID is set (the column contract).
+     */
+    SourceSystem?: string | null;
+    ExternalID?: string | null;
+    Links?: ActivityLinkSpec[];
+}
+export interface WriteActivityResult {
+    Success: boolean;
+    ActivityID: string | null;
+    AlreadyPresent: boolean;
+    Links: mjBizAppsCommonActivityLinkEntity[];
+    Activity: mjBizAppsCommonActivityEntity | null;
+    Issues: string[];
+}
+export interface WriteOptions {
+    ProviderTypeCode: string;
+    /**
+     * Runs inside the open write transaction, after the activity and its party
+     * links are saved and before commit. This is where registered extensions
+     * add app-specific links. Throwing rolls the write back.
+     */
+    OnWritten?: (context: ActivityWriteContext) => Promise<void>;
+}
+/**
+ * Guard-clause validation for the manual entry point. Returns problems rather than throwing so the
+ * writer can report them on the result like every other failure.
+ */
+export declare function ValidateManualActivityInput(input: WriteManualActivityInput): string[];
+export declare class ActivityWriter {
+    /** The sync engine's entry point: connection-stamped, Visibility 'Private', extensions dispatched. */
+    Write(input: WriteActivityInput, provider: IMetadataProvider, contextUser: UserInfo, options?: WriteOptions): Promise<WriteActivityResult>;
+    /**
+     * The manual / declarative entry point (`Common.LogActivity`, UI logging).
+     *
+     * Same transactional core, dedupe and link writing as `Write`; different defaults (Visibility
+     * 'Internal', no connection) and NO extension dispatch — sync extensions enrich an item being
+     * ingested, and a manually logged activity is not one.
+     */
+    WriteManual(input: WriteManualActivityInput, provider: IMetadataProvider, contextUser: UserInfo): Promise<WriteActivityResult>;
+    BuildWriteContext(result: WriteActivityResult, input: WriteActivityInput, contextUser: UserInfo, provider: IMetadataProvider, providerTypeCode: string): ActivityWriteContext | null;
+    /**
+     * The shared transactional core: save the activity, write its links in sequence, run the
+     * optional in-transaction callback, commit. Any failure rolls the whole write back.
+     */
+    private writeWithLinks;
+    private fillSyncFields;
+    private fillManualFields;
+    private planLinks;
+    private dedupeLinks;
+    private emptyResult;
+    private writeLink;
+    private resolveTypeByCode;
+    private findByExternalKey;
+}
+//# sourceMappingURL=writer.d.ts.map

package/dist/writer.d.ts.map

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

package/dist/writer.js

@@ -0,0 +1,326 @@
+/**
+ * One Activity plus N ActivityLink rows, atomically.
+ *
+ * ONE writer, TWO entry points (plans/mj-entity-action-workflow-adoption.md §3.2):
+ * - `Write` — the sync engine's path. Synced rows set Visibility = 'Private' explicitly and dispatch
+ *   registered extensions inside the write transaction.
+ * - `WriteManual` — the manual / declarative path (`Common.LogActivity`, UI logging). Visibility
+ *   defaults to the column's own 'Internal', no connection is stamped, and sync extensions do NOT
+ *   run — those fire on ingest, not on a record being logged (see §8 of the same plan).
+ *
+ * Both share the same transactional core, dedupe, link writing and type resolution, so the
+ * declarative path and the ingest path cannot drift.
+ *
+ * Unmatched participants become unresolved links — never a new Person.
+ */
+import { LogError, RunView, } from '@memberjunction/core';
+import { ACTIVITY_SYNC_ENTITIES } from './entity-names.js';
+import { EscapeText } from './sql.js';
+function isDatabaseProvider(provider) {
+    return ('BeginEntityTransaction' in provider &&
+        typeof provider.BeginEntityTransaction === 'function');
+}
+export const BODY_SNIPPET_CHARS = 500;
+/** Read StoreBody from ActivitySyncConnection.Settings. Missing / invalid / unparseable → Snippet. */
+export function StoreBodyFromSettings(settings) {
+    if (!settings)
+        return 'Snippet';
+    try {
+        const parsed = JSON.parse(settings);
+        if (parsed !== null && typeof parsed === 'object' && 'StoreBody' in parsed) {
+            const value = parsed.StoreBody;
+            if (value === 'None' || value === 'Full' || value === 'Snippet')
+                return value;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return 'Snippet';
+}
+export function BodyForStorage(body, policy = 'Snippet') {
+    const text = body ?? '';
+    if (policy === 'None')
+        return null;
+    if (policy === 'Full')
+        return text.length > 0 ? text : null;
+    if (!text)
+        return null;
+    return text.length <= BODY_SNIPPET_CHARS ? text : text.slice(0, BODY_SNIPPET_CHARS);
+}
+/**
+ * Guard-clause validation for the manual entry point. Returns problems rather than throwing so the
+ * writer can report them on the result like every other failure.
+ */
+export function ValidateManualActivityInput(input) {
+    const issues = [];
+    if (!input.TypeCode?.trim())
+        issues.push('TypeCode is required.');
+    if (!input.Title?.trim())
+        issues.push('Title is required.');
+    if (!(input.StartedAt instanceof Date) || Number.isNaN(input.StartedAt.getTime())) {
+        issues.push('StartedAt must be a valid date.');
+    }
+    else if (input.EndedAt instanceof Date && input.EndedAt.getTime() < input.StartedAt.getTime()) {
+        issues.push('EndedAt must be on or after StartedAt.');
+    }
+    if (input.ExternalID && !input.SourceSystem) {
+        issues.push('SourceSystem is required when ExternalID is set.');
+    }
+    for (const [index, link] of (input.Links ?? []).entries()) {
+        const resolved = Boolean(link.EntityName && link.RecordID);
+        const identity = Boolean(link.IdentityKind && link.IdentityValue);
+        if (resolved === identity) {
+            issues.push(`Link ${index + 1} must carry either EntityName + RecordID or IdentityKind + IdentityValue.`);
+        }
+    }
+    return issues;
+}
+export class ActivityWriter {
+    /** The sync engine's entry point: connection-stamped, Visibility 'Private', extensions dispatched. */
+    async Write(input, provider, contextUser, options) {
+        const result = this.emptyResult();
+        const typeID = await this.resolveTypeByCode(input.Item.TypeCode, contextUser);
+        if (!typeID) {
+            result.Issues.push(`No ActivityType with Code '${input.Item.TypeCode}' is seeded.`);
+            return result;
+        }
+        const existing = await this.findByExternalKey(input.SourceSystem, input.Item.ExternalID, contextUser);
+        if (existing) {
+            result.Success = true;
+            result.ActivityID = existing;
+            result.AlreadyPresent = true;
+            return result;
+        }
+        if (!isDatabaseProvider(provider)) {
+            result.Issues.push('This provider cannot open a transaction; ActivityWriter is server-only.');
+            return result;
+        }
+        const onWritten = options?.OnWritten;
+        const afterLinks = onWritten
+            ? async (activity, links) => {
+                const writeContext = this.BuildWriteContext({ ...result, Activity: activity, ActivityID: activity.ID, Success: true, Links: links }, input, contextUser, provider, options.ProviderTypeCode);
+                if (!writeContext)
+                    return links;
+                await onWritten(writeContext);
+                return writeContext.Links;
+            }
+            : undefined;
+        return this.writeWithLinks(provider, contextUser, result, (activity) => this.fillSyncFields(activity, input, typeID, contextUser), this.planLinks(input), afterLinks);
+    }
+    /**
+     * The manual / declarative entry point (`Common.LogActivity`, UI logging).
+     *
+     * Same transactional core, dedupe and link writing as `Write`; different defaults (Visibility
+     * 'Internal', no connection) and NO extension dispatch — sync extensions enrich an item being
+     * ingested, and a manually logged activity is not one.
+     */
+    async WriteManual(input, provider, contextUser) {
+        const result = this.emptyResult();
+        const problems = ValidateManualActivityInput(input);
+        if (problems.length > 0) {
+            result.Issues.push(...problems);
+            return result;
+        }
+        const typeID = await this.resolveTypeByCode(input.TypeCode, contextUser);
+        if (!typeID) {
+            result.Issues.push(`No ActivityType with Code '${input.TypeCode}' is seeded.`);
+            return result;
+        }
+        if (input.SourceSystem && input.ExternalID) {
+            const existing = await this.findByExternalKey(input.SourceSystem, input.ExternalID, contextUser);
+            if (existing) {
+                result.Success = true;
+                result.ActivityID = existing;
+                result.AlreadyPresent = true;
+                return result;
+            }
+        }
+        if (!isDatabaseProvider(provider)) {
+            result.Issues.push('This provider cannot open a transaction; ActivityWriter is server-only.');
+            return result;
+        }
+        return this.writeWithLinks(provider, contextUser, result, (activity) => this.fillManualFields(activity, input, typeID, contextUser), this.dedupeLinks(input.Links ?? []));
+    }
+    BuildWriteContext(result, input, contextUser, provider, providerTypeCode) {
+        if (!result.Activity || !result.ActivityID)
+            return null;
+        return {
+            Activity: result.Activity,
+            Links: result.Links,
+            Item: input.Item,
+            ResolvedParties: input.Resolved,
+            UnresolvedParties: input.Unresolved,
+            ConnectionID: input.ConnectionID,
+            ProviderTypeCode: providerTypeCode,
+            ContextUser: contextUser,
+            Provider: provider,
+        };
+    }
+    /**
+     * The shared transactional core: save the activity, write its links in sequence, run the
+     * optional in-transaction callback, commit. Any failure rolls the whole write back.
+     */
+    async writeWithLinks(provider, contextUser, result, fill, links, afterLinks) {
+        const scope = await provider.BeginEntityTransaction();
+        try {
+            const activity = await provider.GetEntityObject(ACTIVITY_SYNC_ENTITIES.Activities, contextUser);
+            activity.NewRecord();
+            fill(activity);
+            if (!(await activity.Save())) {
+                await scope.Rollback();
+                result.Issues.push(activity.LatestResult?.CompleteMessage ?? 'Activity.Save failed.');
+                return result;
+            }
+            let sequence = 0;
+            for (const link of links) {
+                const row = await this.writeLink(link, activity.ID, ++sequence, provider, contextUser);
+                if (!row) {
+                    await scope.Rollback();
+                    result.Issues.push(`Link could not be written (role ${link.Role}).`);
+                    return result;
+                }
+                result.Links.push(row);
+            }
+            if (afterLinks) {
+                result.Links = await afterLinks(activity, result.Links);
+            }
+            await scope.Commit();
+            result.Success = true;
+            result.ActivityID = activity.ID;
+            result.Activity = activity;
+            return result;
+        }
+        catch (err) {
+            LogError(`ActivityWriter.Write failed: ${err}`);
+            try {
+                await scope.Rollback();
+            }
+            catch {
+                /* already failed */
+            }
+            result.Issues.push(String(err));
+            return result;
+        }
+    }
+    fillSyncFields(activity, input, typeID, contextUser) {
+        activity.ActivityTypeID = typeID;
+        activity.Title = (input.Item.Subject || '(no subject)').slice(0, 200);
+        activity.StartedAt = input.Item.StartedAt;
+        activity.EndedAt = input.Item.EndedAt;
+        activity.Description = BodyForStorage(input.Item.Body, input.StoreBody ?? 'Snippet');
+        activity.Direction = input.Item.Direction;
+        activity.Status = input.Item.Cancelled ? 'Cancelled' : 'Logged';
+        activity.Visibility = 'Private';
+        activity.Source = input.Source;
+        activity.Location = input.Item.Location;
+        activity.Details = JSON.stringify(input.Item.Raw);
+        activity.ExternalThreadID = input.Item.ExternalThreadID;
+        activity.ActivitySyncConnectionID = input.ConnectionID;
+        activity.SourceSystem = input.SourceSystem;
+        activity.ExternalID = input.Item.ExternalID;
+        activity.LoggedByUserID = contextUser.ID;
+    }
+    fillManualFields(activity, input, typeID, contextUser) {
+        activity.ActivityTypeID = typeID;
+        activity.Title = input.Title.slice(0, 500);
+        activity.StartedAt = input.StartedAt;
+        activity.EndedAt = input.EndedAt ?? null;
+        activity.Description = input.Description ?? null;
+        activity.Direction = input.Direction ?? 'Internal';
+        activity.Status = input.Status ?? 'Logged';
+        activity.Visibility = input.Visibility ?? 'Internal';
+        activity.Source = input.Source ?? 'Manual';
+        activity.Location = input.Location ?? null;
+        activity.Details = input.Details ? JSON.stringify(input.Details) : null;
+        activity.SourceSystem = input.SourceSystem ?? null;
+        activity.ExternalID = input.ExternalID ?? null;
+        activity.LoggedByUserID = contextUser.ID;
+    }
+    planLinks(input) {
+        const links = [];
+        for (const party of input.Resolved) {
+            links.push({
+                Role: party.Role,
+                EntityName: party.Kind === 'Person' ? ACTIVITY_SYNC_ENTITIES.People : ACTIVITY_SYNC_ENTITIES.Organizations,
+                RecordID: party.RecordID,
+            });
+        }
+        for (const party of input.Unresolved) {
+            links.push({
+                Role: party.Role,
+                IdentityKind: party.Kind,
+                IdentityValue: party.Value,
+            });
+        }
+        return this.dedupeLinks(links);
+    }
+    dedupeLinks(links) {
+        const seen = new Set();
+        const out = [];
+        for (const link of links) {
+            const key = link.RecordID
+                ? `r:${link.EntityName}:${link.RecordID.toLowerCase()}`
+                : `i:${link.IdentityKind}:${(link.IdentityValue ?? '').toLowerCase()}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(link);
+        }
+        return out;
+    }
+    emptyResult() {
+        return {
+            Success: false,
+            ActivityID: null,
+            AlreadyPresent: false,
+            Links: [],
+            Activity: null,
+            Issues: [],
+        };
+    }
+    async writeLink(link, activityID, sequence, provider, contextUser) {
+        const entityID = link.EntityName
+            ? provider.Entities.find((e) => e.Name === link.EntityName)?.ID
+            : undefined;
+        if (link.EntityName && !entityID)
+            return null;
+        const row = await provider.GetEntityObject(ACTIVITY_SYNC_ENTITIES.ActivityLinks, contextUser);
+        row.NewRecord();
+        row.ActivityID = activityID;
+        row.Role = link.Role;
+        row.Sequence = sequence;
+        if (link.RecordID && entityID) {
+            row.EntityID = entityID;
+            row.RecordID = link.RecordID;
+        }
+        else {
+            row.IdentityKind = link.IdentityKind ?? 'Email';
+            row.IdentityValue = link.IdentityValue ?? '';
+        }
+        if (!(await row.Save()))
+            return null;
+        return row;
+    }
+    async resolveTypeByCode(code, contextUser) {
+        const rv = new RunView();
+        const res = await rv.RunView({
+            EntityName: ACTIVITY_SYNC_ENTITIES.ActivityTypes,
+            ExtraFilter: `Code = '${EscapeText(code)}'`,
+            MaxRows: 1,
+            ResultType: 'simple',
+        }, contextUser);
+        return res.Success ? (res.Results?.[0]?.ID ?? null) : null;
+    }
+    async findByExternalKey(sourceSystem, externalID, contextUser) {
+        const rv = new RunView();
+        const res = await rv.RunView({
+            EntityName: ACTIVITY_SYNC_ENTITIES.Activities,
+            ExtraFilter: `SourceSystem = '${EscapeText(sourceSystem)}' AND ExternalID = '${EscapeText(externalID)}'`,
+            MaxRows: 1,
+            ResultType: 'simple',
+        }, contextUser);
+        return res.Success ? (res.Results?.[0]?.ID ?? null) : null;
+    }
+}
+//# sourceMappingURL=writer.js.map