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

package/dist/providers/GraphMessageMapper.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Raw Microsoft Graph message JSON → NormalizedItem.
+ *
+ * Maps Graph's own payload, not MJ's Message shape (GetMessages sets To from replyTo[0]).
+ */
+import type { NormalizedItem } from '../types.js';
+export interface GraphEmailAddress {
+    name?: string | null;
+    address?: string | null;
+}
+export interface GraphRecipient {
+    emailAddress?: GraphEmailAddress | null;
+}
+export interface GraphMessage {
+    id?: string | null;
+    conversationId?: string | null;
+    subject?: string | null;
+    bodyPreview?: string | null;
+    body?: {
+        content?: string | null;
+    } | null;
+    sentDateTime?: string | null;
+    receivedDateTime?: string | null;
+    from?: GraphRecipient | null;
+    sender?: GraphRecipient | null;
+    toRecipients?: GraphRecipient[] | null;
+    ccRecipients?: GraphRecipient[] | null;
+    bccRecipients?: GraphRecipient[] | null;
+    [key: string]: unknown;
+}
+export interface MapResult {
+    Items: NormalizedItem[];
+    Issues: string[];
+}
+export declare function MapGraphMessage(message: GraphMessage, mailbox: string, issues: string[]): NormalizedItem | null;
+export declare function MapGraphMessages(payload: unknown, mailbox: string): MapResult;
+//# sourceMappingURL=GraphMessageMapper.d.ts.map

package/dist/providers/GraphMessageMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphMessageMapper.d.ts","sourceRoot":"","sources":["../../src/providers/GraphMessageMapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAsC,cAAc,EAAE,MAAM,aAAa,CAAC;AAEtF,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC3B,YAAY,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACvC,YAAY,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACvC,aAAa,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAuCD,wBAAgB,eAAe,CAC3B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAAE,GACjB,cAAc,GAAG,IAAI,CAsCvB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAkB7E"}

package/dist/providers/GraphMessageMapper.js

@@ -0,0 +1,91 @@
+function isUsableAddress(trimmed) {
+    if (!trimmed)
+        return false;
+    const at = trimmed.indexOf('@');
+    return at > 0 && at < trimmed.length - 1 && !/\s/.test(trimmed);
+}
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function participantFrom(recipient, role, issues, context) {
+    const ea = recipient?.emailAddress ?? null;
+    const raw = (ea?.address ?? '').trim();
+    const name = (ea?.name ?? '').trim() || null;
+    if (!isUsableAddress(raw)) {
+        if (raw) {
+            issues.push(`${context}: ${role} address is not usable and was dropped: ${JSON.stringify(raw)}`);
+        }
+        return null;
+    }
+    return { Address: normalize(raw), Name: name, Role: role, IdentityKind: 'Email' };
+}
+function decideDirection(mailbox, participants) {
+    const box = normalize(mailbox);
+    const from = participants.find((p) => p.Role === 'From');
+    const others = participants.filter((p) => p.Role !== 'From' && p.Address !== box);
+    const sentByMailbox = !!from && from.Address === box;
+    if (sentByMailbox && others.length === 0)
+        return 'Internal';
+    return sentByMailbox ? 'Outbound' : 'Inbound';
+}
+export function MapGraphMessage(message, mailbox, issues) {
+    const id = (message.id ?? '').trim();
+    const context = `message ${id ? id.slice(0, 24) : '(no id)'}`;
+    if (!id) {
+        issues.push('a message arrived with no id and was skipped — it has no dedupe key');
+        return null;
+    }
+    const participants = [];
+    const push = (p) => {
+        if (p)
+            participants.push(p);
+    };
+    push(participantFrom(message.from ?? message.sender, 'From', issues, context));
+    for (const r of message.toRecipients ?? [])
+        push(participantFrom(r, 'To', issues, context));
+    for (const r of message.ccRecipients ?? [])
+        push(participantFrom(r, 'Cc', issues, context));
+    for (const r of message.bccRecipients ?? [])
+        push(participantFrom(r, 'Bcc', issues, context));
+    const stamp = (message.sentDateTime ?? message.receivedDateTime ?? '').trim();
+    const startedAt = stamp ? new Date(stamp) : null;
+    if (!startedAt || Number.isNaN(startedAt.getTime())) {
+        issues.push(`${context}: no usable sentDateTime/receivedDateTime, skipped`);
+        return null;
+    }
+    return {
+        ExternalID: id,
+        ExternalThreadID: (message.conversationId ?? '').trim() || null,
+        TypeCode: 'Email',
+        Subject: (message.subject ?? '').trim() || '(no subject)',
+        Body: (message.bodyPreview ?? message.body?.content ?? '').trim() || null,
+        StartedAt: startedAt,
+        EndedAt: null,
+        Location: null,
+        Direction: decideDirection(mailbox, participants),
+        Participants: participants,
+        Cancelled: false,
+        Raw: message,
+    };
+}
+export function MapGraphMessages(payload, mailbox) {
+    const issues = [];
+    const raw = payload;
+    const list = Array.isArray(raw)
+        ? raw
+        : Array.isArray(raw?.value)
+            ? raw.value
+            : [];
+    if (!list.length) {
+        issues.push('payload contained no messages — expected an array or an object with a `value` array');
+        return { Items: [], Issues: issues };
+    }
+    const items = [];
+    for (const entry of list) {
+        const mapped = MapGraphMessage(entry, mailbox, issues);
+        if (mapped)
+            items.push(mapped);
+    }
+    return { Items: items, Issues: issues };
+}
+//# sourceMappingURL=GraphMessageMapper.js.map

package/dist/providers/GraphMessageMapper.js.map

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

package/dist/providers/MSGraphActivitySyncProvider.d.ts

@@ -0,0 +1,22 @@
+import { BaseActivitySyncProvider } from '../BaseActivitySyncProvider.js';
+import type { ActivitySourceQuery, NormalizedItem, RawBatch } from '../types.js';
+export declare const LIVE_GRAPH_REFUSAL: string;
+export declare class MSGraphActivitySyncProvider extends BaseActivitySyncProvider {
+    /**
+     * Default FALSE. Turning it on is a deliberate act by someone who has confirmed
+     * the Application Access Policy exists. This PR never does that.
+     */
+    private readonly AllowLiveFetch;
+    readonly Kind: "Message";
+    readonly ProviderTypeCode = "Microsoft365";
+    readonly IsLive = true;
+    constructor(
+    /**
+     * Default FALSE. Turning it on is a deliberate act by someone who has confirmed
+     * the Application Access Policy exists. This PR never does that.
+     */
+    AllowLiveFetch?: boolean);
+    protected FetchRaw(query: ActivitySourceQuery): Promise<RawBatch>;
+    protected Normalize(raw: RawBatch, query: ActivitySourceQuery): NormalizedItem[];
+}
+//# sourceMappingURL=MSGraphActivitySyncProvider.d.ts.map

package/dist/providers/MSGraphActivitySyncProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MSGraphActivitySyncProvider.d.ts","sourceRoot":"","sources":["../../src/providers/MSGraphActivitySyncProvider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGjF,eAAO,MAAM,kBAAkB,QAI4B,CAAC;AAE5D,qBACa,2BAA4B,SAAQ,wBAAwB;IAMjE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc;IATnC,SAAgB,IAAI,EAAG,SAAS,CAAU;IAC1C,SAAgB,gBAAgB,kBAAkB;IAClD,SAAgB,MAAM,QAAQ;;IAG1B;;;OAGG;IACc,cAAc,GAAE,OAAe;cAKpC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAcvE,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,mBAAmB,GAAG,cAAc,EAAE;CAOnF"}

package/dist/providers/MSGraphActivitySyncProvider.js

@@ -0,0 +1,62 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * Microsoft Graph mail. Written, typechecked, and refused until an Exchange Application
+ * Access Policy scopes app-only Mail.Read. Fixture is how the engine is exercised.
+ */
+import { LogError } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseActivitySyncProvider } from '../BaseActivitySyncProvider.js';
+import { MapGraphMessages } from './GraphMessageMapper.js';
+export const LIVE_GRAPH_REFUSAL = 'Live Graph fetch is disabled. MSGraphProvider uses app-only auth, so Mail.Read reads ' +
+    'EVERY mailbox in the tenant until an Exchange Application Access Policy scopes the ' +
+    'app registration to a security group. Confirm that policy exists before enabling ' +
+    'this, and use FixtureActivitySyncProvider until then.';
+let MSGraphActivitySyncProvider = class MSGraphActivitySyncProvider extends BaseActivitySyncProvider {
+    constructor(
+    /**
+     * Default FALSE. Turning it on is a deliberate act by someone who has confirmed
+     * the Application Access Policy exists. This PR never does that.
+     */
+    AllowLiveFetch = false) {
+        super();
+        this.AllowLiveFetch = AllowLiveFetch;
+        this.Kind = 'Message';
+        this.ProviderTypeCode = 'Microsoft365';
+        this.IsLive = true;
+    }
+    async FetchRaw(query) {
+        if (!this.AllowLiveFetch) {
+            return { Payloads: [], Issues: [LIVE_GRAPH_REFUSAL] };
+        }
+        LogError(`MSGraphActivitySyncProvider.FetchRaw was enabled for ${query.Mailbox} — not supported in this build.`);
+        return {
+            Payloads: [],
+            Issues: [
+                'Live Graph fetch was opted in but no mailbox transport is wired in this package. ' +
+                    'Keep AllowLiveFetch false and use FixtureActivitySyncProvider.',
+            ],
+        };
+    }
+    Normalize(raw, query) {
+        if (raw.Payloads.length === 0)
+            return [];
+        const mapped = MapGraphMessages(raw.Payloads.length === 1 ? raw.Payloads[0] : raw.Payloads, query.Mailbox);
+        raw.Issues.push(...mapped.Issues);
+        const since = query.Since ? query.Since.getTime() : null;
+        return since === null ? mapped.Items : mapped.Items.filter((i) => i.StartedAt.getTime() > since);
+    }
+};
+MSGraphActivitySyncProvider = __decorate([
+    RegisterClass(BaseActivitySyncProvider, 'Microsoft365'),
+    __metadata("design:paramtypes", [Boolean])
+], MSGraphActivitySyncProvider);
+export { MSGraphActivitySyncProvider };
+//# sourceMappingURL=MSGraphActivitySyncProvider.js.map

package/dist/providers/MSGraphActivitySyncProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MSGraphActivitySyncProvider.js","sourceRoot":"","sources":["../../src/providers/MSGraphActivitySyncProvider.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,CAAC,MAAM,kBAAkB,GAC3B,uFAAuF;IACvF,qFAAqF;IACrF,mFAAmF;IACnF,uDAAuD,CAAC;AAGrD,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,wBAAwB;IAKrE;IACI;;;OAGG;IACc,iBAA0B,KAAK;QAEhD,KAAK,EAAE,CAAC;QAFS,mBAAc,GAAd,cAAc,CAAiB;QATpC,SAAI,GAAG,SAAkB,CAAC;QAC1B,qBAAgB,GAAG,cAAc,CAAC;QAClC,WAAM,GAAG,IAAI,CAAC;IAU9B,CAAC;IAES,KAAK,CAAC,QAAQ,CAAC,KAA0B;QAC/C,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACvB,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC1D,CAAC;QACD,QAAQ,CAAC,wDAAwD,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;QACjH,OAAO;YACH,QAAQ,EAAE,EAAE;YACZ,MAAM,EAAE;gBACJ,mFAAmF;oBAC/E,gEAAgE;aACvE;SACJ,CAAC;IACN,CAAC;IAES,SAAS,CAAC,GAAa,EAAE,KAA0B;QACzD,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3G,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,CAAC;IACrG,CAAC;CACJ,CAAA;AApCY,2BAA2B;IADvC,aAAa,CAAC,wBAAwB,EAAE,cAAc,CAAC;;GAC3C,2BAA2B,CAoCvC"}

package/dist/providers/MSGraphCalendarSyncProvider.d.ts

@@ -0,0 +1,60 @@
+import { BaseActivitySyncProvider } from '../BaseActivitySyncProvider.js';
+import type { ActivitySourceQuery, NormalizedItem, RawBatch } from '../types.js';
+export declare const LIVE_GRAPH_CALENDAR_REFUSAL: string;
+export interface GraphAttendeeLike {
+    type?: string;
+    emailAddress?: {
+        address?: string;
+        name?: string;
+    };
+}
+export interface GraphEventLike {
+    id?: string;
+    iCalUId?: string;
+    subject?: string;
+    bodyPreview?: string;
+    start?: {
+        dateTime?: string;
+        timeZone?: string;
+    };
+    end?: {
+        dateTime?: string;
+        timeZone?: string;
+    };
+    location?: {
+        displayName?: string;
+    };
+    organizer?: {
+        emailAddress?: {
+            address?: string;
+            name?: string;
+        };
+    };
+    attendees?: GraphAttendeeLike[];
+    isCancelled?: boolean;
+    seriesMasterId?: string;
+}
+export interface GraphEventFetcher {
+    GetEvents(params: {
+        Mailbox: string;
+        Since: Date | null;
+        Top: number;
+    }): Promise<{
+        Success?: boolean;
+        ErrorMessage?: string;
+        Events?: GraphEventLike[];
+    }>;
+}
+/** Map one Graph event. Exported so a check can prove the mapping without a mailbox. */
+export declare function MapGraphEvent(event: GraphEventLike, issues: string[]): NormalizedItem | null;
+export declare class MSGraphCalendarSyncProvider extends BaseActivitySyncProvider {
+    private readonly AllowLiveFetch;
+    private readonly fetcher?;
+    readonly Kind: "Calendar";
+    readonly ProviderTypeCode = "Microsoft365";
+    readonly IsLive = true;
+    constructor(AllowLiveFetch?: boolean, fetcher?: GraphEventFetcher | undefined);
+    protected FetchRaw(query: ActivitySourceQuery): Promise<RawBatch>;
+    protected Normalize(raw: RawBatch): NormalizedItem[];
+}
+//# sourceMappingURL=MSGraphCalendarSyncProvider.d.ts.map

package/dist/providers/MSGraphCalendarSyncProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MSGraphCalendarSyncProvider.d.ts","sourceRoot":"","sources":["../../src/providers/MSGraphCalendarSyncProvider.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAmB,cAAc,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAElG,eAAO,MAAM,2BAA2B,QAImC,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACnE,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,MAAM,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC;CACxF;AAiBD,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,IAAI,CAgD5F;AAED,qBACa,2BAA4B,SAAQ,wBAAwB;IAMjE,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAN7B,SAAgB,IAAI,EAAG,UAAU,CAAU;IAC3C,SAAgB,gBAAgB,kBAAkB;IAClD,SAAgB,MAAM,QAAQ;gBAGT,cAAc,GAAE,OAAe,EAC/B,OAAO,CAAC,EAAE,iBAAiB,YAAA;cAKhC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmCvE,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,cAAc,EAAE;CAQvD"}

package/dist/providers/MSGraphCalendarSyncProvider.js

@@ -0,0 +1,145 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/**
+ * Microsoft Graph calendar. Written, typechecked, and refused until an Exchange
+ * Application Access Policy scopes app-only Calendars.Read. Same tenant-wide
+ * grant as Mail.Read; fixture is how the engine is exercised.
+ */
+import { LogError } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { BaseActivitySyncProvider } from '../BaseActivitySyncProvider.js';
+export const LIVE_GRAPH_CALENDAR_REFUSAL = 'Live Graph calendar fetch is disabled. App-only auth makes Calendars.Read tenant-wide, ' +
+    'so it reads EVERY calendar until an Exchange Application Access Policy scopes the app ' +
+    'registration to a security group — the same policy Mail.Read needs. Confirm it exists ' +
+    'before enabling this, and use FixtureActivitySyncProvider until then.';
+function normalize(value) {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed ? trimmed : null;
+}
+function graphDate(slot) {
+    const raw = slot?.dateTime?.trim();
+    if (!raw)
+        return null;
+    const zone = (slot?.timeZone ?? 'UTC').trim().toUpperCase();
+    if (zone !== 'UTC' && !/[Zz]|[+-]\d{2}:?\d{2}$/.test(raw))
+        return null;
+    const stamped = /[Zz]|[+-]\d{2}:?\d{2}$/.test(raw) ? raw : `${raw}Z`;
+    const parsed = new Date(stamped);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/** Map one Graph event. Exported so a check can prove the mapping without a mailbox. */
+export function MapGraphEvent(event, issues) {
+    const externalID = event.id?.trim();
+    if (!externalID) {
+        issues.push('An event carried no id and was skipped — it cannot be deduped.');
+        return null;
+    }
+    const startedAt = graphDate(event.start);
+    if (!startedAt) {
+        issues.push(`Event ${externalID} had no usable start time and was skipped.`);
+        return null;
+    }
+    const participants = [];
+    const organizer = normalize(event.organizer?.emailAddress?.address);
+    if (organizer) {
+        participants.push({
+            Address: organizer,
+            Name: event.organizer?.emailAddress?.name ?? null,
+            Role: 'Organizer',
+            IdentityKind: 'Email',
+        });
+    }
+    for (const attendee of event.attendees ?? []) {
+        const address = normalize(attendee.emailAddress?.address);
+        if (!address || address === organizer)
+            continue;
+        participants.push({
+            Address: address,
+            Name: attendee.emailAddress?.name ?? null,
+            Role: 'Attendee',
+            IdentityKind: 'Email',
+        });
+    }
+    const endedAt = graphDate(event.end);
+    return {
+        ExternalID: externalID,
+        ExternalThreadID: event.seriesMasterId?.trim() || null,
+        TypeCode: 'Meeting',
+        Subject: event.subject?.trim() || '(no subject)',
+        Body: event.bodyPreview ?? null,
+        StartedAt: startedAt,
+        EndedAt: endedAt && endedAt.getTime() >= startedAt.getTime() ? endedAt : null,
+        Location: event.location?.displayName?.trim() || null,
+        Direction: 'Internal',
+        Participants: participants,
+        Cancelled: event.isCancelled === true,
+        Raw: { ...event, iCalUId: event.iCalUId ?? null },
+    };
+}
+let MSGraphCalendarSyncProvider = class MSGraphCalendarSyncProvider extends BaseActivitySyncProvider {
+    constructor(AllowLiveFetch = false, fetcher) {
+        super();
+        this.AllowLiveFetch = AllowLiveFetch;
+        this.fetcher = fetcher;
+        this.Kind = 'Calendar';
+        this.ProviderTypeCode = 'Microsoft365';
+        this.IsLive = true;
+    }
+    async FetchRaw(query) {
+        if (!this.AllowLiveFetch) {
+            return { Payloads: [], Issues: [LIVE_GRAPH_CALENDAR_REFUSAL] };
+        }
+        if (!this.fetcher) {
+            LogError(`MSGraphCalendarSyncProvider.FetchRaw was enabled for ${query.Mailbox} — no transport is wired.`);
+            return {
+                Payloads: [],
+                Issues: [
+                    'Live Graph calendar fetch was opted in but no mailbox transport is wired in this package. ' +
+                        'Keep AllowLiveFetch false and use FixtureActivitySyncProvider.',
+                ],
+            };
+        }
+        try {
+            const response = await this.fetcher.GetEvents({
+                Mailbox: query.Mailbox,
+                Since: query.Since,
+                Top: query.Limit,
+            });
+            if (response?.Success === false) {
+                return {
+                    Payloads: [],
+                    Issues: [`Graph refused the calendar read: ${response.ErrorMessage ?? 'no reason given'}`],
+                };
+            }
+            return {
+                Payloads: (response?.Events ?? []),
+                Issues: [],
+            };
+        }
+        catch (err) {
+            return { Payloads: [], Issues: [`Graph calendar read failed: ${String(err)}`] };
+        }
+    }
+    Normalize(raw) {
+        const items = [];
+        for (const payload of raw.Payloads) {
+            const mapped = MapGraphEvent(payload, raw.Issues);
+            if (mapped)
+                items.push(mapped);
+        }
+        return items;
+    }
+};
+MSGraphCalendarSyncProvider = __decorate([
+    RegisterClass(BaseActivitySyncProvider, 'Microsoft365.Calendar'),
+    __metadata("design:paramtypes", [Boolean, Object])
+], MSGraphCalendarSyncProvider);
+export { MSGraphCalendarSyncProvider };
+//# sourceMappingURL=MSGraphCalendarSyncProvider.js.map

package/dist/providers/MSGraphCalendarSyncProvider.js.map

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

package/dist/qualification.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview The qualification cascade — ordered stages, each deciding or deferring.
+ *
+ * ── THE ORDERING IS A PRIVACY GUARANTEE, SO IT IS ENFORCED, NOT DOCUMENTED ──────────────────────
+ *
+ * A stage that calls a model must never run before the deterministic stages. A message whose
+ * participants match no known contact is discarded having been read only by a string comparison;
+ * putting inference first would send the contents of every message in a mailbox — including the
+ * private ones — to a third party.
+ *
+ * {@link RunQualificationCascade} therefore REJECTS a stage list where a local stage follows an
+ * inference stage, rather than trusting the caller to order it correctly. A comment could be
+ * ignored by the next person to add a stage; a thrown error cannot.
+ *
+ * ── AND ABSTENTION IS FIRST-CLASS ────────────────────────────────────────────────────
+ *
+ * A stage that is not confident returns `Undecided` instead of guessing. When every stage abstains,
+ * the provider type's default policy decides — and for anything mailbox-shaped that default is
+ * `Exclude`. Capturing a private message is worse than missing a business one, so the cascade fails
+ * CLOSED.
+ *
+ * @module @mj-biz-apps/common-activity-sync
+ */
+import { NormalizedItem } from './types.js';
+export type QualificationDecision = 'Include' | 'Exclude' | 'Undecided';
+/** What an `Undecided` chain resolves to. Mirrors `ActivitySyncProviderType.DefaultQualificationPolicy`. */
+export type QualificationPolicy = 'Include' | 'Exclude';
+/**
+ * The cascade's fail-closed default.
+ *
+ * `ActivitySyncProviderTypeID` is nullable, and a host install currently ships
+ * zero provider-type rows until a release-engineer Metadata_Sync. Whatever the
+ * engine passes as `RunQualificationCascade`'s last argument *is* the real
+ * default — `ResolvePolicy`'s first parameter is required, so a missing type
+ * cannot silently fall through.
+ *
+ * Only an explicit `'Include'` on the type row opts in. Null, missing, empty,
+ * or any other value is `'Exclude'`. A `?? 'Include'` at the engine call site
+ * would defeat the cascade while every test still passed.
+ */
+export declare function DefaultPolicyFromProviderType(policy: string | null | undefined): QualificationPolicy;
+/** One stage's answer. `Reason` is always populated — including on `Include`, so a capture is explicable. */
+export interface QualificationVerdict {
+    Decision: QualificationDecision;
+    Reason: string;
+    StageName: string;
+    /** 0–1 where a stage can express one. Absent for deterministic stages, which are certain or abstain. */
+    Confidence?: number;
+    /** Set when the verdict came from an AI Prompt, for trace. */
+    AIPromptRunID?: string;
+    /**
+     * The rule or exclusion that decided, when one did.
+     *
+     * Carried on the verdict rather than reconstructed by the caller, because these are what
+     * `ActivitySyncRunDetail` records — and "which rule ate my message" is the question the run log
+     * exists to answer. A verdict that cannot name its cause makes the log a narrative instead of
+     * evidence.
+     */
+    ActivitySyncRuleID?: string;
+    ActivitySyncExclusionID?: string;
+}
+/** Whatever a stage needs beyond the item itself — known addresses, the connection's rules, and so on. */
+export interface QualificationContext {
+    ConnectionID: string;
+    /** Provider type `Code`, for stages that behave differently per source. */
+    ProviderTypeCode: string;
+}
+export interface IQualificationStage {
+    readonly Name: string;
+    /**
+     * True when this stage sends item content to a model.
+     *
+     * Load-bearing: the cascade uses it to enforce that inference never precedes deterministic work.
+     */
+    readonly RequiresInference: boolean;
+    Evaluate(item: NormalizedItem, context: QualificationContext): Promise<QualificationVerdict>;
+}
+/**
+ * Runs stages in order and returns the first decisive verdict.
+ *
+ * @throws if a non-inference stage follows an inference stage — see the file header.
+ */
+export declare function RunQualificationCascade(stages: readonly IQualificationStage[], item: NormalizedItem, context: QualificationContext, defaultPolicy: QualificationPolicy): Promise<QualificationVerdict>;
+/**
+ * Guards the one ordering that cannot be left to convention.
+ *
+ * Keyed on the CAUSE (an inference stage exists and something local follows it) rather than on a
+ * position or a count, so it still holds when someone adds a fourth stage years from now.
+ */
+export declare function AssertInferenceRunsLast(stages: readonly IQualificationStage[]): void;
+//# sourceMappingURL=qualification.d.ts.map

package/dist/qualification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualification.d.ts","sourceRoot":"","sources":["../src/qualification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAExE,4GAA4G;AAC5G,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,mBAAmB,CAErB;AAED,6GAA6G;AAC7G,MAAM,WAAW,oBAAoB;IACjC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,0GAA0G;AAC1G,MAAM,WAAW,oBAAoB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAChG;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CACzC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,oBAAoB,EAC7B,aAAa,EAAE,mBAAmB,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAU/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAepF"}

package/dist/qualification.js

@@ -0,0 +1,62 @@
+/**
+ * The cascade's fail-closed default.
+ *
+ * `ActivitySyncProviderTypeID` is nullable, and a host install currently ships
+ * zero provider-type rows until a release-engineer Metadata_Sync. Whatever the
+ * engine passes as `RunQualificationCascade`'s last argument *is* the real
+ * default — `ResolvePolicy`'s first parameter is required, so a missing type
+ * cannot silently fall through.
+ *
+ * Only an explicit `'Include'` on the type row opts in. Null, missing, empty,
+ * or any other value is `'Exclude'`. A `?? 'Include'` at the engine call site
+ * would defeat the cascade while every test still passed.
+ */
+export function DefaultPolicyFromProviderType(policy) {
+    return policy === 'Include' ? 'Include' : 'Exclude';
+}
+/**
+ * Runs stages in order and returns the first decisive verdict.
+ *
+ * @throws if a non-inference stage follows an inference stage — see the file header.
+ */
+export async function RunQualificationCascade(stages, item, context, defaultPolicy) {
+    AssertInferenceRunsLast(stages);
+    for (const stage of stages) {
+        const verdict = await stage.Evaluate(item, context);
+        if (verdict.Decision !== 'Undecided') {
+            return verdict;
+        }
+    }
+    return AbstainedVerdict(stages, defaultPolicy);
+}
+/**
+ * Guards the one ordering that cannot be left to convention.
+ *
+ * Keyed on the CAUSE (an inference stage exists and something local follows it) rather than on a
+ * position or a count, so it still holds when someone adds a fourth stage years from now.
+ */
+export function AssertInferenceRunsLast(stages) {
+    let seenInference = null;
+    for (const stage of stages) {
+        if (stage.RequiresInference) {
+            seenInference = stage;
+            continue;
+        }
+        if (seenInference !== null) {
+            throw new Error(`Qualification stage "${stage.Name}" is deterministic but is ordered AFTER the ` +
+                `inference stage "${seenInference.Name}". Inference must run last: a deterministic ` +
+                `stage placed after it would let unfiltered content reach a model first.`);
+        }
+    }
+}
+/** The verdict when every stage abstained. Names the policy so an operator can see why. */
+function AbstainedVerdict(stages, defaultPolicy) {
+    const stageNames = stages.length > 0 ? stages.map((s) => s.Name).join(', ') : '(none)';
+    return {
+        Decision: defaultPolicy,
+        StageName: 'DefaultPolicy',
+        Reason: `No stage reached a decision (${stageNames}); the provider type's ` +
+            `DefaultQualificationPolicy of "${defaultPolicy}" applied.`,
+    };
+}
+//# sourceMappingURL=qualification.js.map

package/dist/qualification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualification.js","sourceRoot":"","sources":["../src/qualification.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,6BAA6B,CACzC,MAAiC;IAEjC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAyCD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CACzC,MAAsC,EACtC,IAAoB,EACpB,OAA6B,EAC7B,aAAkC;IAElC,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAEhC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YACnC,OAAO,OAAO,CAAC;QACnB,CAAC;IACL,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAsC;IAC1E,IAAI,aAAa,GAA+B,IAAI,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC1B,aAAa,GAAG,KAAK,CAAC;YACtB,SAAS;QACb,CAAC;QACD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACX,wBAAwB,KAAK,CAAC,IAAI,8CAA8C;gBAC5E,oBAAoB,aAAa,CAAC,IAAI,8CAA8C;gBACpF,yEAAyE,CAChF,CAAC;QACN,CAAC;IACL,CAAC;AACL,CAAC;AAED,2FAA2F;AAC3F,SAAS,gBAAgB,CACrB,MAAsC,EACtC,aAAkC;IAElC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvF,OAAO;QACH,QAAQ,EAAE,aAAa;QACvB,SAAS,EAAE,eAAe;QAC1B,MAAM,EACF,gCAAgC,UAAU,yBAAyB;YACnE,kCAAkC,aAAa,YAAY;KAClE,CAAC;AACN,CAAC"}