Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -0,0 +1,70 @@
|
||||
// VA-P23 · Gmail integration adapter (catalog presence + health).
|
||||
//
|
||||
// Same shape as adapters/google-calendar.ts: the Apps-Engine catalog needs a
|
||||
// registered adapter per app key (drift-free, registry.test.ts), but the HEAVY
|
||||
// per-USER mailbox sync does NOT run through the generic AppSyncRun path — it
|
||||
// lives in the email-inbox module (apps/web/app/modules/emailInbox) keyed by
|
||||
// EmailIntegrationMailbox, because mailboxes are per-user with read_own
|
||||
// visibility, not per-tenant DataConnections.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GmailError, fetchGmailUserInfo, refreshGmailAccessToken, resolveGmailOAuthConfig } from "../google/gmailApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
|
||||
export interface GmailCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GmailError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
case "quota_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: GmailCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await fetchGmailUserInfo(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const gmailAdapter: IntegrationAdapter<GmailCreds> = registerIntegrationAdapter<GmailCreds>({
|
||||
key: "gmail",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: GmailCreds): Promise<AdapterTokenRefresh<GmailCreds>> => {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GmailError("not_configured");
|
||||
}
|
||||
const next = await refreshGmailAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync;
|
||||
// the generic engine sync is a no-op that reports this in Klartext.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
// AK-P16a · Google Calendar integration adapter (catalog presence + health).
|
||||
//
|
||||
// The Apps-Engine catalog needs a registered adapter per app key (drift-free,
|
||||
// registry.test.ts). The HEAVY per-USER bidirectional sync does NOT run through
|
||||
// the generic AppSyncRun path — it lives in the calendar module
|
||||
// (apps/web/app/modules/calendar) keyed by CalendarConnection, because calendar
|
||||
// connections are per-user with leak-protection, not per-tenant DataConnections.
|
||||
//
|
||||
// So this adapter is intentionally thin: it satisfies the contract for catalog
|
||||
// reachability + lets the platform-admin health surface probe a token, and
|
||||
// implements OAuth refresh by delegating to googleCalendarApi. `sync()` reports a
|
||||
// Klartext summary that the per-user engine owns the actual event sync.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GoogleCalendarError, listCalendars, refreshAccessToken, resolveGoogleOAuthConfig } from "../google/googleCalendarApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per CalendarConnection. */
|
||||
export interface GoogleCalendarCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GoogleCalendarError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "calendar.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "calendar.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: GoogleCalendarCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await listCalendars(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "calendar.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const googleCalendarAdapter: IntegrationAdapter<GoogleCalendarCreds> = registerIntegrationAdapter<GoogleCalendarCreds>({
|
||||
key: "google-calendar",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: GoogleCalendarCreds): Promise<AdapterTokenRefresh<GoogleCalendarCreds>> => {
|
||||
const config = resolveGoogleOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GoogleCalendarError("not_configured");
|
||||
}
|
||||
const next = await refreshAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user calendar engine (webhook + cron driven) owns event sync; the
|
||||
// generic engine sync is a no-op that reports this in Klartext.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "calendar.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
// VA-P23 · Microsoft (Outlook/Graph) mail integration adapter (catalog presence
|
||||
// + health). Thin like adapters/gmail.ts — the per-user sync engine lives in the
|
||||
// email-inbox module, this satisfies the catalog/registry drift contract.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GraphMailError, fetchGraphUserProfile, refreshMicrosoftAccessToken, resolveMicrosoftMailOAuthConfig } from "../microsoft/graphMailApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
|
||||
export interface MicrosoftMailCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GraphMailError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: MicrosoftMailCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await fetchGraphUserProfile(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const microsoftMailAdapter: IntegrationAdapter<MicrosoftMailCreds> = registerIntegrationAdapter<MicrosoftMailCreds>({
|
||||
key: "microsoft-mail",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: MicrosoftMailCreds): Promise<AdapterTokenRefresh<MicrosoftMailCreds>> => {
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GraphMailError("not_configured");
|
||||
}
|
||||
const next = await refreshMicrosoftAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
import { createHmac } from "node:crypto";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { buildPandaDocAuthHeader, pandaDocByokAdapter, verifyPandaDocWebhookSignature } from "./pandadoc-byok.js";
|
||||
|
||||
describe("PandaDoc BYOK adapter", () => {
|
||||
it("uses the API-Key auth header confirmed by EXT-17", () => {
|
||||
expect(buildPandaDocAuthHeader("secret")).toBe("API-Key secret");
|
||||
});
|
||||
|
||||
it("validates required BYOK credentials", async () => {
|
||||
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k", templateUuid: "tpl" })).resolves.toMatchObject({ ok: true });
|
||||
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k" })).resolves.toMatchObject({ ok: false, health: "broken" });
|
||||
});
|
||||
|
||||
it("verifies HMAC SHA-256 webhooks over the raw body", () => {
|
||||
const rawBody = JSON.stringify({ event: "document.completed", data: { id: "pd-1" } });
|
||||
const signature = createHmac("sha256", "shared").update(rawBody).digest("hex");
|
||||
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, signature, "shared")).toBe(true);
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, `sha256=${signature}`, "shared")).toBe(true);
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, signature, "other")).toBe(false);
|
||||
});
|
||||
});
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
// AK-P16d · optional PandaDoc BYOK adapter.
|
||||
//
|
||||
// Plane/EXT-17 confirmed the implementation details used here:
|
||||
// Authorization: API-Key <key>, template-driven documents, and webhook HMAC
|
||||
// SHA-256 over the raw request body with the signature supplied by PandaDoc.
|
||||
|
||||
import { createHmac, timingSafeEqual } from "node:crypto";
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
export interface PandaDocByokCreds {
|
||||
readonly apiKey?: string | null;
|
||||
readonly templateUuid?: string | null;
|
||||
readonly webhookSharedKey?: string | null;
|
||||
}
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
const MISSING: AdapterResult = { ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" };
|
||||
|
||||
function validate(creds: PandaDocByokCreds): Promise<AdapterResult> {
|
||||
if (!creds.apiKey || !creds.templateUuid) {
|
||||
return Promise.resolve(MISSING);
|
||||
}
|
||||
return Promise.resolve(ACTIVE);
|
||||
}
|
||||
|
||||
function normalizeSignature(signature: string): string {
|
||||
return signature.startsWith("sha256=") ? signature.slice("sha256=".length) : signature;
|
||||
}
|
||||
|
||||
export function buildPandaDocAuthHeader(apiKey: string): string {
|
||||
return `API-Key ${apiKey}`;
|
||||
}
|
||||
|
||||
export function verifyPandaDocWebhookSignature(rawBody: string | Buffer, signature: string | null | undefined, sharedKey: string | null | undefined): boolean {
|
||||
if (!signature || !sharedKey) return false;
|
||||
const expected = createHmac("sha256", sharedKey).update(rawBody).digest("hex");
|
||||
const received = normalizeSignature(signature);
|
||||
const expectedBuffer = Buffer.from(expected, "hex");
|
||||
const receivedBuffer = Buffer.from(received, "hex");
|
||||
if (expectedBuffer.length !== receivedBuffer.length) return false;
|
||||
return timingSafeEqual(expectedBuffer, receivedBuffer);
|
||||
}
|
||||
|
||||
export const pandaDocByokAdapter: IntegrationAdapter<PandaDocByokCreds> = registerIntegrationAdapter<PandaDocByokCreds>({
|
||||
key: "pandadoc-byok",
|
||||
connectionType: "api_key",
|
||||
validateConnection: validate,
|
||||
healthCheck: validate,
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [],
|
||||
summaryKey: "integrations.sync.summary.noop",
|
||||
}),
|
||||
});
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
// R-P5 (P5) — reference integration adapter (the only adapter shipped in v1).
|
||||
//
|
||||
// Demonstrates the IntegrationAdapter contract end-to-end (validate / health /
|
||||
// sync) without any external provider. Concrete adapters (Gmail/AirCall/Mollie)
|
||||
// follow this shape in their module phases. Registers itself on import (the
|
||||
// registry barrel imports this for its side effect).
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
type SampleCreds = { baseUrl: string; apiKey: string };
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
|
||||
function validate(creds: SampleCreds): Promise<AdapterResult> {
|
||||
if (!creds.baseUrl || !creds.apiKey) {
|
||||
return Promise.resolve({ ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" });
|
||||
}
|
||||
return Promise.resolve(ACTIVE);
|
||||
}
|
||||
|
||||
export const sampleDataSyncAdapter: IntegrationAdapter<SampleCreds> = registerIntegrationAdapter<SampleCreds>({
|
||||
key: "sample-data-sync",
|
||||
connectionType: "rest_api",
|
||||
validateConnection: validate,
|
||||
healthCheck: validate,
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [
|
||||
{ entityType: "contact", externalId: "ext-1", operation: "created", status: "synced" },
|
||||
{ entityType: "contact", externalId: "ext-2", operation: "updated", status: "synced" },
|
||||
],
|
||||
summaryKey: "integrations.sync.summary.ok",
|
||||
}),
|
||||
});
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
// AK-P16d · AD-25 default signature adapter.
|
||||
//
|
||||
// The hardened SES implementation is local to HiveGrid (touch signature,
|
||||
// one-time links, email OTP, audit events, sealed PDF + completion certificate).
|
||||
// This adapter exists so the Apps-Engine catalog/registry can expose and monitor
|
||||
// the capability without requiring provider credentials.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
type SesSelfhostedCreds = Record<string, never>;
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
|
||||
export const sesSelfhostedAdapter: IntegrationAdapter<SesSelfhostedCreds> = registerIntegrationAdapter<SesSelfhostedCreds>({
|
||||
key: "ses-selfhosted",
|
||||
connectionType: "rest_api",
|
||||
validateConnection: () => Promise.resolve(ACTIVE),
|
||||
healthCheck: () => Promise.resolve(ACTIVE),
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [],
|
||||
summaryKey: "integrations.sync.summary.noop",
|
||||
}),
|
||||
});
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { decideWebhookRenewal, DEFAULT_RENEWAL_THRESHOLD_MS } from "./calendar-webhook-renewal.js";
|
||||
|
||||
const now = new Date("2026-07-01T12:00:00Z");
|
||||
|
||||
describe("decideWebhookRenewal", () => {
|
||||
it("renews when there is no subscription yet", () => {
|
||||
expect(decideWebhookRenewal({ expiresAt: null, now })).toEqual({ shouldRenew: true, reason: "no_subscription" });
|
||||
});
|
||||
|
||||
it("renews when expiring within the threshold", () => {
|
||||
const expiresAt = new Date(now.getTime() + DEFAULT_RENEWAL_THRESHOLD_MS - 60_000);
|
||||
expect(decideWebhookRenewal({ expiresAt, now })).toEqual({ shouldRenew: true, reason: "expiring_soon" });
|
||||
});
|
||||
|
||||
it("renews exactly at the threshold boundary", () => {
|
||||
const expiresAt = new Date(now.getTime() + DEFAULT_RENEWAL_THRESHOLD_MS);
|
||||
expect(decideWebhookRenewal({ expiresAt, now }).shouldRenew).toBe(true);
|
||||
});
|
||||
|
||||
it("leaves a still-valid subscription alone", () => {
|
||||
const expiresAt = new Date(now.getTime() + DEFAULT_RENEWAL_THRESHOLD_MS + 60 * 60_000);
|
||||
expect(decideWebhookRenewal({ expiresAt, now })).toEqual({ shouldRenew: false, reason: "still_valid" });
|
||||
});
|
||||
|
||||
it("honours a custom threshold", () => {
|
||||
const expiresAt = new Date(now.getTime() + 2 * 60 * 60_000); // 2h left
|
||||
expect(decideWebhookRenewal({ expiresAt, now, thresholdMs: 60 * 60_000 }).shouldRenew).toBe(false);
|
||||
expect(decideWebhookRenewal({ expiresAt, now, thresholdMs: 3 * 60 * 60_000 }).shouldRenew).toBe(true);
|
||||
});
|
||||
});
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
// AK-P16a · webhook-subscription renewal decision (PURE) — M25 Block E.
|
||||
//
|
||||
// Google Calendar push channels expire (~1 week). A worker cron renews channels
|
||||
// that will lapse soon, BEFORE they go silent. This module holds only the pure
|
||||
// decision (no DB/network) so the cron stays thin and the timing is unit-tested.
|
||||
// The renewal threshold (default 24h) gives ample margin against the cron cadence.
|
||||
|
||||
export const DEFAULT_RENEWAL_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
|
||||
|
||||
export interface WebhookRenewalInput {
|
||||
/** Current provider channel expiry (null = no active subscription). */
|
||||
readonly expiresAt: Date | null;
|
||||
readonly now: Date;
|
||||
readonly thresholdMs?: number;
|
||||
}
|
||||
|
||||
export interface WebhookRenewalDecision {
|
||||
readonly shouldRenew: boolean;
|
||||
/** Stable reason code (also a Klartext i18n suffix). */
|
||||
readonly reason: "no_subscription" | "expiring_soon" | "still_valid";
|
||||
}
|
||||
|
||||
/**
|
||||
* Decide whether a connection's push channel needs renewal now. Renew when there
|
||||
* is no subscription yet, or it expires within `thresholdMs`.
|
||||
*/
|
||||
export function decideWebhookRenewal(input: WebhookRenewalInput): WebhookRenewalDecision {
|
||||
if (input.expiresAt === null) {
|
||||
return { shouldRenew: true, reason: "no_subscription" };
|
||||
}
|
||||
const threshold = input.thresholdMs ?? DEFAULT_RENEWAL_THRESHOLD_MS;
|
||||
const msLeft = input.expiresAt.getTime() - input.now.getTime();
|
||||
if (msLeft <= threshold) {
|
||||
return { shouldRenew: true, reason: "expiring_soon" };
|
||||
}
|
||||
return { shouldRenew: false, reason: "still_valid" };
|
||||
}
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { syncInternalCalendarEventsForTenant, type CalendarWorkerClient } from "./calendar-worker-tasks.server.js";
|
||||
|
||||
const mocks = vi.hoisted(() => {
|
||||
class MockGoogleCalendarError extends Error {
|
||||
readonly code: string;
|
||||
readonly httpStatus?: number;
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: string, httpStatus?: number) {
|
||||
super(code);
|
||||
this.name = "GoogleCalendarError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
this.fullResyncRequired = httpStatus === 410;
|
||||
}
|
||||
}
|
||||
return {
|
||||
MockGoogleCalendarError,
|
||||
createNotificationDelivery: vi.fn(async () => ({})),
|
||||
insertEvent: vi.fn(),
|
||||
patchEvent: vi.fn(),
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock("./google/googleCalendarApi.js", () => ({
|
||||
deleteEvent: vi.fn(async () => undefined),
|
||||
GoogleCalendarError: mocks.MockGoogleCalendarError,
|
||||
insertEvent: mocks.insertEvent,
|
||||
listEvents: vi.fn(),
|
||||
patchEvent: mocks.patchEvent,
|
||||
refreshAccessToken: vi.fn(),
|
||||
resolveGoogleOAuthConfig: vi.fn(() => ({ clientId: "id", clientSecret: "secret", redirectUri: "https://app.example.test/callback" })),
|
||||
watchCalendar: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/crypto/tenant-envelope.server", () => ({
|
||||
decryptTenantField: vi.fn(async (_tenantId: string, ciphertext: string) => (ciphertext.includes("refresh") ? "refresh-token" : "access-token")),
|
||||
encryptTenantField: vi.fn(async (_tenantId: string, value: string) => `sealed:${value}`),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/notifications.server", () => ({
|
||||
createNotificationDelivery: mocks.createNotificationDelivery,
|
||||
}));
|
||||
|
||||
function createClient(options: { mapping?: Record<string, unknown> | null; patchConflict?: boolean } = {}) {
|
||||
const now = new Date("2026-06-30T10:00:00.000Z");
|
||||
const connection = {
|
||||
id: "conn_1",
|
||||
tenantId: "tenant_1",
|
||||
userId: "user_1",
|
||||
oauthRefreshTokenCiphertext: "sealed-refresh",
|
||||
oauthAccessTokenCiphertext: "sealed-access",
|
||||
oauthAccessTokenExpiresAt: new Date("2026-06-30T11:00:00.000Z"),
|
||||
webhookSubscriptionId: null,
|
||||
webhookSubscriptionExpiresAt: null,
|
||||
syncDirection: "bidirectional" as const,
|
||||
status: "active" as const,
|
||||
};
|
||||
const event = {
|
||||
id: "event_1",
|
||||
updatedAt: now,
|
||||
tenantId: "tenant_1",
|
||||
userId: "user_1",
|
||||
title: "Kundentermin",
|
||||
description: null,
|
||||
location: null,
|
||||
startsAt: new Date("2026-07-01T08:00:00.000Z"),
|
||||
endsAt: new Date("2026-07-01T09:00:00.000Z"),
|
||||
isAllDay: false,
|
||||
timeZone: "Europe/Berlin",
|
||||
attendees: [],
|
||||
versionToken: 1,
|
||||
archivedAt: null,
|
||||
};
|
||||
const mapping = options.mapping ?? null;
|
||||
const client = {
|
||||
calendarConnection: {
|
||||
findMany: vi.fn(async () => [connection]),
|
||||
findFirst: vi.fn(async () => connection),
|
||||
updateMany: vi.fn(async () => ({ count: 1 })),
|
||||
update: vi.fn(async () => ({})),
|
||||
},
|
||||
calendarEvent: {
|
||||
findMany: vi.fn(async () => [event]),
|
||||
upsert: vi.fn(async () => ({})),
|
||||
},
|
||||
calendarEventMapping: {
|
||||
findFirst: vi.fn(async () => mapping),
|
||||
create: vi.fn(async ({ data }) => ({ id: "mapping_1", ...data })),
|
||||
update: vi.fn(async ({ data }) => ({ id: "mapping_1", ...data })),
|
||||
deleteMany: vi.fn(async () => ({ count: 1 })),
|
||||
},
|
||||
calendarSyncCursor: {
|
||||
findFirst: vi.fn(async () => null),
|
||||
upsert: vi.fn(async () => ({})),
|
||||
updateMany: vi.fn(async () => ({ count: 1 })),
|
||||
},
|
||||
calendarWebhookEvent: {
|
||||
findMany: vi.fn(async () => []),
|
||||
updateMany: vi.fn(async () => ({ count: 1 })),
|
||||
update: vi.fn(async () => ({})),
|
||||
},
|
||||
calendarConflict: {
|
||||
create: vi.fn(async () => ({})),
|
||||
},
|
||||
};
|
||||
|
||||
if (options.patchConflict) {
|
||||
mocks.patchEvent.mockRejectedValueOnce(new mocks.MockGoogleCalendarError("rate_limit_exceeded", 412));
|
||||
}
|
||||
return client as unknown as CalendarWorkerClient & typeof client;
|
||||
}
|
||||
|
||||
describe("calendar worker write sync", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.insertEvent.mockResolvedValue({ id: "google_event_1", etag: "etag_1" });
|
||||
mocks.patchEvent.mockResolvedValue({ id: "google_event_1", etag: "etag_2" });
|
||||
});
|
||||
|
||||
it("creates an external event and mapping for a new HiveGrid event", async () => {
|
||||
const client = createClient();
|
||||
|
||||
const result = await syncInternalCalendarEventsForTenant(client, "tenant_1", { now: new Date("2026-06-30T10:00:00.000Z") });
|
||||
|
||||
expect(result).toMatchObject({ scanned: 1, created: 1, updated: 0, conflicts: 0, failed: 0 });
|
||||
expect(mocks.insertEvent).toHaveBeenCalledWith("access-token", "primary", expect.objectContaining({ summary: "Kundentermin" }));
|
||||
expect(client.calendarEventMapping.create).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
internalEventId: "event_1",
|
||||
externalEventId: "google_event_1",
|
||||
lastKnownExternalEtag: "etag_1",
|
||||
lastKnownInternalVersionToken: 1,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it("logs and notifies a Last-Write-Wins conflict on provider etag mismatch", async () => {
|
||||
const client = createClient({
|
||||
mapping: {
|
||||
id: "mapping_1",
|
||||
internalEventId: "event_1",
|
||||
externalEventId: "google_event_1",
|
||||
externalCalendarId: "primary",
|
||||
connectionId: "conn_1",
|
||||
lastSyncedAt: new Date("2026-06-30T09:00:00.000Z"),
|
||||
lastKnownExternalEtag: "old-etag",
|
||||
lastKnownInternalVersionToken: 0,
|
||||
},
|
||||
patchConflict: true,
|
||||
});
|
||||
|
||||
const result = await syncInternalCalendarEventsForTenant(client, "tenant_1", { now: new Date("2026-06-30T10:00:00.000Z") });
|
||||
|
||||
expect(result).toMatchObject({ scanned: 1, created: 0, updated: 0, conflicts: 1, failed: 0 });
|
||||
expect(client.calendarConflict.create).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
connectionId: "conn_1",
|
||||
internalEventId: "event_1",
|
||||
externalEventId: "google_event_1",
|
||||
resolution: "external_won",
|
||||
descriptionText: "calendar.conflict.externalWon",
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(mocks.createNotificationDelivery).toHaveBeenCalledWith(expect.objectContaining({ userId: "user_1", messageKey: "calendar.conflict.externalWon" }));
|
||||
});
|
||||
});
|
||||
+580
@@ -0,0 +1,580 @@
|
||||
// AK-P16a (P16) calendar worker tasks. Shared by apps/worker so the background
|
||||
// engine can run without importing apps/web modules.
|
||||
|
||||
import { decryptTenantField, encryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
|
||||
import { createNotificationDelivery } from "@hivegrid/db/notifications.server";
|
||||
import {
|
||||
deleteEvent,
|
||||
GoogleCalendarError,
|
||||
insertEvent,
|
||||
listEvents,
|
||||
patchEvent as googlePatchEvent,
|
||||
refreshAccessToken,
|
||||
resolveGoogleOAuthConfig,
|
||||
watchCalendar,
|
||||
type GoogleEvent,
|
||||
type GoogleEventInput,
|
||||
} from "./google/googleCalendarApi.js";
|
||||
import { decideWebhookRenewal } from "./calendar-webhook-renewal.js";
|
||||
|
||||
const PRIMARY_CALENDAR = "primary";
|
||||
const WINDOW_PAST_DAYS = 7;
|
||||
const WINDOW_FUTURE_DAYS = 60;
|
||||
const DEFAULT_TAKE = 50;
|
||||
|
||||
type CalendarConnectionRow = {
|
||||
id: string;
|
||||
tenantId: string;
|
||||
userId: string;
|
||||
oauthRefreshTokenCiphertext: string | null;
|
||||
oauthAccessTokenCiphertext: string | null;
|
||||
oauthAccessTokenExpiresAt: Date | null;
|
||||
webhookSubscriptionId: string | null;
|
||||
webhookSubscriptionExpiresAt: Date | null;
|
||||
syncDirection: "bidirectional" | "hivegrid_to_external_only" | "external_to_hivegrid_only";
|
||||
status: "active" | "paused" | "error" | "revoked";
|
||||
};
|
||||
|
||||
type CalendarEventRow = {
|
||||
id: string;
|
||||
updatedAt: Date;
|
||||
tenantId: string;
|
||||
userId: string;
|
||||
title: string | null;
|
||||
description: string | null;
|
||||
location: string | null;
|
||||
startsAt: Date;
|
||||
endsAt: Date;
|
||||
isAllDay: boolean;
|
||||
timeZone: string | null;
|
||||
attendees: unknown;
|
||||
versionToken: number;
|
||||
archivedAt: Date | null;
|
||||
};
|
||||
|
||||
type CalendarEventMappingRow = {
|
||||
id: string;
|
||||
internalEventId: string;
|
||||
externalEventId: string;
|
||||
externalCalendarId: string;
|
||||
connectionId: string;
|
||||
lastSyncedAt: Date | null;
|
||||
lastKnownExternalEtag: string | null;
|
||||
lastKnownInternalVersionToken: number | null;
|
||||
};
|
||||
|
||||
type CalendarWebhookEventRow = {
|
||||
id: string;
|
||||
tenantId: string;
|
||||
connectionId: string;
|
||||
};
|
||||
|
||||
type CalendarSyncCursorRow = {
|
||||
cursorToken: string | null;
|
||||
};
|
||||
|
||||
export type CalendarWorkerClient = {
|
||||
calendarConnection: {
|
||||
findMany(args: Record<string, unknown>): Promise<CalendarConnectionRow[]>;
|
||||
findFirst(args: Record<string, unknown>): Promise<CalendarConnectionRow | null>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
update(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
calendarEvent: {
|
||||
findMany(args: Record<string, unknown>): Promise<CalendarEventRow[]>;
|
||||
upsert(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
calendarEventMapping: {
|
||||
findFirst(args: Record<string, unknown>): Promise<CalendarEventMappingRow | null>;
|
||||
create(args: Record<string, unknown>): Promise<CalendarEventMappingRow>;
|
||||
update(args: Record<string, unknown>): Promise<CalendarEventMappingRow>;
|
||||
deleteMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
};
|
||||
calendarSyncCursor: {
|
||||
findFirst(args: Record<string, unknown>): Promise<CalendarSyncCursorRow | null>;
|
||||
upsert(args: Record<string, unknown>): Promise<unknown>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
};
|
||||
calendarWebhookEvent: {
|
||||
findMany(args: Record<string, unknown>): Promise<CalendarWebhookEventRow[]>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
update(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
calendarConflict: {
|
||||
create(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
};
|
||||
|
||||
type CalendarCreds = {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt: Date | null;
|
||||
};
|
||||
|
||||
async function loadCreds(client: CalendarWorkerClient, tenantId: string, connectionId: string): Promise<CalendarCreds | null> {
|
||||
const row = await client.calendarConnection.findFirst({
|
||||
where: { id: connectionId, tenantId, archivedAt: null },
|
||||
select: { id: true, tenantId: true, userId: true, oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true, webhookSubscriptionId: true, webhookSubscriptionExpiresAt: true, syncDirection: true, status: true },
|
||||
});
|
||||
if (!row?.oauthRefreshTokenCiphertext || !row.oauthAccessTokenCiphertext) {
|
||||
return null;
|
||||
}
|
||||
const [refreshToken, accessToken] = await Promise.all([
|
||||
decryptTenantField(tenantId, row.oauthRefreshTokenCiphertext, { client: client as never }),
|
||||
decryptTenantField(tenantId, row.oauthAccessTokenCiphertext, { client: client as never }),
|
||||
]);
|
||||
return { refreshToken, accessToken, expiresAt: row.oauthAccessTokenExpiresAt };
|
||||
}
|
||||
|
||||
async function ensureFreshCreds(client: CalendarWorkerClient, tenantId: string, connectionId: string, creds: CalendarCreds, now = new Date()): Promise<CalendarCreds> {
|
||||
if (creds.expiresAt && creds.expiresAt.getTime() > now.getTime() + 60_000) {
|
||||
return creds;
|
||||
}
|
||||
const config = resolveGoogleOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GoogleCalendarError("not_configured");
|
||||
}
|
||||
const refreshed = await refreshAccessToken(config, creds.refreshToken);
|
||||
const [accessCiphertext, refreshCiphertext] = await Promise.all([
|
||||
encryptTenantField(tenantId, refreshed.accessToken, { client: client as never }),
|
||||
encryptTenantField(tenantId, refreshed.refreshToken ?? creds.refreshToken, { client: client as never }),
|
||||
]);
|
||||
await client.calendarConnection.updateMany({
|
||||
where: { id: connectionId, tenantId },
|
||||
data: {
|
||||
oauthAccessTokenCiphertext: accessCiphertext,
|
||||
oauthRefreshTokenCiphertext: refreshCiphertext,
|
||||
oauthAccessTokenExpiresAt: refreshed.expiresAt,
|
||||
status: "active",
|
||||
lastErrorText: null,
|
||||
},
|
||||
});
|
||||
return { accessToken: refreshed.accessToken, refreshToken: refreshed.refreshToken ?? creds.refreshToken, expiresAt: refreshed.expiresAt };
|
||||
}
|
||||
|
||||
function toGoogleInput(event: CalendarEventRow): GoogleEventInput {
|
||||
const tz = event.timeZone ?? "UTC";
|
||||
const boundary = (date: Date): GoogleEventInput["start"] =>
|
||||
event.isAllDay ? { date: date.toISOString().slice(0, 10) } : { dateTime: date.toISOString(), timeZone: tz };
|
||||
return {
|
||||
summary: event.title ?? "HiveGrid Termin",
|
||||
description: event.description ?? undefined,
|
||||
location: event.location ?? undefined,
|
||||
start: boundary(event.startsAt),
|
||||
end: boundary(event.endsAt),
|
||||
attendees: toAttendees(event.attendees),
|
||||
};
|
||||
}
|
||||
|
||||
function toAttendees(value: unknown): Array<{ email: string }> | undefined {
|
||||
if (!Array.isArray(value)) {
|
||||
return undefined;
|
||||
}
|
||||
const attendees = value
|
||||
.map((item) => (item && typeof item === "object" && "email" in item ? String((item as { email?: unknown }).email ?? "") : ""))
|
||||
.filter((email) => email.includes("@"))
|
||||
.map((email) => ({ email }));
|
||||
return attendees.length > 0 ? attendees : undefined;
|
||||
}
|
||||
|
||||
function toExternalEventFields(event: GoogleEvent, ctx: { tenantId: string; userId: string; connectionId: string }, now: Date) {
|
||||
const start = parseBoundary(event.start);
|
||||
const end = parseBoundary(event.end);
|
||||
const cancelled = event.status === "cancelled";
|
||||
return {
|
||||
tenantId: ctx.tenantId,
|
||||
userId: ctx.userId,
|
||||
connectionId: ctx.connectionId,
|
||||
source: "external_synced",
|
||||
provider: "google",
|
||||
externalEventId: event.id,
|
||||
externalCalendarId: PRIMARY_CALENDAR,
|
||||
title: event.summary ?? null,
|
||||
description: event.description ?? null,
|
||||
location: event.location ?? null,
|
||||
startsAt: start.at,
|
||||
endsAt: end.at,
|
||||
isAllDay: start.isAllDay || end.isAllDay,
|
||||
timeZone: event.start?.timeZone ?? null,
|
||||
recurrenceRule: event.recurrence && event.recurrence.length > 0 ? event.recurrence[0] : null,
|
||||
attendees: (event.attendees ?? []).map((a) => ({ email: a.email ?? "", status: a.responseStatus ?? null })),
|
||||
etag: event.etag ?? null,
|
||||
lastModifiedExternal: event.updated ? new Date(event.updated) : null,
|
||||
isBusyForAvailability: cancelled ? false : event.transparency !== "transparent",
|
||||
archivedAt: cancelled ? now : null,
|
||||
};
|
||||
}
|
||||
|
||||
function parseBoundary(value: { dateTime?: string; date?: string } | undefined): { at: Date; isAllDay: boolean } {
|
||||
if (value?.dateTime) {
|
||||
return { at: new Date(value.dateTime), isAllDay: false };
|
||||
}
|
||||
if (value?.date) {
|
||||
return { at: new Date(`${value.date}T00:00:00.000Z`), isAllDay: true };
|
||||
}
|
||||
return { at: new Date(0), isAllDay: false };
|
||||
}
|
||||
|
||||
async function notifyOwner(tenantId: string, userId: string, messageKey: string, metadata: Record<string, string | number | null>): Promise<void> {
|
||||
await createNotificationDelivery({
|
||||
tenantId,
|
||||
userId,
|
||||
channel: "in-app",
|
||||
category: "calendar",
|
||||
messageKey,
|
||||
status: "PENDING",
|
||||
sourceKey: `${messageKey}:${metadata.connectionId ?? ""}:${metadata.eventId ?? ""}:${metadata.externalEventId ?? ""}`,
|
||||
payloadMetadata: metadata,
|
||||
}).catch(() => undefined);
|
||||
}
|
||||
|
||||
async function persistConflict(
|
||||
client: CalendarWorkerClient,
|
||||
input: {
|
||||
tenantId: string;
|
||||
connectionId: string;
|
||||
userId: string;
|
||||
internalEventId?: string | null;
|
||||
externalEventId?: string | null;
|
||||
resolution: "external_won" | "hivegrid_won" | "external_deleted" | "hivegrid_deleted";
|
||||
descriptionText: string;
|
||||
},
|
||||
): Promise<void> {
|
||||
await client.calendarConflict.create({
|
||||
data: {
|
||||
tenantId: input.tenantId,
|
||||
connectionId: input.connectionId,
|
||||
userId: input.userId,
|
||||
internalEventId: input.internalEventId ?? null,
|
||||
externalEventId: input.externalEventId ?? null,
|
||||
resolution: input.resolution,
|
||||
descriptionText: input.descriptionText,
|
||||
},
|
||||
});
|
||||
await notifyOwner(input.tenantId, input.userId, input.descriptionText, {
|
||||
connectionId: input.connectionId,
|
||||
eventId: input.internalEventId ?? null,
|
||||
externalEventId: input.externalEventId ?? null,
|
||||
});
|
||||
}
|
||||
|
||||
export async function refreshCalendarTokensForTenant(
|
||||
client: CalendarWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; windowMs?: number } = {},
|
||||
): Promise<{ refreshed: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const horizon = new Date(now.getTime() + (opts.windowMs ?? 10 * 60_000));
|
||||
const rows = await client.calendarConnection.findMany({
|
||||
where: { tenantId, archivedAt: null, status: { in: ["active", "error"] }, oauthAccessTokenExpiresAt: { not: null, lte: horizon } },
|
||||
select: { id: true, tenantId: true, userId: true, oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true, webhookSubscriptionId: true, webhookSubscriptionExpiresAt: true, syncDirection: true, status: true },
|
||||
});
|
||||
|
||||
let refreshed = 0;
|
||||
let failed = 0;
|
||||
for (const row of rows) {
|
||||
const creds = await loadCreds(client, tenantId, row.id);
|
||||
if (!creds) {
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
await ensureFreshCreds(client, tenantId, row.id, creds, now);
|
||||
refreshed += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.calendarConnection.updateMany({ where: { id: row.id, tenantId }, data: { status: "error", lastErrorText: "calendar.health.tokenExpired" } });
|
||||
await notifyOwner(tenantId, row.userId, "calendar.health.tokenExpired", { connectionId: row.id, eventId: null, externalEventId: null });
|
||||
}
|
||||
}
|
||||
return { refreshed, failed };
|
||||
}
|
||||
|
||||
export async function renewCalendarWebhooksForTenant(
|
||||
client: CalendarWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; thresholdMs?: number; webhookUrl?: string } = {},
|
||||
): Promise<{ checked: number; renewed: number; failed: number; skipped: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const webhookUrl = opts.webhookUrl;
|
||||
const rows = await client.calendarConnection.findMany({
|
||||
where: { tenantId, archivedAt: null, status: "active" },
|
||||
select: { id: true, tenantId: true, userId: true, oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true, webhookSubscriptionId: true, webhookSubscriptionExpiresAt: true, syncDirection: true, status: true },
|
||||
});
|
||||
|
||||
let renewed = 0;
|
||||
let failed = 0;
|
||||
let skipped = 0;
|
||||
for (const row of rows) {
|
||||
const decision = decideWebhookRenewal({ expiresAt: row.webhookSubscriptionExpiresAt, now, thresholdMs: opts.thresholdMs });
|
||||
if (!decision.shouldRenew) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
if (!webhookUrl) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, row.id);
|
||||
if (!baseCreds) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
const creds = await ensureFreshCreds(client, tenantId, row.id, baseCreds, now);
|
||||
const channelId = `cal_${row.id}_${now.getTime()}`;
|
||||
const subscription = await watchCalendar(creds.accessToken, PRIMARY_CALENDAR, channelId, webhookUrl, row.id);
|
||||
await client.calendarConnection.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { webhookSubscriptionId: subscription.channelId, webhookSubscriptionExpiresAt: subscription.expiresAt, status: "active", lastErrorText: null },
|
||||
});
|
||||
renewed += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.calendarConnection.updateMany({ where: { id: row.id, tenantId }, data: { lastErrorText: "calendar.health.webhookSubscriptionFailed" } });
|
||||
}
|
||||
}
|
||||
return { checked: rows.length, renewed, failed, skipped };
|
||||
}
|
||||
|
||||
export async function drainCalendarWebhookEventsForTenant(
|
||||
client: CalendarWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number } = {},
|
||||
): Promise<{ claimed: number; completed: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const rows = await client.calendarWebhookEvent.findMany({
|
||||
where: { tenantId, processingStatus: "pending" },
|
||||
select: { id: true, tenantId: true, connectionId: true },
|
||||
orderBy: { receivedAt: "asc" },
|
||||
take: opts.take ?? DEFAULT_TAKE,
|
||||
});
|
||||
let claimed = 0;
|
||||
let completed = 0;
|
||||
let failed = 0;
|
||||
for (const row of rows) {
|
||||
const claim = await client.calendarWebhookEvent.updateMany({
|
||||
where: { id: row.id, tenantId, processingStatus: "pending" },
|
||||
data: { processingStatus: "processing" },
|
||||
});
|
||||
if (claim.count !== 1) {
|
||||
continue;
|
||||
}
|
||||
claimed += 1;
|
||||
try {
|
||||
await syncExternalEventsForConnection(client, tenantId, row.connectionId, now);
|
||||
await client.calendarWebhookEvent.update({
|
||||
where: { id: row.id },
|
||||
data: { processingStatus: "completed", processedAt: now, processingErrorText: null },
|
||||
});
|
||||
completed += 1;
|
||||
} catch (error) {
|
||||
failed += 1;
|
||||
await client.calendarWebhookEvent.update({
|
||||
where: { id: row.id },
|
||||
data: { processingStatus: "failed", processedAt: now, processingErrorText: redactedError(error) },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { claimed, completed, failed };
|
||||
}
|
||||
|
||||
export async function syncExternalEventsForConnection(client: CalendarWorkerClient, tenantId: string, connectionId: string, now = new Date()): Promise<{ upserted: number; fullResync: boolean }> {
|
||||
const connection = await client.calendarConnection.findFirst({
|
||||
where: { id: connectionId, tenantId, archivedAt: null },
|
||||
select: { id: true, tenantId: true, userId: true, oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true, webhookSubscriptionId: true, webhookSubscriptionExpiresAt: true, syncDirection: true, status: true },
|
||||
});
|
||||
if (!connection || connection.syncDirection === "hivegrid_to_external_only") {
|
||||
return { upserted: 0, fullResync: false };
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, connectionId);
|
||||
if (!baseCreds) {
|
||||
return { upserted: 0, fullResync: false };
|
||||
}
|
||||
const creds = await ensureFreshCreds(client, tenantId, connectionId, baseCreds, now);
|
||||
const cursor = await client.calendarSyncCursor.findFirst({
|
||||
where: { connectionId, externalCalendarId: PRIMARY_CALENDAR },
|
||||
select: { cursorToken: true },
|
||||
});
|
||||
|
||||
let syncToken = cursor?.cursorToken ?? undefined;
|
||||
let pageToken: string | undefined;
|
||||
let nextSyncToken: string | undefined;
|
||||
let upserted = 0;
|
||||
let fullResync = false;
|
||||
|
||||
do {
|
||||
let page: Awaited<ReturnType<typeof listEvents>>;
|
||||
try {
|
||||
page = await listEvents(creds.accessToken, PRIMARY_CALENDAR, {
|
||||
syncToken,
|
||||
pageToken,
|
||||
timeMin: syncToken ? undefined : new Date(now.getTime() - WINDOW_PAST_DAYS * 86_400_000).toISOString(),
|
||||
timeMax: syncToken ? undefined : new Date(now.getTime() + WINDOW_FUTURE_DAYS * 86_400_000).toISOString(),
|
||||
});
|
||||
} catch (error) {
|
||||
if (error instanceof GoogleCalendarError && error.fullResyncRequired) {
|
||||
fullResync = true;
|
||||
syncToken = undefined;
|
||||
pageToken = undefined;
|
||||
await client.calendarSyncCursor.updateMany({ where: { connectionId, externalCalendarId: PRIMARY_CALENDAR }, data: { cursorToken: null } });
|
||||
continue;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
|
||||
for (const event of page.events) {
|
||||
const mapping = await client.calendarEventMapping.findFirst({
|
||||
where: { tenantId, connectionId, externalEventId: event.id, provider: "google" },
|
||||
select: { id: true, internalEventId: true, externalEventId: true, externalCalendarId: true, connectionId: true, lastSyncedAt: true, lastKnownExternalEtag: true, lastKnownInternalVersionToken: true },
|
||||
});
|
||||
if (event.status === "cancelled" && mapping) {
|
||||
await persistConflict(client, {
|
||||
tenantId,
|
||||
connectionId,
|
||||
userId: connection.userId,
|
||||
internalEventId: mapping.internalEventId,
|
||||
externalEventId: event.id,
|
||||
resolution: "external_deleted",
|
||||
descriptionText: "calendar.conflict.externalDeleted",
|
||||
});
|
||||
await client.calendarEventMapping.deleteMany({ where: { id: mapping.id, tenantId } });
|
||||
}
|
||||
const fields = toExternalEventFields(event, { tenantId, userId: connection.userId, connectionId }, now);
|
||||
await client.calendarEvent.upsert({
|
||||
where: { tenantId_userId_provider_externalEventId: { tenantId, userId: connection.userId, provider: "google", externalEventId: event.id } },
|
||||
create: fields,
|
||||
update: { ...fields, createdAt: undefined },
|
||||
});
|
||||
upserted += 1;
|
||||
}
|
||||
|
||||
pageToken = page.nextPageToken;
|
||||
nextSyncToken = page.nextSyncToken ?? nextSyncToken;
|
||||
} while (pageToken);
|
||||
|
||||
if (nextSyncToken) {
|
||||
await client.calendarSyncCursor.upsert({
|
||||
where: { connectionId_externalCalendarId: { connectionId, externalCalendarId: PRIMARY_CALENDAR } },
|
||||
create: { tenantId, connectionId, externalCalendarId: PRIMARY_CALENDAR, cursorToken: nextSyncToken, lastFullSyncAt: fullResync ? now : null },
|
||||
update: { cursorToken: nextSyncToken, ...(fullResync ? { lastFullSyncAt: now } : {}) },
|
||||
});
|
||||
}
|
||||
await client.calendarConnection.updateMany({ where: { id: connectionId, tenantId }, data: { lastSyncAt: now, status: "active" } });
|
||||
return { upserted, fullResync };
|
||||
}
|
||||
|
||||
export async function syncInternalCalendarEventsForTenant(
|
||||
client: CalendarWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number } = {},
|
||||
): Promise<{ scanned: number; created: number; updated: number; deleted: number; conflicts: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const connections = await client.calendarConnection.findMany({
|
||||
where: { tenantId, archivedAt: null, status: "active", syncDirection: { in: ["bidirectional", "hivegrid_to_external_only"] } },
|
||||
select: { id: true, tenantId: true, userId: true, oauthRefreshTokenCiphertext: true, oauthAccessTokenCiphertext: true, oauthAccessTokenExpiresAt: true, webhookSubscriptionId: true, webhookSubscriptionExpiresAt: true, syncDirection: true, status: true },
|
||||
});
|
||||
|
||||
let scanned = 0;
|
||||
let created = 0;
|
||||
let updated = 0;
|
||||
let deleted = 0;
|
||||
let conflicts = 0;
|
||||
let failed = 0;
|
||||
|
||||
for (const connection of connections) {
|
||||
const baseCreds = await loadCreds(client, tenantId, connection.id);
|
||||
if (!baseCreds) {
|
||||
continue;
|
||||
}
|
||||
let creds: CalendarCreds;
|
||||
try {
|
||||
creds = await ensureFreshCreds(client, tenantId, connection.id, baseCreds, now);
|
||||
} catch {
|
||||
failed += 1;
|
||||
continue;
|
||||
}
|
||||
const events = await client.calendarEvent.findMany({
|
||||
where: { tenantId, userId: connection.userId, source: "hivegrid_internal" },
|
||||
select: { id: true, updatedAt: true, tenantId: true, userId: true, title: true, description: true, location: true, startsAt: true, endsAt: true, isAllDay: true, timeZone: true, attendees: true, versionToken: true, archivedAt: true },
|
||||
orderBy: { updatedAt: "asc" },
|
||||
take: opts.take ?? DEFAULT_TAKE,
|
||||
});
|
||||
for (const event of events) {
|
||||
scanned += 1;
|
||||
try {
|
||||
const mapping = await client.calendarEventMapping.findFirst({
|
||||
where: { tenantId, connectionId: connection.id, internalEventId: event.id, provider: "google", externalCalendarId: PRIMARY_CALENDAR },
|
||||
select: { id: true, internalEventId: true, externalEventId: true, externalCalendarId: true, connectionId: true, lastSyncedAt: true, lastKnownExternalEtag: true, lastKnownInternalVersionToken: true },
|
||||
});
|
||||
if (event.archivedAt) {
|
||||
if (mapping) {
|
||||
await deleteEvent(creds.accessToken, PRIMARY_CALENDAR, mapping.externalEventId);
|
||||
await client.calendarEventMapping.deleteMany({ where: { id: mapping.id, tenantId } });
|
||||
deleted += 1;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (!mapping) {
|
||||
const result = await insertEvent(creds.accessToken, PRIMARY_CALENDAR, toGoogleInput(event));
|
||||
await client.calendarEventMapping.create({
|
||||
data: {
|
||||
tenantId,
|
||||
internalEventId: event.id,
|
||||
externalEventId: result.id,
|
||||
provider: "google",
|
||||
externalCalendarId: PRIMARY_CALENDAR,
|
||||
connectionId: connection.id,
|
||||
lastSyncedAt: now,
|
||||
lastKnownExternalEtag: result.etag ?? null,
|
||||
lastKnownInternalVersionToken: event.versionToken,
|
||||
},
|
||||
});
|
||||
created += 1;
|
||||
continue;
|
||||
}
|
||||
const changedSinceSync = !mapping.lastSyncedAt || event.updatedAt.getTime() > mapping.lastSyncedAt.getTime() || mapping.lastKnownInternalVersionToken !== event.versionToken;
|
||||
if (!changedSinceSync) {
|
||||
continue;
|
||||
}
|
||||
const result = await patchEvent(creds.accessToken, PRIMARY_CALENDAR, mapping.externalEventId, toGoogleInput(event), mapping.lastKnownExternalEtag);
|
||||
await client.calendarEventMapping.update({
|
||||
where: { id: mapping.id },
|
||||
data: { lastSyncedAt: now, lastKnownExternalEtag: result.etag ?? null, lastKnownInternalVersionToken: event.versionToken },
|
||||
});
|
||||
updated += 1;
|
||||
} catch (error) {
|
||||
if (error instanceof GoogleCalendarError && error.httpStatus === 412) {
|
||||
conflicts += 1;
|
||||
const mapping = await client.calendarEventMapping.findFirst({
|
||||
where: { tenantId, connectionId: connection.id, internalEventId: event.id, provider: "google", externalCalendarId: PRIMARY_CALENDAR },
|
||||
select: { id: true, internalEventId: true, externalEventId: true, externalCalendarId: true, connectionId: true, lastSyncedAt: true, lastKnownExternalEtag: true, lastKnownInternalVersionToken: true },
|
||||
});
|
||||
await persistConflict(client, {
|
||||
tenantId,
|
||||
connectionId: connection.id,
|
||||
userId: connection.userId,
|
||||
internalEventId: event.id,
|
||||
externalEventId: mapping?.externalEventId ?? null,
|
||||
resolution: "external_won",
|
||||
descriptionText: "calendar.conflict.externalWon",
|
||||
});
|
||||
continue;
|
||||
}
|
||||
failed += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
return { scanned, created, updated, deleted, conflicts, failed };
|
||||
}
|
||||
|
||||
async function patchEvent(accessToken: string, calendarId: string, eventId: string, input: GoogleEventInput, etag: string | null): Promise<{ id: string; etag?: string }> {
|
||||
return googlePatchEvent(accessToken, calendarId, eventId, input, etag ?? undefined);
|
||||
}
|
||||
|
||||
function redactedError(error: unknown): string {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return message
|
||||
.replace(/(authorization\s*:\s*Bearer\s+)\S+/gi, "$1[redacted]")
|
||||
.replace(/(token|secret|password)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]")
|
||||
.slice(0, 500);
|
||||
}
|
||||
+35
@@ -0,0 +1,35 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { INTEGRATION_CATALOG } from "./catalog.js";
|
||||
import { buildAppUpsertData, buildCatalogSeedPlan } from "./catalog-seed.js";
|
||||
|
||||
// R-P5 — the catalog seed plan mirrors INTEGRATION_CATALOG 1:1 and stays
|
||||
// idempotent by unique key (deferred App-table seed, now shipped).
|
||||
|
||||
describe("buildCatalogSeedPlan", () => {
|
||||
it("produces one upsert payload per catalog entry, keyed uniquely", () => {
|
||||
const plan = buildCatalogSeedPlan();
|
||||
expect(plan).toHaveLength(INTEGRATION_CATALOG.length);
|
||||
expect(new Set(plan.map((entry) => entry.key)).size).toBe(plan.length);
|
||||
});
|
||||
|
||||
it("maps catalog fields onto the App columns (title carries the i18n key)", () => {
|
||||
const sample = INTEGRATION_CATALOG.find((entry) => entry.key === "sample-data-sync")!;
|
||||
const data = buildAppUpsertData(sample);
|
||||
expect(data).toMatchObject({
|
||||
key: "sample-data-sync",
|
||||
title: "integrations.app.sampleDataSync.title",
|
||||
category: "erp",
|
||||
connectionType: "rest_api",
|
||||
phase: "P5",
|
||||
icon: null,
|
||||
isActive: true,
|
||||
});
|
||||
expect(data.connectionSchema.fields.map((field) => field.name)).toEqual(["baseUrl", "apiKey"]);
|
||||
});
|
||||
|
||||
it("keeps oauth2 apps with empty credential forms seedable", () => {
|
||||
const gmail = buildCatalogSeedPlan().find((entry) => entry.key === "gmail")!;
|
||||
expect(gmail.connectionType).toBe("oauth2");
|
||||
expect(gmail.connectionSchema.fields).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,39 @@
|
||||
// R-P5 — pure builders for the App catalog seed (INTEGRATION_CATALOG -> global
|
||||
// `App` definition table). No Prisma/node imports: the caller (db seed) runs the
|
||||
// actual upserts, so this stays importable everywhere and unit-testable. The
|
||||
// tenant runtime keeps reading the code catalog (DataConnection.appId = bare
|
||||
// catalog key, AD-21 — no App FK); the table exists as the global definition/
|
||||
// drift surface.
|
||||
|
||||
import { INTEGRATION_CATALOG, type AppCatalogEntry } from "./catalog.js";
|
||||
|
||||
/** Prisma-shaped payload for one `App` upsert (create/update identical). */
|
||||
export interface AppUpsertData {
|
||||
readonly key: string;
|
||||
/** i18n key of the display name (App.title carries the key, M003). */
|
||||
readonly title: string;
|
||||
readonly category: AppCatalogEntry["category"];
|
||||
readonly connectionType: AppCatalogEntry["connectionType"];
|
||||
readonly connectionSchema: { readonly fields: AppCatalogEntry["connectionSchema"]["fields"] };
|
||||
readonly phase: string | null;
|
||||
readonly icon: string | null;
|
||||
readonly isActive: boolean;
|
||||
}
|
||||
|
||||
export function buildAppUpsertData(entry: AppCatalogEntry): AppUpsertData {
|
||||
return {
|
||||
key: entry.key,
|
||||
title: entry.titleKey,
|
||||
category: entry.category,
|
||||
connectionType: entry.connectionType,
|
||||
connectionSchema: { fields: entry.connectionSchema.fields },
|
||||
phase: entry.phase ?? null,
|
||||
icon: entry.icon ?? null,
|
||||
isActive: true,
|
||||
};
|
||||
}
|
||||
|
||||
/** One upsert payload per catalog entry (idempotent by unique `key`). */
|
||||
export function buildCatalogSeedPlan(): AppUpsertData[] {
|
||||
return INTEGRATION_CATALOG.map(buildAppUpsertData);
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
// R-P5 (P5) — the Apps-Engine App catalog (global definition table seed).
|
||||
//
|
||||
// One entry per integratable app. The `connectionSchema` drives the
|
||||
// auto-generated credential form in the connect wizard. v1 ships ONLY the
|
||||
// reference `sample-data-sync` adapter; concrete apps (Gmail/Outlook/AirCall/
|
||||
// Mollie/KWP) add their catalog entry + adapter together in P14/P15/P16/P20, so
|
||||
// the catalog and the adapter registry stay drift-free.
|
||||
//
|
||||
// Pure data (no node/Prisma) — importable by web, worker, the catalog upsert, and
|
||||
// the drift check.
|
||||
|
||||
import type { AdapterConnectionType } from "@hivegrid/foundation";
|
||||
|
||||
/** A credential field rendered by the connect wizard (from connectionSchema). */
|
||||
export interface AppCredentialField {
|
||||
readonly name: string;
|
||||
/** i18n label key (M003). */
|
||||
readonly labelKey: string;
|
||||
readonly type: "text" | "secret" | "url";
|
||||
readonly required: boolean;
|
||||
}
|
||||
|
||||
export interface AppConnectionSchema {
|
||||
readonly fields: readonly AppCredentialField[];
|
||||
}
|
||||
|
||||
export type AppCatalogCategory = "erp" | "communication" | "calendar" | "signature" | "payment" | "ki";
|
||||
|
||||
export interface AppCatalogEntry {
|
||||
readonly key: string;
|
||||
/** i18n key for the app's display name (M003). Brand names route through i18n
|
||||
* too, staying identical across locales. */
|
||||
readonly titleKey: string;
|
||||
readonly category: AppCatalogCategory;
|
||||
readonly connectionType: AdapterConnectionType;
|
||||
readonly connectionSchema: AppConnectionSchema;
|
||||
readonly phase: string;
|
||||
readonly icon?: string;
|
||||
}
|
||||
|
||||
export const INTEGRATION_CATALOG: readonly AppCatalogEntry[] = [
|
||||
{
|
||||
key: "sample-data-sync",
|
||||
titleKey: "integrations.app.sampleDataSync.title",
|
||||
category: "erp",
|
||||
connectionType: "rest_api",
|
||||
phase: "P5",
|
||||
connectionSchema: {
|
||||
fields: [
|
||||
{ name: "baseUrl", labelKey: "integrations.field.baseUrl", type: "url", required: true },
|
||||
{ name: "apiKey", labelKey: "integrations.field.apiKey", type: "secret", required: true },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
// AK-P16a · Google Calendar. connectionType oauth2 → the connect flow is the
|
||||
// OAuth redirect (no manual credential form), so `fields` is empty. The
|
||||
// per-USER connection + bidirectional sync lives in the calendar module
|
||||
// (CalendarConnection); this catalog entry keeps the app reachable in the
|
||||
// integrations surface and drift-free with its registered adapter.
|
||||
key: "google-calendar",
|
||||
titleKey: "integrations.app.googleCalendar.title",
|
||||
category: "calendar",
|
||||
connectionType: "oauth2",
|
||||
phase: "P16",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// VA-P23 · Gmail mailbox sync. connectionType oauth2 → the connect flow is
|
||||
// the OAuth redirect (no manual credential form). The per-USER mailbox +
|
||||
// push sync lives in the email-inbox module (EmailIntegrationMailbox); this
|
||||
// catalog entry keeps the app reachable in the integrations surface and
|
||||
// drift-free with its registered adapter.
|
||||
key: "gmail",
|
||||
titleKey: "integrations.app.gmail.title",
|
||||
category: "communication",
|
||||
connectionType: "oauth2",
|
||||
phase: "P23",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// VA-P23 · Microsoft (Outlook/Graph) mailbox sync — same pattern as gmail.
|
||||
key: "microsoft-mail",
|
||||
titleKey: "integrations.app.microsoftMail.title",
|
||||
category: "communication",
|
||||
connectionType: "oauth2",
|
||||
phase: "P23",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// AK-P16d · AD-25 default: hardened self-hosted SES. No external provider
|
||||
// credentials are required; the app entry keeps the module visible in the
|
||||
// integration surface and drift-free with the registered adapter.
|
||||
key: "ses-selfhosted",
|
||||
titleKey: "integrations.app.sesSelfhosted.title",
|
||||
category: "signature",
|
||||
connectionType: "rest_api",
|
||||
phase: "P16",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// AK-P16d · Optional PandaDoc BYOK bridge. AD-25 keeps PandaDoc out of the
|
||||
// default flow; tenants can connect their own key/template when needed.
|
||||
key: "pandadoc-byok",
|
||||
titleKey: "integrations.app.pandadocByok.title",
|
||||
category: "signature",
|
||||
connectionType: "api_key",
|
||||
phase: "P16",
|
||||
connectionSchema: {
|
||||
fields: [
|
||||
{ name: "apiKey", labelKey: "integrations.field.apiKey", type: "secret", required: true },
|
||||
{ name: "templateUuid", labelKey: "integrations.field.templateUuid", type: "text", required: true },
|
||||
{ name: "webhookSharedKey", labelKey: "integrations.field.webhookSharedKey", type: "secret", required: false },
|
||||
],
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
/** All catalog keys (for drift comparison). */
|
||||
export function catalogKeys(): string[] {
|
||||
return INTEGRATION_CATALOG.map((entry) => entry.key);
|
||||
}
|
||||
|
||||
/** Look up a catalog entry by key. */
|
||||
export function getCatalogEntry(key: string): AppCatalogEntry | undefined {
|
||||
return INTEGRATION_CATALOG.find((entry) => entry.key === key);
|
||||
}
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
// VA-P23 · auto-match wiring (M09 Block E + H). Bridges the sync engine's
|
||||
// upsert hook to the pure decision (email-match.ts): gathers candidates from
|
||||
// the CRM (KontaktEmail / Lead.email / open Projekte / subject Projekt), writes
|
||||
// the match onto the message row, and logs the Activity-Stream entry
|
||||
// (`email_received` / `email_sent`, actorKind `system`, DoD 14).
|
||||
//
|
||||
// A manual override wins: overridden messages are never re-matched, and the
|
||||
// hook only matches NEWLY created rows (re-syncs of an existing mirror keep
|
||||
// their match untouched).
|
||||
|
||||
import { logActivity } from "@hivegrid/activity";
|
||||
import { decideEmailMatch, extractSubjectProjektNummer, type EmailMatchResult } from "./email-match.js";
|
||||
import type { EmailMessageUpsertedHook, EmailWorkerClient } from "./email-worker-tasks.server.js";
|
||||
import type { MappedEmailMessage } from "./email-message-mapping.js";
|
||||
|
||||
type KontaktEmailRow = { kontaktId: string; primaer: boolean };
|
||||
type IdRow = { id: string };
|
||||
type ProjektKontaktRow = { projektId: string };
|
||||
type MessageMatchRow = { id: string; manualOverrideAt: Date | null };
|
||||
|
||||
/** The extra CRM read surface the matcher needs on top of the sync client. */
|
||||
export type EmailMatchClient = EmailWorkerClient & {
|
||||
kontaktEmail: { findMany(args: Record<string, unknown>): Promise<KontaktEmailRow[]> };
|
||||
lead: { findMany(args: Record<string, unknown>): Promise<IdRow[]> };
|
||||
projekt: { findFirst(args: Record<string, unknown>): Promise<IdRow | null> };
|
||||
projektKontakt: { findMany(args: Record<string, unknown>): Promise<ProjektKontaktRow[]> };
|
||||
emailIntegrationMessage: EmailWorkerClient["emailIntegrationMessage"] & {
|
||||
findUnique?(args: Record<string, unknown>): Promise<MessageMatchRow | null>;
|
||||
};
|
||||
activity: { create(args: { data: Record<string, unknown> }): Promise<{ id: string }> };
|
||||
};
|
||||
|
||||
function klartextSummary(message: MappedEmailMessage): string {
|
||||
const who = message.direction === "inbound" ? (message.from.name ?? message.from.address) : (message.to[0]?.name ?? message.to[0]?.address ?? "");
|
||||
const subject = message.subject?.trim() ? `„${message.subject.trim()}“` : "(ohne Betreff)";
|
||||
return message.direction === "inbound" ? `Eingehende E-Mail von ${who}: ${subject}` : `Ausgehende E-Mail an ${who}: ${subject}`;
|
||||
}
|
||||
|
||||
async function gatherAndDecide(
|
||||
client: EmailMatchClient,
|
||||
tenantId: string,
|
||||
message: MappedEmailMessage,
|
||||
): Promise<EmailMatchResult> {
|
||||
// Every connected mailbox address of the tenant = "own" (self-mail exclusion).
|
||||
const mailboxes = await client.emailIntegrationMailbox.findMany({
|
||||
where: { tenantId, archivedAt: null },
|
||||
select: { id: true, emailAddress: true },
|
||||
});
|
||||
const ownAddresses = mailboxes.map((m) => (m as unknown as { emailAddress: string }).emailAddress.toLowerCase());
|
||||
|
||||
// Subject token `[Projekt #<nummer>]` — must exist in the tenant (else ignored).
|
||||
const nummer = extractSubjectProjektNummer(message.subject);
|
||||
const subjectProjekt = nummer
|
||||
? await client.projekt.findFirst({ where: { tenantId, projektNummer: nummer, archivedAt: null }, select: { id: true } })
|
||||
: null;
|
||||
|
||||
const probe = decideEmailMatch({
|
||||
direction: message.direction,
|
||||
fromAddress: message.from.address,
|
||||
toAddresses: message.to,
|
||||
isNewsletter: message.isNewsletter,
|
||||
ownAddresses,
|
||||
subjectProjektId: subjectProjekt?.id ?? null,
|
||||
kontaktCandidates: [],
|
||||
leadCandidateIds: [],
|
||||
openProjekteByKontaktId: {},
|
||||
});
|
||||
const address = probe.counterpartAddress;
|
||||
if (!address && !subjectProjekt) {
|
||||
return probe;
|
||||
}
|
||||
|
||||
const kontaktCandidates = address
|
||||
? await client.kontaktEmail.findMany({ where: { tenantId, email: address }, select: { kontaktId: true, primaer: true } })
|
||||
: [];
|
||||
const leadCandidates =
|
||||
address && kontaktCandidates.length === 0
|
||||
? await client.lead.findMany({ where: { tenantId, email: address, archivedAt: null, convertedAt: null }, select: { id: true }, take: 1 })
|
||||
: [];
|
||||
|
||||
// Open Projekte only for the Kontakt the pure decision would pick (primary first).
|
||||
const pickedKontaktId = kontaktCandidates.length > 0 ? (kontaktCandidates.find((c) => c.primaer) ?? kontaktCandidates[0]).kontaktId : null;
|
||||
const openProjekteByKontaktId: Record<string, string[]> = {};
|
||||
if (pickedKontaktId && !subjectProjekt) {
|
||||
const links = await client.projektKontakt.findMany({
|
||||
where: { tenantId, kontaktId: pickedKontaktId, projekt: { wonAt: null, lostAt: null, archivedAt: null } },
|
||||
select: { projektId: true },
|
||||
});
|
||||
openProjekteByKontaktId[pickedKontaktId] = [...new Set(links.map((l) => l.projektId))];
|
||||
}
|
||||
|
||||
return decideEmailMatch({
|
||||
direction: message.direction,
|
||||
fromAddress: message.from.address,
|
||||
toAddresses: message.to,
|
||||
isNewsletter: message.isNewsletter,
|
||||
ownAddresses,
|
||||
subjectProjektId: subjectProjekt?.id ?? null,
|
||||
kontaktCandidates,
|
||||
leadCandidateIds: leadCandidates.map((l) => l.id),
|
||||
openProjekteByKontaktId,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the sync-engine hook. Failures inside the matcher degrade to "no match"
|
||||
* — the message itself is already persisted, matching must never break the sync.
|
||||
*/
|
||||
export function createEmailAutoMatchHook(): EmailMessageUpsertedHook {
|
||||
return async ({ client, tenantId, mailboxId, messageId, created, message }) => {
|
||||
if (!created) {
|
||||
return; // existing mirrors keep their match (and any manual override)
|
||||
}
|
||||
const matchClient = client as EmailMatchClient;
|
||||
try {
|
||||
const match = await gatherAndDecide(matchClient, tenantId, message);
|
||||
if (match.confidence === "none") {
|
||||
return;
|
||||
}
|
||||
await matchClient.emailIntegrationMessage.updateMany({
|
||||
where: { id: messageId, tenantId, mailboxId, manualOverrideAt: null },
|
||||
data: {
|
||||
matchedKontaktId: match.matchedKontaktId,
|
||||
matchedLeadId: match.matchedLeadId,
|
||||
matchedProjektId: match.matchedProjektId,
|
||||
matchConfidence: match.confidence,
|
||||
},
|
||||
});
|
||||
|
||||
// Activity at the primary matched entity; the rest ride as related refs.
|
||||
const subject = match.matchedKontaktId
|
||||
? { subjectType: "contact" as const, subjectId: match.matchedKontaktId }
|
||||
: match.matchedLeadId
|
||||
? { subjectType: "lead" as const, subjectId: match.matchedLeadId }
|
||||
: { subjectType: "project" as const, subjectId: match.matchedProjektId as string };
|
||||
const relatedEntityRefs = [
|
||||
...(match.matchedProjektId && subject.subjectType !== "project" ? [{ type: "project" as const, id: match.matchedProjektId }] : []),
|
||||
...(match.matchedLeadId && subject.subjectType !== "lead" ? [{ type: "lead" as const, id: match.matchedLeadId }] : []),
|
||||
];
|
||||
await logActivity(
|
||||
{
|
||||
tenantId,
|
||||
actorKind: "system",
|
||||
activityType: message.direction === "inbound" ? "email_received" : "email_sent",
|
||||
subjectType: subject.subjectType,
|
||||
subjectId: subject.subjectId,
|
||||
summaryText: klartextSummary(message),
|
||||
relatedEntityRefs: relatedEntityRefs.length > 0 ? relatedEntityRefs : undefined,
|
||||
metadata: {
|
||||
emailMessageId: messageId,
|
||||
mailboxId,
|
||||
providerMessageId: message.providerMessageId,
|
||||
subject: message.subject,
|
||||
snippet: message.snippet,
|
||||
matchConfidence: match.confidence,
|
||||
},
|
||||
},
|
||||
{ client: matchClient },
|
||||
);
|
||||
} catch {
|
||||
// Matching is best-effort — the mirror row stays with confidence "none".
|
||||
}
|
||||
};
|
||||
}
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { counterpartAddress, decideEmailMatch, extractSubjectProjektNummer, type EmailMatchInput } from "./email-match.js";
|
||||
|
||||
// VA-P23 — the auto-match rules (M09 Block E) incl. every spec edge case:
|
||||
// primary-contact tie-break, own-address exclusion, newsletter exclusion,
|
||||
// subject token precedence, 1-open-Projekt heuristic.
|
||||
|
||||
function input(overrides: Partial<EmailMatchInput> = {}): EmailMatchInput {
|
||||
return {
|
||||
direction: "inbound",
|
||||
fromAddress: "max@kunde.de",
|
||||
toAddresses: [{ address: "info@handwerk.de" }],
|
||||
isNewsletter: false,
|
||||
ownAddresses: ["info@handwerk.de"],
|
||||
subjectProjektId: null,
|
||||
kontaktCandidates: [],
|
||||
leadCandidateIds: [],
|
||||
openProjekteByKontaktId: {},
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("extractSubjectProjektNummer", () => {
|
||||
it("extracts the token in its variants", () => {
|
||||
expect(extractSubjectProjektNummer("Re: [Projekt #123] Angebot")).toBe("123");
|
||||
expect(extractSubjectProjektNummer("[projekt # P-42 ] Nachtrag")).toBe("P-42");
|
||||
expect(extractSubjectProjektNummer("Kein Token")).toBeNull();
|
||||
expect(extractSubjectProjektNummer(null)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("counterpartAddress", () => {
|
||||
it("uses the sender for inbound mail", () => {
|
||||
expect(counterpartAddress(input())).toBe("max@kunde.de");
|
||||
});
|
||||
|
||||
it("excludes the tenant's own mailbox addresses (self-mail)", () => {
|
||||
expect(counterpartAddress(input({ fromAddress: "Info@Handwerk.de" }))).toBeNull();
|
||||
});
|
||||
|
||||
it("uses the first non-own recipient for outbound mail", () => {
|
||||
const result = counterpartAddress(
|
||||
input({ direction: "outbound", fromAddress: "info@handwerk.de", toAddresses: [{ address: "info@handwerk.de" }, { address: "max@kunde.de" }] }),
|
||||
);
|
||||
expect(result).toBe("max@kunde.de");
|
||||
});
|
||||
});
|
||||
|
||||
describe("decideEmailMatch", () => {
|
||||
it("hard-matches a Kontakt by exact email (high)", () => {
|
||||
const result = decideEmailMatch(input({ kontaktCandidates: [{ kontaktId: "k1", primaer: true }] }));
|
||||
expect(result).toMatchObject({ matchedKontaktId: "k1", matchedLeadId: null, matchedProjektId: null, confidence: "high" });
|
||||
});
|
||||
|
||||
it("prefers the PRIMARY-email contact when several contacts share the address", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({
|
||||
kontaktCandidates: [
|
||||
{ kontaktId: "k-secondary", primaer: false },
|
||||
{ kontaktId: "k-primary", primaer: true },
|
||||
],
|
||||
}),
|
||||
);
|
||||
expect(result.matchedKontaktId).toBe("k-primary");
|
||||
});
|
||||
|
||||
it("matches a Lead only when no Kontakt matched", () => {
|
||||
const leadOnly = decideEmailMatch(input({ leadCandidateIds: ["l1"] }));
|
||||
expect(leadOnly).toMatchObject({ matchedKontaktId: null, matchedLeadId: "l1", confidence: "high" });
|
||||
|
||||
const both = decideEmailMatch(input({ kontaktCandidates: [{ kontaktId: "k1", primaer: true }], leadCandidateIds: ["l1"] }));
|
||||
expect(both.matchedLeadId).toBeNull();
|
||||
expect(both.matchedKontaktId).toBe("k1");
|
||||
});
|
||||
|
||||
it("a valid [Projekt #] subject token matches high — even without a Kontakt", () => {
|
||||
const result = decideEmailMatch(input({ subjectProjektId: "p42" }));
|
||||
expect(result).toMatchObject({ matchedProjektId: "p42", confidence: "high" });
|
||||
});
|
||||
|
||||
it("applies the 1-open-Projekt heuristic as medium", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({ kontaktCandidates: [{ kontaktId: "k1", primaer: true }], openProjekteByKontaktId: { k1: ["p1"] } }),
|
||||
);
|
||||
expect(result).toMatchObject({ matchedKontaktId: "k1", matchedProjektId: "p1", confidence: "medium" });
|
||||
});
|
||||
|
||||
it("does NOT auto-assign a Projekt when the Kontakt has several open ones", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({ kontaktCandidates: [{ kontaktId: "k1", primaer: true }], openProjekteByKontaktId: { k1: ["p1", "p2"] } }),
|
||||
);
|
||||
expect(result.matchedProjektId).toBeNull();
|
||||
expect(result.matchedKontaktId).toBe("k1");
|
||||
expect(result.confidence).toBe("high");
|
||||
});
|
||||
|
||||
it("the subject token beats the heuristic", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({ subjectProjektId: "p-subject", kontaktCandidates: [{ kontaktId: "k1", primaer: true }], openProjekteByKontaktId: { k1: ["p-heuristic"] } }),
|
||||
);
|
||||
expect(result.matchedProjektId).toBe("p-subject");
|
||||
expect(result.confidence).toBe("high");
|
||||
});
|
||||
|
||||
it("never matches newsletters (List-Unsubscribe)", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({ isNewsletter: true, kontaktCandidates: [{ kontaktId: "k1", primaer: true }], subjectProjektId: "p1" }),
|
||||
);
|
||||
expect(result).toMatchObject({ matchedKontaktId: null, matchedLeadId: null, matchedProjektId: null, confidence: "none" });
|
||||
});
|
||||
|
||||
it("returns none (manually assignable) when nothing matches", () => {
|
||||
const result = decideEmailMatch(input());
|
||||
expect(result.confidence).toBe("none");
|
||||
expect(result.counterpartAddress).toBe("max@kunde.de");
|
||||
});
|
||||
|
||||
it("does not contact-match a self-addressed mail but keeps a subject-token Projekt", () => {
|
||||
const result = decideEmailMatch(
|
||||
input({ fromAddress: "info@handwerk.de", subjectProjektId: "p9", kontaktCandidates: [] }),
|
||||
);
|
||||
expect(result.matchedKontaktId).toBeNull();
|
||||
expect(result.matchedProjektId).toBe("p9");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,136 @@
|
||||
// VA-P23 · auto-match decision logic (M09 Block E) — PURE function, no I/O.
|
||||
//
|
||||
// The caller (email-match-hook.server.ts) gathers the candidates (KontaktEmail
|
||||
// lookups, Lead email lookups, open Projekte per Kontakt, subject-referenced
|
||||
// Projekt) and this decides the final match. AD-20 pivot: match targets are
|
||||
// Kontakt / Lead / Projekt — there is NO "Deal" entity.
|
||||
//
|
||||
// Rules (spec order):
|
||||
// 0. Newsletters (List-Unsubscribe) never auto-match.
|
||||
// 1. Own mailbox addresses are excluded (self-mail → no contact match).
|
||||
// 2. Subject pattern `[Projekt #<nummer>]` (validated by the caller) → high.
|
||||
// 3. Exact Kontakt email match → high; several contacts share the address →
|
||||
// the PRIMARY-email contact wins.
|
||||
// 4. Exact Lead email match (no Kontakt) → lead match, high.
|
||||
// 5. Kontakt matched + exactly ONE open Projekt → medium Projekt heuristic
|
||||
// (a subject-pattern Projekt from rule 2 is never overridden).
|
||||
// 6. Nothing matched → none (visible in the inbox, manually assignable).
|
||||
//
|
||||
// A manual override (`manualOverrideAt`) is enforced by the CALLER: overridden
|
||||
// messages are never re-matched (M09 Block E).
|
||||
|
||||
export interface EmailMatchAddress {
|
||||
readonly address: string;
|
||||
}
|
||||
|
||||
export interface EmailMatchKontaktCandidate {
|
||||
readonly kontaktId: string;
|
||||
/** True when the matching KontaktEmail row is the contact's primary address. */
|
||||
readonly primaer: boolean;
|
||||
}
|
||||
|
||||
export interface EmailMatchInput {
|
||||
readonly direction: "inbound" | "outbound";
|
||||
readonly fromAddress: string;
|
||||
readonly toAddresses: readonly EmailMatchAddress[];
|
||||
readonly isNewsletter: boolean;
|
||||
/** Every connected mailbox address of the tenant (lowercased). */
|
||||
readonly ownAddresses: readonly string[];
|
||||
/** Projekt referenced by a valid `[Projekt #<nummer>]` subject token, if any. */
|
||||
readonly subjectProjektId: string | null;
|
||||
/** Kontakt candidates for the counterpart address (caller-queried). */
|
||||
readonly kontaktCandidates: readonly EmailMatchKontaktCandidate[];
|
||||
/** Lead ids whose email equals the counterpart address. */
|
||||
readonly leadCandidateIds: readonly string[];
|
||||
/** Open Projekt ids per candidate Kontakt (wonAt/lostAt/archivedAt all null). */
|
||||
readonly openProjekteByKontaktId: Readonly<Record<string, readonly string[]>>;
|
||||
}
|
||||
|
||||
export type EmailMatchConfidence = "high" | "medium" | "low" | "manual" | "none";
|
||||
|
||||
export interface EmailMatchResult {
|
||||
readonly matchedKontaktId: string | null;
|
||||
readonly matchedLeadId: string | null;
|
||||
readonly matchedProjektId: string | null;
|
||||
readonly confidence: EmailMatchConfidence;
|
||||
/** The address the CRM lookup keyed on (Klartext/debug metadata). */
|
||||
readonly counterpartAddress: string | null;
|
||||
}
|
||||
|
||||
const NO_MATCH: EmailMatchResult = {
|
||||
matchedKontaktId: null,
|
||||
matchedLeadId: null,
|
||||
matchedProjektId: null,
|
||||
confidence: "none",
|
||||
counterpartAddress: null,
|
||||
};
|
||||
|
||||
/** Extract the Projekt number from a `[Projekt #123]` subject token (M09 E). */
|
||||
export function extractSubjectProjektNummer(subject: string | null | undefined): string | null {
|
||||
if (!subject) return null;
|
||||
const match = subject.match(/\[\s*Projekt\s*#\s*([\w-]+)\s*\]/i);
|
||||
return match ? match[1] : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The counterpart address of a message: sender for inbound, first recipient
|
||||
* that is NOT one of the tenant's own mailboxes for outbound.
|
||||
*/
|
||||
export function counterpartAddress(input: Pick<EmailMatchInput, "direction" | "fromAddress" | "toAddresses" | "ownAddresses">): string | null {
|
||||
const own = new Set(input.ownAddresses.map((a) => a.toLowerCase()));
|
||||
if (input.direction === "inbound") {
|
||||
const from = input.fromAddress.toLowerCase();
|
||||
return from && !own.has(from) ? from : null;
|
||||
}
|
||||
for (const recipient of input.toAddresses) {
|
||||
const address = recipient.address.toLowerCase();
|
||||
if (address && !own.has(address)) {
|
||||
return address;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function decideEmailMatch(input: EmailMatchInput): EmailMatchResult {
|
||||
if (input.isNewsletter) {
|
||||
return NO_MATCH;
|
||||
}
|
||||
const address = counterpartAddress(input);
|
||||
|
||||
// Kontakt: exact email match; primary-address contact wins on duplicates.
|
||||
let kontaktId: string | null = null;
|
||||
if (address && input.kontaktCandidates.length > 0) {
|
||||
const primary = input.kontaktCandidates.find((c) => c.primaer);
|
||||
kontaktId = (primary ?? input.kontaktCandidates[0]).kontaktId;
|
||||
}
|
||||
|
||||
// Lead: only when no Kontakt matched (a promoted lead lives on as Kontakt).
|
||||
const leadId = !kontaktId && address && input.leadCandidateIds.length > 0 ? input.leadCandidateIds[0] : null;
|
||||
|
||||
// Projekt: subject token wins (high); else the 1-open-Projekt heuristic.
|
||||
let projektId = input.subjectProjektId;
|
||||
let projektConfidence: EmailMatchConfidence | null = projektId ? "high" : null;
|
||||
if (!projektId && kontaktId) {
|
||||
const open = input.openProjekteByKontaktId[kontaktId] ?? [];
|
||||
if (open.length === 1) {
|
||||
projektId = open[0];
|
||||
projektConfidence = "medium";
|
||||
}
|
||||
}
|
||||
|
||||
if (!kontaktId && !leadId && !projektId) {
|
||||
return { ...NO_MATCH, counterpartAddress: address };
|
||||
}
|
||||
|
||||
// Overall confidence: the weakest link that produced a target — a heuristic
|
||||
// Projekt makes the whole match medium; direct matches are high.
|
||||
const confidence: EmailMatchConfidence = projektConfidence === "medium" && !input.subjectProjektId ? "medium" : "high";
|
||||
|
||||
return {
|
||||
matchedKontaktId: kontaktId,
|
||||
matchedLeadId: leadId,
|
||||
matchedProjektId: projektId,
|
||||
confidence,
|
||||
counterpartAddress: address,
|
||||
};
|
||||
}
|
||||
+200
@@ -0,0 +1,200 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
buildRfc2822Message,
|
||||
mapGmailMessage,
|
||||
mapGraphMessage,
|
||||
normalizeInternetMessageId,
|
||||
parseAddressList,
|
||||
toBase64Url,
|
||||
} from "./email-message-mapping.js";
|
||||
import type { GmailMessage } from "./google/gmailApi.js";
|
||||
import type { GraphMessage } from "./microsoft/graphMailApi.js";
|
||||
|
||||
// VA-P23 — the provider → neutral mapping is shared by web adapters and the
|
||||
// worker sync engine; these tests pin header parsing, MIME walking, direction,
|
||||
// newsletter detection, and the RFC-2822 builder (threading headers).
|
||||
|
||||
function b64url(value: string): string {
|
||||
return Buffer.from(value, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
||||
}
|
||||
|
||||
describe("parseAddressList", () => {
|
||||
it("parses named, bare, and quoted addresses", () => {
|
||||
expect(parseAddressList('Alice Example <A@X.de>, b@y.de, "Meier, Hans" <hans@meier.de>')).toEqual([
|
||||
{ address: "a@x.de", name: "Alice Example" },
|
||||
{ address: "b@y.de" },
|
||||
{ address: "hans@meier.de", name: "Meier, Hans" },
|
||||
]);
|
||||
});
|
||||
|
||||
it("returns empty for null/garbage", () => {
|
||||
expect(parseAddressList(null)).toEqual([]);
|
||||
expect(parseAddressList("no-address-here")).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("normalizeInternetMessageId", () => {
|
||||
it("strips angle brackets and whitespace", () => {
|
||||
expect(normalizeInternetMessageId(" <abc@mail.example> ")).toBe("abc@mail.example");
|
||||
expect(normalizeInternetMessageId(null)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("mapGmailMessage", () => {
|
||||
const gmailFixture: GmailMessage = {
|
||||
id: "gm1",
|
||||
threadId: "gt1",
|
||||
labelIds: ["INBOX", "UNREAD"],
|
||||
snippet: "Hallo, kurze Frage zur Wartung",
|
||||
internalDate: "1751400000000",
|
||||
payload: {
|
||||
mimeType: "multipart/mixed",
|
||||
headers: [
|
||||
{ name: "From", value: "Max Mustermann <max@kunde.de>" },
|
||||
{ name: "To", value: "info@handwerk.de" },
|
||||
{ name: "Subject", value: "Anfrage Wartung" },
|
||||
{ name: "Message-ID", value: "<msg-1@kunde.de>" },
|
||||
],
|
||||
parts: [
|
||||
{
|
||||
mimeType: "multipart/alternative",
|
||||
parts: [
|
||||
{ mimeType: "text/plain", body: { data: b64url("Hallo, kurze Frage zur Wartung.") } },
|
||||
{ mimeType: "text/html", body: { data: b64url("<p>Hallo, kurze Frage zur Wartung.</p>") } },
|
||||
],
|
||||
},
|
||||
{ mimeType: "application/pdf", filename: "angebot.pdf", body: { attachmentId: "att1", size: 12345 } },
|
||||
],
|
||||
},
|
||||
};
|
||||
|
||||
it("maps headers, bodies, attachments, and read/direction state", () => {
|
||||
const mapped = mapGmailMessage(gmailFixture);
|
||||
expect(mapped.providerMessageId).toBe("gm1");
|
||||
expect(mapped.providerThreadId).toBe("gt1");
|
||||
expect(mapped.internetMessageId).toBe("msg-1@kunde.de");
|
||||
expect(mapped.direction).toBe("inbound");
|
||||
expect(mapped.from).toEqual({ address: "max@kunde.de", name: "Max Mustermann" });
|
||||
expect(mapped.to).toEqual([{ address: "info@handwerk.de" }]);
|
||||
expect(mapped.subject).toBe("Anfrage Wartung");
|
||||
expect(mapped.bodyHtml).toBe("<p>Hallo, kurze Frage zur Wartung.</p>");
|
||||
expect(mapped.bodyText).toBe("Hallo, kurze Frage zur Wartung.");
|
||||
expect(mapped.isRead).toBe(false);
|
||||
expect(mapped.hasAttachments).toBe(true);
|
||||
expect(mapped.attachments).toEqual([{ attachmentId: "att1", filename: "angebot.pdf", mimeType: "application/pdf", sizeBytes: 12345 }]);
|
||||
expect(mapped.sentAt).toEqual(new Date(1751400000000));
|
||||
expect(mapped.isNewsletter).toBe(false);
|
||||
});
|
||||
|
||||
it("marks SENT-labelled messages outbound and read", () => {
|
||||
const mapped = mapGmailMessage({ ...gmailFixture, labelIds: ["SENT"] });
|
||||
expect(mapped.direction).toBe("outbound");
|
||||
expect(mapped.isRead).toBe(true);
|
||||
expect(mapped.receivedAt).toBeNull();
|
||||
});
|
||||
|
||||
it("flags a List-Unsubscribe header as newsletter", () => {
|
||||
const withHeader: GmailMessage = {
|
||||
...gmailFixture,
|
||||
payload: {
|
||||
...gmailFixture.payload!,
|
||||
headers: [...(gmailFixture.payload!.headers ?? []), { name: "List-Unsubscribe", value: "<mailto:unsub@news.de>" }],
|
||||
},
|
||||
};
|
||||
expect(mapGmailMessage(withHeader).isNewsletter).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("mapGraphMessage", () => {
|
||||
const graphFixture: GraphMessage = {
|
||||
id: "ms1",
|
||||
conversationId: "conv1",
|
||||
internetMessageId: "<msg-2@kunde.de>",
|
||||
subject: "Re: Anfrage Wartung",
|
||||
bodyPreview: "Danke, passt!",
|
||||
body: { contentType: "html", content: "<p>Danke, passt!</p>" },
|
||||
from: { emailAddress: { address: "Max@Kunde.de", name: "Max Mustermann" } },
|
||||
toRecipients: [{ emailAddress: { address: "info@handwerk.de" } }],
|
||||
sentDateTime: "2026-07-01T10:00:00Z",
|
||||
receivedDateTime: "2026-07-01T10:00:05Z",
|
||||
isRead: true,
|
||||
hasAttachments: false,
|
||||
};
|
||||
|
||||
it("maps a Graph inbox message", () => {
|
||||
const mapped = mapGraphMessage(graphFixture, "inbox");
|
||||
expect(mapped.providerMessageId).toBe("ms1");
|
||||
expect(mapped.providerThreadId).toBe("conv1");
|
||||
expect(mapped.internetMessageId).toBe("msg-2@kunde.de");
|
||||
expect(mapped.direction).toBe("inbound");
|
||||
expect(mapped.from).toEqual({ address: "max@kunde.de", name: "Max Mustermann" });
|
||||
expect(mapped.bodyHtml).toBe("<p>Danke, passt!</p>");
|
||||
expect(mapped.bodyText).toBeNull();
|
||||
expect(mapped.isRead).toBe(true);
|
||||
expect(mapped.receivedAt).toEqual(new Date("2026-07-01T10:00:05Z"));
|
||||
});
|
||||
|
||||
it("derives outbound direction from the sentitems folder", () => {
|
||||
expect(mapGraphMessage(graphFixture, "sentitems").direction).toBe("outbound");
|
||||
});
|
||||
|
||||
it("detects a newsletter only when internetMessageHeaders carry List-Unsubscribe", () => {
|
||||
expect(mapGraphMessage(graphFixture, "inbox").isNewsletter).toBe(false);
|
||||
const withHeaders: GraphMessage = {
|
||||
...graphFixture,
|
||||
internetMessageHeaders: [{ name: "List-Unsubscribe", value: "<https://news.de/unsub>" }],
|
||||
};
|
||||
expect(mapGraphMessage(withHeaders, "inbox").isNewsletter).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildRfc2822Message", () => {
|
||||
it("builds threading headers and encodes the html body", () => {
|
||||
const raw = buildRfc2822Message({
|
||||
fromAddress: "info@handwerk.de",
|
||||
to: [{ address: "max@kunde.de", name: "Max" }],
|
||||
subject: "Re: Anfrage",
|
||||
bodyHtml: "<p>Gern!</p>",
|
||||
inReplyToInternetMessageId: "msg-1@kunde.de",
|
||||
referencesInternetMessageIds: ["msg-0@kunde.de", "msg-1@kunde.de"],
|
||||
});
|
||||
expect(raw).toContain("From: info@handwerk.de");
|
||||
expect(raw).toContain("To: Max <max@kunde.de>");
|
||||
expect(raw).toContain("In-Reply-To: <msg-1@kunde.de>");
|
||||
expect(raw).toContain("References: <msg-0@kunde.de> <msg-1@kunde.de>");
|
||||
expect(raw).toContain(Buffer.from("<p>Gern!</p>", "utf8").toString("base64"));
|
||||
});
|
||||
|
||||
it("wraps attachments in a multipart/mixed envelope", () => {
|
||||
const raw = buildRfc2822Message({
|
||||
fromAddress: "info@handwerk.de",
|
||||
to: [{ address: "max@kunde.de" }],
|
||||
subject: "Angebot",
|
||||
bodyHtml: "<p>Anbei</p>",
|
||||
attachments: [{ filename: "angebot.pdf", mimeType: "application/pdf", contentBase64: "QUJD" }],
|
||||
});
|
||||
expect(raw).toContain("multipart/mixed");
|
||||
expect(raw).toContain('filename="angebot.pdf"');
|
||||
expect(raw).toContain("QUJD");
|
||||
});
|
||||
|
||||
it("mime-encodes non-ascii subjects and names", () => {
|
||||
const raw = buildRfc2822Message({
|
||||
fromAddress: "info@handwerk.de",
|
||||
to: [{ address: "max@kunde.de", name: "Müller GmbH" }],
|
||||
subject: "Rückfrage Wärmepumpe",
|
||||
bodyHtml: "<p>x</p>",
|
||||
});
|
||||
expect(raw).toContain(`Subject: =?UTF-8?B?${Buffer.from("Rückfrage Wärmepumpe", "utf8").toString("base64")}?=`);
|
||||
expect(raw).toContain("=?UTF-8?B?");
|
||||
});
|
||||
});
|
||||
|
||||
describe("toBase64Url", () => {
|
||||
it("produces url-safe base64 without padding", () => {
|
||||
const encoded = toBase64Url("a?b>c");
|
||||
expect(encoded).not.toMatch(/[+/=]/);
|
||||
expect(Buffer.from(encoded.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8")).toBe("a?b>c");
|
||||
});
|
||||
});
|
||||
+302
@@ -0,0 +1,302 @@
|
||||
// VA-P23 · provider → neutral message mapping (shared web + worker).
|
||||
//
|
||||
// Pure functions: GmailMessage (MIME payload walk) and GraphMessage map into the
|
||||
// SAME neutral shape the EmailIntegrationMessage row is written from. Living in
|
||||
// @hivegrid/integrations so the apps/web provider adapters AND the worker sync
|
||||
// tasks share one mapping (no drift between the connect-time and cron-time sync).
|
||||
|
||||
import type { GmailMessage, GmailMessagePart } from "./google/gmailApi.js";
|
||||
import type { GraphMessage } from "./microsoft/graphMailApi.js";
|
||||
|
||||
export interface MappedEmailAddress {
|
||||
readonly address: string;
|
||||
readonly name?: string;
|
||||
}
|
||||
|
||||
export interface MappedEmailAttachment {
|
||||
readonly attachmentId: string;
|
||||
readonly filename: string;
|
||||
readonly mimeType: string | null;
|
||||
readonly sizeBytes: number;
|
||||
}
|
||||
|
||||
/** The neutral message shape (field-compatible with EmailIntegrationMessage). */
|
||||
export interface MappedEmailMessage {
|
||||
readonly providerMessageId: string;
|
||||
readonly providerThreadId: string | null;
|
||||
/** RFC-5322 Message-ID (angle brackets stripped) — cross-provider dedupe key. */
|
||||
readonly internetMessageId: string | null;
|
||||
readonly direction: "inbound" | "outbound";
|
||||
readonly from: MappedEmailAddress;
|
||||
readonly to: readonly MappedEmailAddress[];
|
||||
readonly cc: readonly MappedEmailAddress[];
|
||||
readonly bcc: readonly MappedEmailAddress[];
|
||||
readonly subject: string | null;
|
||||
readonly snippet: string | null;
|
||||
readonly bodyHtml: string | null;
|
||||
readonly bodyText: string | null;
|
||||
readonly sentAt: Date;
|
||||
readonly receivedAt: Date | null;
|
||||
readonly isRead: boolean;
|
||||
readonly hasAttachments: boolean;
|
||||
/** True when a List-Unsubscribe header marks a newsletter/bulk sender (M09 E). */
|
||||
readonly isNewsletter: boolean;
|
||||
readonly providerLabels: readonly string[];
|
||||
readonly attachments: readonly MappedEmailAttachment[];
|
||||
}
|
||||
|
||||
const SNIPPET_MAX = 140;
|
||||
|
||||
/** Normalize an RFC-5322 Message-ID: strip angle brackets + whitespace. */
|
||||
export function normalizeInternetMessageId(value: string | null | undefined): string | null {
|
||||
if (!value) return null;
|
||||
const trimmed = value.trim().replace(/^<|>$/g, "").trim();
|
||||
return trimmed.length > 0 ? trimmed : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse an RFC-5322 address list ("Alice <a@x.de>, b@y.de"). Deliberately
|
||||
* simple: split on commas outside quotes/brackets, extract `<addr>` or a bare
|
||||
* address. Display names keep their content, quotes stripped.
|
||||
*/
|
||||
export function parseAddressList(value: string | null | undefined): MappedEmailAddress[] {
|
||||
if (!value) return [];
|
||||
const parts: string[] = [];
|
||||
let depth = 0;
|
||||
let inQuotes = false;
|
||||
let current = "";
|
||||
for (const char of value) {
|
||||
if (char === '"') inQuotes = !inQuotes;
|
||||
if (!inQuotes) {
|
||||
if (char === "<" || char === "(") depth += 1;
|
||||
if (char === ">" || char === ")") depth = Math.max(0, depth - 1);
|
||||
if (char === "," && depth === 0) {
|
||||
parts.push(current);
|
||||
current = "";
|
||||
continue;
|
||||
}
|
||||
}
|
||||
current += char;
|
||||
}
|
||||
if (current.trim()) parts.push(current);
|
||||
|
||||
const result: MappedEmailAddress[] = [];
|
||||
for (const raw of parts) {
|
||||
const piece = raw.trim();
|
||||
if (!piece) continue;
|
||||
const angled = piece.match(/^(.*?)<([^<>]+)>\s*$/);
|
||||
if (angled) {
|
||||
const name = angled[1].trim().replace(/^"|"$/g, "").trim();
|
||||
const address = angled[2].trim().toLowerCase();
|
||||
if (address.includes("@")) {
|
||||
result.push(name ? { address, name } : { address });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const bare = piece.replace(/^"|"$/g, "").trim().toLowerCase();
|
||||
if (bare.includes("@")) {
|
||||
result.push({ address: bare });
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function buildSnippet(preferred: string | null | undefined, fallbackText: string | null): string | null {
|
||||
const source = (preferred ?? "").trim() || (fallbackText ?? "").replace(/\s+/g, " ").trim();
|
||||
if (!source) return null;
|
||||
return source.length > SNIPPET_MAX ? `${source.slice(0, SNIPPET_MAX - 1)}…` : source;
|
||||
}
|
||||
|
||||
// --- Gmail -------------------------------------------------------------------
|
||||
|
||||
function base64UrlDecode(data: string): string {
|
||||
const pad = data.length % 4 === 0 ? "" : "=".repeat(4 - (data.length % 4));
|
||||
return Buffer.from(data.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8");
|
||||
}
|
||||
|
||||
function headerValue(headers: ReadonlyArray<{ name: string; value: string }> | undefined, name: string): string | null {
|
||||
const match = (headers ?? []).find((h) => h.name.toLowerCase() === name.toLowerCase());
|
||||
return match?.value ?? null;
|
||||
}
|
||||
|
||||
interface GmailBodyWalk {
|
||||
html: string | null;
|
||||
text: string | null;
|
||||
attachments: MappedEmailAttachment[];
|
||||
}
|
||||
|
||||
function walkParts(part: GmailMessagePart | undefined, acc: GmailBodyWalk): void {
|
||||
if (!part) return;
|
||||
const mime = part.mimeType ?? "";
|
||||
if (part.filename && part.body?.attachmentId) {
|
||||
acc.attachments.push({
|
||||
attachmentId: part.body.attachmentId,
|
||||
filename: part.filename,
|
||||
mimeType: mime || null,
|
||||
sizeBytes: part.body.size ?? 0,
|
||||
});
|
||||
} else if (mime === "text/html" && part.body?.data && acc.html === null) {
|
||||
acc.html = base64UrlDecode(part.body.data);
|
||||
} else if (mime === "text/plain" && part.body?.data && acc.text === null) {
|
||||
acc.text = base64UrlDecode(part.body.data);
|
||||
}
|
||||
for (const child of part.parts ?? []) {
|
||||
walkParts(child, acc);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Map a Gmail message (format=full) into the neutral shape. Direction comes from
|
||||
* the SENT label; read state from the absence of UNREAD.
|
||||
*/
|
||||
export function mapGmailMessage(message: GmailMessage): MappedEmailMessage {
|
||||
const headers = message.payload?.headers;
|
||||
const walk: GmailBodyWalk = { html: null, text: null, attachments: [] };
|
||||
walkParts(message.payload, walk);
|
||||
|
||||
const labels = message.labelIds ?? [];
|
||||
const from = parseAddressList(headerValue(headers, "From"))[0] ?? { address: "" };
|
||||
const sentAtMs = message.internalDate ? Number(message.internalDate) : NaN;
|
||||
const dateHeader = headerValue(headers, "Date");
|
||||
const sentAt = Number.isFinite(sentAtMs) ? new Date(sentAtMs) : dateHeader ? new Date(dateHeader) : new Date(0);
|
||||
|
||||
return {
|
||||
providerMessageId: message.id,
|
||||
providerThreadId: message.threadId ?? null,
|
||||
internetMessageId: normalizeInternetMessageId(headerValue(headers, "Message-ID") ?? headerValue(headers, "Message-Id")),
|
||||
direction: labels.includes("SENT") ? "outbound" : "inbound",
|
||||
from,
|
||||
to: parseAddressList(headerValue(headers, "To")),
|
||||
cc: parseAddressList(headerValue(headers, "Cc")),
|
||||
bcc: parseAddressList(headerValue(headers, "Bcc")),
|
||||
subject: headerValue(headers, "Subject"),
|
||||
snippet: buildSnippet(message.snippet, walk.text),
|
||||
bodyHtml: walk.html,
|
||||
bodyText: walk.text,
|
||||
sentAt,
|
||||
receivedAt: labels.includes("SENT") ? null : sentAt,
|
||||
isRead: !labels.includes("UNREAD"),
|
||||
hasAttachments: walk.attachments.length > 0,
|
||||
isNewsletter: headerValue(headers, "List-Unsubscribe") !== null,
|
||||
providerLabels: labels,
|
||||
attachments: walk.attachments,
|
||||
};
|
||||
}
|
||||
|
||||
// --- Microsoft Graph -----------------------------------------------------------
|
||||
|
||||
function graphAddress(entry: { emailAddress?: { address?: string; name?: string } } | undefined): MappedEmailAddress | null {
|
||||
const address = entry?.emailAddress?.address?.toLowerCase();
|
||||
if (!address) return null;
|
||||
const name = entry?.emailAddress?.name;
|
||||
return name ? { address, name } : { address };
|
||||
}
|
||||
|
||||
function graphAddresses(list: ReadonlyArray<{ emailAddress?: { address?: string; name?: string } }> | undefined): MappedEmailAddress[] {
|
||||
return (list ?? []).map(graphAddress).filter((a): a is MappedEmailAddress => a !== null);
|
||||
}
|
||||
|
||||
/**
|
||||
* Map a Graph message into the neutral shape. Direction is derived from the
|
||||
* folder the delta ran on (`sentitems` → outbound) — Graph messages carry no
|
||||
* SENT label. `isNewsletter` needs internetMessageHeaders (only present on a
|
||||
* single-message fetch with $expand) — false when absent.
|
||||
*/
|
||||
export function mapGraphMessage(message: GraphMessage, folderId: string): MappedEmailMessage {
|
||||
const isHtml = (message.body?.contentType ?? "").toLowerCase() === "html";
|
||||
const bodyContent = message.body?.content ?? null;
|
||||
const listUnsubscribe = (message.internetMessageHeaders ?? []).some((h) => (h.name ?? "").toLowerCase() === "list-unsubscribe");
|
||||
const sentAt = message.sentDateTime ? new Date(message.sentDateTime) : new Date(0);
|
||||
const direction: MappedEmailMessage["direction"] = folderId === "sentitems" ? "outbound" : "inbound";
|
||||
|
||||
return {
|
||||
providerMessageId: message.id,
|
||||
providerThreadId: message.conversationId ?? null,
|
||||
internetMessageId: normalizeInternetMessageId(message.internetMessageId),
|
||||
direction,
|
||||
from: graphAddress(message.from) ?? { address: "" },
|
||||
to: graphAddresses(message.toRecipients),
|
||||
cc: graphAddresses(message.ccRecipients),
|
||||
bcc: graphAddresses(message.bccRecipients),
|
||||
subject: message.subject ?? null,
|
||||
snippet: buildSnippet(message.bodyPreview, isHtml ? null : bodyContent),
|
||||
bodyHtml: isHtml ? bodyContent : null,
|
||||
bodyText: isHtml ? null : bodyContent,
|
||||
sentAt,
|
||||
receivedAt: message.receivedDateTime ? new Date(message.receivedDateTime) : null,
|
||||
isRead: message.isRead ?? false,
|
||||
hasAttachments: message.hasAttachments ?? false,
|
||||
isNewsletter: listUnsubscribe,
|
||||
providerLabels: [folderId],
|
||||
// Graph attachments are listed via a separate call (listGraphAttachments).
|
||||
attachments: [],
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Build an RFC-2822 raw message for the Gmail send path (base64url encoding is
|
||||
* the caller's job). Minimal MIME: multipart/mixed when attachments are present,
|
||||
* otherwise a single text/html part. Threading headers (In-Reply-To/References)
|
||||
* keep replies in the recipient's thread (M09 Block G).
|
||||
*/
|
||||
export function buildRfc2822Message(input: {
|
||||
readonly fromAddress: string;
|
||||
readonly fromName?: string;
|
||||
readonly to: readonly MappedEmailAddress[];
|
||||
readonly cc?: readonly MappedEmailAddress[];
|
||||
readonly bcc?: readonly MappedEmailAddress[];
|
||||
readonly subject: string;
|
||||
readonly bodyHtml: string;
|
||||
readonly inReplyToInternetMessageId?: string | null;
|
||||
readonly referencesInternetMessageIds?: readonly string[];
|
||||
readonly attachments?: ReadonlyArray<{ filename: string; mimeType: string; contentBase64: string }>;
|
||||
}): string {
|
||||
const encodeWord = (value: string): string =>
|
||||
/[^\x20-\x7e]/.test(value) ? `=?UTF-8?B?${Buffer.from(value, "utf8").toString("base64")}?=` : value;
|
||||
const formatAddress = (a: MappedEmailAddress): string => (a.name ? `${encodeWord(a.name)} <${a.address}>` : a.address);
|
||||
|
||||
const headers: string[] = [
|
||||
`From: ${formatAddress({ address: input.fromAddress, name: input.fromName })}`,
|
||||
`To: ${input.to.map(formatAddress).join(", ")}`,
|
||||
];
|
||||
if (input.cc?.length) headers.push(`Cc: ${input.cc.map(formatAddress).join(", ")}`);
|
||||
if (input.bcc?.length) headers.push(`Bcc: ${input.bcc.map(formatAddress).join(", ")}`);
|
||||
headers.push(`Subject: ${encodeWord(input.subject)}`);
|
||||
if (input.inReplyToInternetMessageId) {
|
||||
headers.push(`In-Reply-To: <${input.inReplyToInternetMessageId}>`);
|
||||
}
|
||||
if (input.referencesInternetMessageIds?.length) {
|
||||
headers.push(`References: ${input.referencesInternetMessageIds.map((id) => `<${id}>`).join(" ")}`);
|
||||
}
|
||||
headers.push("MIME-Version: 1.0");
|
||||
|
||||
const htmlPart = `Content-Type: text/html; charset="UTF-8"\r\nContent-Transfer-Encoding: base64\r\n\r\n${Buffer.from(input.bodyHtml, "utf8").toString("base64")}`;
|
||||
|
||||
if (!input.attachments?.length) {
|
||||
return `${headers.join("\r\n")}\r\n${htmlPart}`;
|
||||
}
|
||||
|
||||
const boundary = `hg_${Math.abs(hashCode(input.subject + input.fromAddress + String(input.to.length)))}_mime`;
|
||||
headers.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
|
||||
const attachmentParts = input.attachments
|
||||
.map(
|
||||
(a) =>
|
||||
`--${boundary}\r\nContent-Type: ${a.mimeType}; name="${a.filename}"\r\nContent-Disposition: attachment; filename="${a.filename}"\r\nContent-Transfer-Encoding: base64\r\n\r\n${a.contentBase64}`,
|
||||
)
|
||||
.join("\r\n");
|
||||
return `${headers.join("\r\n")}\r\n\r\n--${boundary}\r\n${htmlPart}\r\n${attachmentParts}\r\n--${boundary}--`;
|
||||
}
|
||||
|
||||
function hashCode(value: string): number {
|
||||
let hash = 0;
|
||||
for (let i = 0; i < value.length; i += 1) {
|
||||
hash = (hash << 5) - hash + value.charCodeAt(i);
|
||||
hash |= 0;
|
||||
}
|
||||
return hash;
|
||||
}
|
||||
|
||||
/** Base64url-encode a raw RFC-2822 message for Gmail messages.send. */
|
||||
export function toBase64Url(raw: string): string {
|
||||
return Buffer.from(raw, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
|
||||
}
|
||||
+374
@@ -0,0 +1,374 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
EMAIL_GMAIL_FOLDER,
|
||||
cleanupEmailWebhookEventsForTenant,
|
||||
drainEmailWebhookEventsForTenant,
|
||||
pollStaleEmailMailboxesForTenant,
|
||||
renewEmailWebhooksForTenant,
|
||||
runEmailInitialSyncForTenant,
|
||||
syncMailboxIncremental,
|
||||
upsertNeutralMessage,
|
||||
type EmailWorkerClient,
|
||||
} from "./email-worker-tasks.server.js";
|
||||
import type { MappedEmailMessage } from "./email-message-mapping.js";
|
||||
|
||||
// VA-P23 — sync-engine tests (Prisma + provider fetch mocked): delta drain,
|
||||
// resumable initial sync, renewal thresholds for BOTH providers, dedupe.
|
||||
|
||||
const mocks = vi.hoisted(() => {
|
||||
class MockGmailError extends Error {
|
||||
readonly code: string;
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: string) {
|
||||
super(code);
|
||||
this.name = "GmailError";
|
||||
this.code = code;
|
||||
this.fullResyncRequired = code === "history_expired";
|
||||
}
|
||||
}
|
||||
class MockGraphMailError extends Error {
|
||||
readonly code: string;
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: string) {
|
||||
super(code);
|
||||
this.name = "GraphMailError";
|
||||
this.code = code;
|
||||
this.fullResyncRequired = code === "delta_token_invalid";
|
||||
}
|
||||
}
|
||||
return {
|
||||
MockGmailError,
|
||||
MockGraphMailError,
|
||||
listHistory: vi.fn(),
|
||||
listMessageIds: vi.fn(),
|
||||
getGmailMessage: vi.fn(),
|
||||
watchMailbox: vi.fn(),
|
||||
refreshGmailAccessToken: vi.fn(),
|
||||
fetchDeltaPage: vi.fn(),
|
||||
renewMailSubscription: vi.fn(),
|
||||
createMailSubscription: vi.fn(),
|
||||
refreshMicrosoftAccessToken: vi.fn(),
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock("./google/gmailApi.js", () => ({
|
||||
GmailError: mocks.MockGmailError,
|
||||
getMessage: mocks.getGmailMessage,
|
||||
listHistory: mocks.listHistory,
|
||||
listMessageIds: mocks.listMessageIds,
|
||||
refreshGmailAccessToken: mocks.refreshGmailAccessToken,
|
||||
resolveGmailOAuthConfig: vi.fn(() => ({ clientId: "id", clientSecret: "s", redirectUri: "https://x", pubsubTopic: "projects/p/topics/t" })),
|
||||
watchMailbox: mocks.watchMailbox,
|
||||
}));
|
||||
|
||||
vi.mock("./microsoft/graphMailApi.js", () => ({
|
||||
GraphMailError: mocks.MockGraphMailError,
|
||||
buildInitialDeltaUrl: vi.fn((folderId: string) => `https://graph/delta/${folderId}`),
|
||||
createMailSubscription: mocks.createMailSubscription,
|
||||
fetchDeltaPage: mocks.fetchDeltaPage,
|
||||
refreshMicrosoftAccessToken: mocks.refreshMicrosoftAccessToken,
|
||||
renewMailSubscription: mocks.renewMailSubscription,
|
||||
resolveMicrosoftMailOAuthConfig: vi.fn(() => ({ clientId: "id", clientSecret: "s", redirectUri: "https://x", tenant: "common" })),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/crypto/tenant-envelope.server", () => ({
|
||||
decryptTenantField: vi.fn(async (_tenantId: string, ciphertext: string) => (ciphertext.includes("refresh") ? "refresh-token" : "access-token")),
|
||||
encryptTenantField: vi.fn(async (_tenantId: string, value: string) => `sealed:${value}`),
|
||||
}));
|
||||
|
||||
const NOW = new Date("2026-07-02T10:00:00.000Z");
|
||||
|
||||
function mappedMessage(overrides: Partial<MappedEmailMessage> = {}): MappedEmailMessage {
|
||||
return {
|
||||
providerMessageId: "pm1",
|
||||
providerThreadId: "th1",
|
||||
internetMessageId: "rfc-1@x.de",
|
||||
direction: "inbound",
|
||||
from: { address: "max@kunde.de" },
|
||||
to: [{ address: "info@handwerk.de" }],
|
||||
cc: [],
|
||||
bcc: [],
|
||||
subject: "Anfrage",
|
||||
snippet: "Anfrage",
|
||||
bodyHtml: "<p>Hi</p>",
|
||||
bodyText: "Hi",
|
||||
sentAt: NOW,
|
||||
receivedAt: NOW,
|
||||
isRead: false,
|
||||
hasAttachments: false,
|
||||
isNewsletter: false,
|
||||
providerLabels: ["INBOX"],
|
||||
attachments: [],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
type MailboxOverrides = Partial<{
|
||||
id: string;
|
||||
provider: "gmail" | "microsoft";
|
||||
status: string;
|
||||
webhookSubscriptionId: string | null;
|
||||
webhookSubscriptionExpiresAt: Date | null;
|
||||
webhookClientState: string | null;
|
||||
lastSyncAt: Date | null;
|
||||
}>;
|
||||
|
||||
function mailboxRow(overrides: MailboxOverrides = {}) {
|
||||
return {
|
||||
id: "mb1",
|
||||
tenantId: "t1",
|
||||
ownerUserId: "u1",
|
||||
provider: "gmail" as const,
|
||||
emailAddress: "info@handwerk.de",
|
||||
oauthRefreshTokenCiphertext: "sealed-refresh",
|
||||
oauthAccessTokenCiphertext: "sealed-access",
|
||||
oauthAccessTokenExpiresAt: new Date("2026-07-02T11:00:00.000Z"),
|
||||
webhookSubscriptionId: "sub1",
|
||||
webhookSubscriptionExpiresAt: new Date("2026-07-05T10:00:00.000Z"),
|
||||
webhookClientState: "cs1",
|
||||
status: "active" as const,
|
||||
lastSyncAt: new Date("2026-07-02T09:00:00.000Z"),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function createClient(opts: {
|
||||
mailboxes?: ReturnType<typeof mailboxRow>[];
|
||||
cursors?: Array<Record<string, unknown>>;
|
||||
existingMessage?: { id: string; providerMessageId: string } | null;
|
||||
existingByRfc?: { id: string; providerMessageId: string } | null;
|
||||
webhookEvents?: Array<{ id: string; tenantId: string; mailboxId: string }>;
|
||||
}) {
|
||||
const mailboxes = opts.mailboxes ?? [mailboxRow()];
|
||||
const cursors = opts.cursors ?? [];
|
||||
const client = {
|
||||
emailIntegrationMailbox: {
|
||||
findMany: vi.fn<(args: Record<string, unknown>) => Promise<typeof mailboxes>>(async () => mailboxes),
|
||||
findFirst: vi.fn(async (args: { where?: { id?: string } }) => mailboxes.find((m) => !args?.where?.id || m.id === args.where.id) ?? null),
|
||||
updateMany: vi.fn<(args: Record<string, unknown>) => Promise<{ count: number }>>(async () => ({ count: 1 })),
|
||||
},
|
||||
emailIntegrationMessage: {
|
||||
findFirst: vi.fn(async (args: { where?: { internetMessageId?: string } }) =>
|
||||
args?.where?.internetMessageId ? (opts.existingByRfc ?? null) : (opts.existingMessage ?? null),
|
||||
),
|
||||
create: vi.fn<(args: Record<string, unknown>) => Promise<{ id: string; providerMessageId: string }>>(async () => ({ id: "msg-new", providerMessageId: "pm1" })),
|
||||
updateMany: vi.fn<(args: Record<string, unknown>) => Promise<{ count: number }>>(async () => ({ count: 1 })),
|
||||
},
|
||||
emailIntegrationSyncCursor: {
|
||||
findMany: vi.fn<(args: Record<string, unknown>) => Promise<typeof cursors>>(async () => cursors),
|
||||
findFirst: vi.fn(async (args: { where?: { externalFolderId?: string } }) =>
|
||||
(cursors.find((c) => !args?.where?.externalFolderId || c.externalFolderId === args.where.externalFolderId) as never) ?? null,
|
||||
),
|
||||
updateMany: vi.fn<(args: Record<string, unknown>) => Promise<{ count: number }>>(async () => ({ count: 1 })),
|
||||
upsert: vi.fn<(args: Record<string, unknown>) => Promise<Record<string, never>>>(async () => ({})),
|
||||
},
|
||||
emailIntegrationWebhookEvent: {
|
||||
findMany: vi.fn<(args: Record<string, unknown>) => Promise<Array<{ id: string; tenantId: string; mailboxId: string }>>>(async () => opts.webhookEvents ?? []),
|
||||
update: vi.fn<(args: Record<string, unknown>) => Promise<Record<string, never>>>(async () => ({})),
|
||||
updateMany: vi.fn<(args: Record<string, unknown>) => Promise<{ count: number }>>(async () => ({ count: 1 })),
|
||||
deleteMany: vi.fn<(args: Record<string, unknown>) => Promise<{ count: number }>>(async () => ({ count: 2 })),
|
||||
},
|
||||
};
|
||||
return client as unknown as EmailWorkerClient & typeof client;
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
describe("upsertNeutralMessage", () => {
|
||||
it("creates a new row when nothing matches", async () => {
|
||||
const client = createClient({ existingMessage: null, existingByRfc: null });
|
||||
const result = await upsertNeutralMessage(client, { tenantId: "t1", mailboxId: "mb1" }, mappedMessage());
|
||||
expect(result).toEqual({ id: "msg-new", created: true });
|
||||
expect(client.emailIntegrationMessage.create).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("adopts the provider id onto an existing row matched by internetMessageId (Graph 202 mirror)", async () => {
|
||||
const client = createClient({ existingByRfc: { id: "local-mirror", providerMessageId: "local-tmp" } });
|
||||
const result = await upsertNeutralMessage(client, { tenantId: "t1", mailboxId: "mb1" }, mappedMessage({ providerMessageId: "graph-real" }));
|
||||
expect(result).toEqual({ id: "local-mirror", created: false });
|
||||
const updateArgs = client.emailIntegrationMessage.updateMany.mock.calls[0][0] as unknown as { data: { providerMessageId: string } };
|
||||
expect(updateArgs.data.providerMessageId).toBe("graph-real");
|
||||
});
|
||||
|
||||
it("updates an existing row matched by providerMessageId", async () => {
|
||||
const client = createClient({ existingMessage: { id: "row1", providerMessageId: "pm1" } });
|
||||
const result = await upsertNeutralMessage(client, { tenantId: "t1", mailboxId: "mb1" }, mappedMessage({ internetMessageId: null }));
|
||||
expect(result).toEqual({ id: "row1", created: false });
|
||||
expect(client.emailIntegrationMessage.create).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("syncMailboxIncremental (gmail)", () => {
|
||||
it("drains history pages and advances the cursor", async () => {
|
||||
const client = createClient({ cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: "100", initialSyncStatus: "completed", initialSyncProgress: null }] });
|
||||
mocks.listHistory
|
||||
.mockResolvedValueOnce({ addedMessageIds: ["g1"], nextPageToken: "p2", historyId: "150" })
|
||||
.mockResolvedValueOnce({ addedMessageIds: ["g2"], historyId: "200" });
|
||||
mocks.getGmailMessage.mockResolvedValue({ id: "g1", threadId: "t", labelIds: ["INBOX"], payload: { headers: [{ name: "From", value: "a@b.de" }] }, internalDate: String(NOW.getTime()) });
|
||||
|
||||
const result = await syncMailboxIncremental(client, "t1", "mb1", { now: NOW });
|
||||
expect(result.upserted).toBe(2);
|
||||
expect(mocks.listHistory).toHaveBeenCalledTimes(2);
|
||||
const cursorUpdate = client.emailIntegrationSyncCursor.updateMany.mock.calls.at(-1)?.[0] as unknown as { data: { cursorToken: string } };
|
||||
expect(cursorUpdate.data.cursorToken).toBe("200");
|
||||
});
|
||||
|
||||
it("resets the cursor for a bounded resync when the historyId expired", async () => {
|
||||
const client = createClient({ cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: "1", initialSyncStatus: "completed", initialSyncProgress: null }] });
|
||||
mocks.listHistory.mockRejectedValueOnce(new mocks.MockGmailError("history_expired"));
|
||||
const result = await syncMailboxIncremental(client, "t1", "mb1", { now: NOW });
|
||||
expect(result.resyncScheduled).toBe(true);
|
||||
const resetCall = client.emailIntegrationSyncCursor.updateMany.mock.calls[0][0] as unknown as { data: { cursorToken: null; initialSyncStatus: string } };
|
||||
expect(resetCall.data.cursorToken).toBeNull();
|
||||
expect(resetCall.data.initialSyncStatus).toBe("pending");
|
||||
});
|
||||
});
|
||||
|
||||
describe("syncMailboxIncremental (microsoft)", () => {
|
||||
it("drains per-folder deltas and stores the new deltaLink", async () => {
|
||||
const client = createClient({
|
||||
mailboxes: [mailboxRow({ provider: "microsoft" })],
|
||||
cursors: [
|
||||
{ id: "c1", mailboxId: "mb1", externalFolderId: "inbox", cursorToken: "https://graph/delta-inbox", initialSyncStatus: "completed", initialSyncProgress: null },
|
||||
{ id: "c2", mailboxId: "mb1", externalFolderId: "sentitems", cursorToken: null, initialSyncStatus: "pending", initialSyncProgress: null },
|
||||
],
|
||||
});
|
||||
mocks.fetchDeltaPage.mockResolvedValueOnce({
|
||||
messages: [{ id: "m1", conversationId: "c", sentDateTime: NOW.toISOString(), from: { emailAddress: { address: "a@b.de" } } }],
|
||||
deltaLink: "https://graph/delta-inbox-next",
|
||||
});
|
||||
const result = await syncMailboxIncremental(client, "t1", "mb1", { now: NOW });
|
||||
expect(result.upserted).toBe(1);
|
||||
// Only the inbox folder had a cursor — sentitems waits for the initial sync.
|
||||
expect(mocks.fetchDeltaPage).toHaveBeenCalledTimes(1);
|
||||
const cursorUpdate = client.emailIntegrationSyncCursor.updateMany.mock.calls.at(-1)?.[0] as unknown as { data: { cursorToken: string } };
|
||||
expect(cursorUpdate.data.cursorToken).toBe("https://graph/delta-inbox-next");
|
||||
});
|
||||
});
|
||||
|
||||
describe("runEmailInitialSyncForTenant", () => {
|
||||
it("persists resumable progress when more pages remain", async () => {
|
||||
const client = createClient({ cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: null, initialSyncStatus: "pending", initialSyncProgress: null }] });
|
||||
// Always another page → the run hits the per-run page cap and persists pageToken.
|
||||
mocks.listMessageIds.mockResolvedValue({ messageIds: ["g1"], nextPageToken: "next-page" });
|
||||
mocks.getGmailMessage.mockResolvedValue({ id: "g1", labelIds: ["INBOX"], payload: { headers: [{ name: "From", value: "a@b.de" }] }, internalDate: String(NOW.getTime()) });
|
||||
|
||||
const result = await runEmailInitialSyncForTenant(client, "t1", { now: NOW });
|
||||
expect(result.completed).toBe(0);
|
||||
expect(result.fetched).toBe(5); // 5 pages per run × 1 message
|
||||
const progressUpdate = client.emailIntegrationSyncCursor.updateMany.mock.calls.at(-1)?.[0] as unknown as {
|
||||
data: { initialSyncStatus: string; initialSyncProgress: { pageToken: string; fetchedCount: number } };
|
||||
};
|
||||
expect(progressUpdate.data.initialSyncStatus).toBe("running");
|
||||
expect(progressUpdate.data.initialSyncProgress.pageToken).toBe("next-page");
|
||||
expect(progressUpdate.data.initialSyncProgress.fetchedCount).toBe(5);
|
||||
});
|
||||
|
||||
it("resumes from the persisted pageToken and completes when pages end", async () => {
|
||||
const client = createClient({
|
||||
cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: null, initialSyncStatus: "running", initialSyncProgress: { pageToken: "resume-here", fetchedCount: 40 } }],
|
||||
});
|
||||
mocks.listMessageIds.mockResolvedValueOnce({ messageIds: ["g9"], nextPageToken: undefined });
|
||||
mocks.getGmailMessage.mockResolvedValue({ id: "g9", labelIds: ["INBOX"], payload: { headers: [{ name: "From", value: "a@b.de" }] }, internalDate: String(NOW.getTime()) });
|
||||
|
||||
const result = await runEmailInitialSyncForTenant(client, "t1", { now: NOW });
|
||||
expect(mocks.listMessageIds.mock.calls[0][1]).toMatchObject({ pageToken: "resume-here" });
|
||||
expect(result.completed).toBe(1);
|
||||
const completedUpdate = client.emailIntegrationSyncCursor.updateMany.mock.calls.at(-1)?.[0] as unknown as {
|
||||
data: { initialSyncStatus: string; initialSyncProgress: { fetchedCount: number; percent: number } };
|
||||
};
|
||||
expect(completedUpdate.data.initialSyncStatus).toBe("completed");
|
||||
expect(completedUpdate.data.initialSyncProgress.fetchedCount).toBe(41);
|
||||
expect(completedUpdate.data.initialSyncProgress.percent).toBe(100);
|
||||
});
|
||||
|
||||
it("marks the folder failed with a redacted Klartext error on provider failure", async () => {
|
||||
const client = createClient({ cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: null, initialSyncStatus: "pending", initialSyncProgress: null }] });
|
||||
mocks.listMessageIds.mockRejectedValueOnce(new mocks.MockGmailError("provider_outage"));
|
||||
const result = await runEmailInitialSyncForTenant(client, "t1", { now: NOW });
|
||||
expect(result.failed).toBe(1);
|
||||
const failedUpdate = client.emailIntegrationSyncCursor.updateMany.mock.calls.at(-1)?.[0] as unknown as { data: { initialSyncStatus: string } };
|
||||
expect(failedUpdate.data.initialSyncStatus).toBe("failed");
|
||||
});
|
||||
|
||||
it("completes a Graph folder and promotes the deltaLink to the incremental cursor", async () => {
|
||||
const client = createClient({
|
||||
mailboxes: [mailboxRow({ provider: "microsoft" })],
|
||||
cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: "inbox", cursorToken: null, initialSyncStatus: "pending", initialSyncProgress: null }],
|
||||
});
|
||||
mocks.fetchDeltaPage.mockResolvedValueOnce({ messages: [], deltaLink: "https://graph/final-delta" });
|
||||
const result = await runEmailInitialSyncForTenant(client, "t1", { now: NOW });
|
||||
expect(result.completed).toBe(1);
|
||||
const cursorPromotion = client.emailIntegrationSyncCursor.updateMany.mock.calls[0][0] as unknown as { data: { cursorToken: string } };
|
||||
expect(cursorPromotion.data.cursorToken).toBe("https://graph/final-delta");
|
||||
});
|
||||
});
|
||||
|
||||
describe("renewEmailWebhooksForTenant", () => {
|
||||
it("re-issues the Gmail watch when the expiry is inside the threshold", async () => {
|
||||
const client = createClient({ mailboxes: [mailboxRow({ webhookSubscriptionExpiresAt: new Date("2026-07-02T20:00:00.000Z") })] });
|
||||
mocks.watchMailbox.mockResolvedValueOnce({ historyId: "999", expiresAt: new Date("2026-07-09T10:00:00.000Z") });
|
||||
const result = await renewEmailWebhooksForTenant(client, "t1", { now: NOW });
|
||||
expect(result.renewed).toBe(1);
|
||||
expect(mocks.watchMailbox).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("skips mailboxes whose subscription is still comfortably valid", async () => {
|
||||
const client = createClient({ mailboxes: [mailboxRow({ webhookSubscriptionExpiresAt: new Date("2026-07-08T10:00:00.000Z") })] });
|
||||
const result = await renewEmailWebhooksForTenant(client, "t1", { now: NOW });
|
||||
expect(result.renewed).toBe(0);
|
||||
expect(result.skipped).toBe(1);
|
||||
});
|
||||
|
||||
it("renews a Graph subscription and re-creates it when Microsoft already dropped it", async () => {
|
||||
const client = createClient({ mailboxes: [mailboxRow({ provider: "microsoft", webhookSubscriptionExpiresAt: new Date("2026-07-02T20:00:00.000Z") })] });
|
||||
mocks.renewMailSubscription.mockRejectedValueOnce(new mocks.MockGraphMailError("subscription_failed"));
|
||||
mocks.createMailSubscription.mockResolvedValueOnce({ id: "sub-new", expiresAt: new Date("2026-07-05T10:00:00.000Z") });
|
||||
const result = await renewEmailWebhooksForTenant(client, "t1", { now: NOW, graphWebhookUrl: "https://app/webhooks/email/microsoft" });
|
||||
expect(result.renewed).toBe(1);
|
||||
expect(mocks.createMailSubscription).toHaveBeenCalledWith("access-token", "https://app/webhooks/email/microsoft", "cs1");
|
||||
});
|
||||
});
|
||||
|
||||
describe("drain + stale poll + cleanup", () => {
|
||||
it("collapses multiple pushes for one mailbox into a single incremental sync", async () => {
|
||||
const client = createClient({
|
||||
cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: "100", initialSyncStatus: "completed", initialSyncProgress: null }],
|
||||
webhookEvents: [
|
||||
{ id: "e1", tenantId: "t1", mailboxId: "mb1" },
|
||||
{ id: "e2", tenantId: "t1", mailboxId: "mb1" },
|
||||
],
|
||||
});
|
||||
mocks.listHistory.mockResolvedValue({ addedMessageIds: [], historyId: "101" });
|
||||
const result = await drainEmailWebhookEventsForTenant(client, "t1", { now: NOW });
|
||||
expect(result.claimed).toBe(2);
|
||||
expect(result.completed).toBe(2);
|
||||
// history.list ran once, not per event.
|
||||
expect(mocks.listHistory).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("polls only mailboxes silent for the stale window", async () => {
|
||||
const client = createClient({
|
||||
mailboxes: [mailboxRow({ lastSyncAt: new Date("2026-07-02T04:00:00.000Z") })],
|
||||
cursors: [{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: "100", initialSyncStatus: "completed", initialSyncProgress: null }],
|
||||
});
|
||||
mocks.listHistory.mockResolvedValue({ addedMessageIds: [], historyId: "101" });
|
||||
const result = await pollStaleEmailMailboxesForTenant(client, "t1", { now: NOW });
|
||||
expect(result.polled).toBe(1);
|
||||
const where = client.emailIntegrationMailbox.findMany.mock.calls[0][0] as unknown as { where: { lastSyncAt: { lte: Date } } };
|
||||
expect(where.where.lastSyncAt.lte).toEqual(new Date("2026-07-02T06:00:00.000Z"));
|
||||
});
|
||||
|
||||
it("cleans up done events after 30d and failed after 90d", async () => {
|
||||
const client = createClient({});
|
||||
const result = await cleanupEmailWebhookEventsForTenant(client, "t1", { now: NOW });
|
||||
expect(result.deleted).toBe(4);
|
||||
const doneCall = client.emailIntegrationWebhookEvent.deleteMany.mock.calls[0][0] as unknown as { where: { receivedAt: { lte: Date } } };
|
||||
const failedCall = client.emailIntegrationWebhookEvent.deleteMany.mock.calls[1][0] as unknown as { where: { receivedAt: { lte: Date } } };
|
||||
expect(doneCall.where.receivedAt.lte).toEqual(new Date("2026-06-02T10:00:00.000Z"));
|
||||
expect(failedCall.where.receivedAt.lte).toEqual(new Date("2026-04-03T10:00:00.000Z"));
|
||||
});
|
||||
});
|
||||
+736
@@ -0,0 +1,736 @@
|
||||
// VA-P23 (P23) email-inbox worker tasks. Shared by apps/worker so the background
|
||||
// sync engine runs without importing apps/web modules (mirror of
|
||||
// calendar-worker-tasks.server.ts). Provider I/O goes through the raw clients
|
||||
// (gmailApi/graphMailApi) + the shared neutral mapping — the same mapping the
|
||||
// web adapters use, so connect-time and cron-time sync cannot drift.
|
||||
//
|
||||
// Responsibilities (M09 Block D):
|
||||
// - refreshEmailTokensForTenant — access-token refresh window sweep
|
||||
// - renewEmailWebhooksForTenant — Graph subscription (~3d) AND Gmail watch
|
||||
// (~7d) renewal, keyed by webhookSubscriptionExpiresAt
|
||||
// - drainEmailWebhookEventsForTenant — claim pending pushes → incremental sync
|
||||
// - runEmailInitialSyncForTenant — bounded 90-day backfill, RESUMABLE via the
|
||||
// per-folder cursor progress JSON
|
||||
// - pollStaleEmailMailboxesForTenant — 4h-silence fallback poll (safety net,
|
||||
// push stays the primary channel)
|
||||
// - cleanupEmailWebhookEventsForTenant — 30d retention (failed: 90d)
|
||||
|
||||
import { decryptTenantField, encryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
|
||||
import {
|
||||
GmailError,
|
||||
getMessage as getGmailMessage,
|
||||
listHistory,
|
||||
listMessageIds,
|
||||
refreshGmailAccessToken,
|
||||
resolveGmailOAuthConfig,
|
||||
watchMailbox,
|
||||
} from "./google/gmailApi.js";
|
||||
import {
|
||||
GraphMailError,
|
||||
buildInitialDeltaUrl,
|
||||
createMailSubscription,
|
||||
fetchDeltaPage,
|
||||
refreshMicrosoftAccessToken,
|
||||
renewMailSubscription,
|
||||
resolveMicrosoftMailOAuthConfig,
|
||||
} from "./microsoft/graphMailApi.js";
|
||||
import { mapGmailMessage, mapGraphMessage, type MappedEmailMessage } from "./email-message-mapping.js";
|
||||
|
||||
export const EMAIL_GMAIL_FOLDER = "*";
|
||||
export const EMAIL_GRAPH_FOLDERS = ["inbox", "sentitems"] as const;
|
||||
|
||||
const DEFAULT_TAKE = 25;
|
||||
const INITIAL_SYNC_DAYS = 90;
|
||||
/** Pages per initial-sync run per folder — keeps a run bounded + resumable. */
|
||||
const INITIAL_SYNC_MAX_PAGES_PER_RUN = 5;
|
||||
/** Estimated total for the Klartext percent line when the provider gives one. */
|
||||
const WEBHOOK_RETENTION_DAYS = 30;
|
||||
const WEBHOOK_FAILED_RETENTION_DAYS = 90;
|
||||
|
||||
type EmailProvider = "gmail" | "microsoft";
|
||||
|
||||
type EmailMailboxRow = {
|
||||
id: string;
|
||||
tenantId: string;
|
||||
ownerUserId: string;
|
||||
provider: EmailProvider;
|
||||
emailAddress: string;
|
||||
oauthRefreshTokenCiphertext: string | null;
|
||||
oauthAccessTokenCiphertext: string | null;
|
||||
oauthAccessTokenExpiresAt: Date | null;
|
||||
webhookSubscriptionId: string | null;
|
||||
webhookSubscriptionExpiresAt: Date | null;
|
||||
webhookClientState: string | null;
|
||||
status: "connecting" | "active" | "paused" | "error" | "revoked";
|
||||
lastSyncAt: Date | null;
|
||||
};
|
||||
|
||||
type EmailSyncCursorRow = {
|
||||
id: string;
|
||||
mailboxId: string;
|
||||
externalFolderId: string;
|
||||
cursorToken: string | null;
|
||||
initialSyncStatus: "pending" | "running" | "completed" | "failed";
|
||||
initialSyncProgress: unknown;
|
||||
};
|
||||
|
||||
type EmailWebhookEventRow = {
|
||||
id: string;
|
||||
tenantId: string;
|
||||
mailboxId: string;
|
||||
};
|
||||
|
||||
type EmailMessageIdRow = { id: string; providerMessageId: string };
|
||||
|
||||
export type EmailWorkerClient = {
|
||||
emailIntegrationMailbox: {
|
||||
findMany(args: Record<string, unknown>): Promise<EmailMailboxRow[]>;
|
||||
findFirst(args: Record<string, unknown>): Promise<EmailMailboxRow | null>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
};
|
||||
emailIntegrationMessage: {
|
||||
findFirst(args: Record<string, unknown>): Promise<EmailMessageIdRow | null>;
|
||||
create(args: Record<string, unknown>): Promise<EmailMessageIdRow>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
};
|
||||
emailIntegrationSyncCursor: {
|
||||
findMany(args: Record<string, unknown>): Promise<EmailSyncCursorRow[]>;
|
||||
findFirst(args: Record<string, unknown>): Promise<EmailSyncCursorRow | null>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
upsert(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
emailIntegrationWebhookEvent: {
|
||||
findMany(args: Record<string, unknown>): Promise<EmailWebhookEventRow[]>;
|
||||
update(args: Record<string, unknown>): Promise<unknown>;
|
||||
updateMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
deleteMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
};
|
||||
};
|
||||
|
||||
type EmailCreds = {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt: Date | null;
|
||||
};
|
||||
|
||||
const MAILBOX_SELECT = {
|
||||
id: true,
|
||||
tenantId: true,
|
||||
ownerUserId: true,
|
||||
provider: true,
|
||||
emailAddress: true,
|
||||
oauthRefreshTokenCiphertext: true,
|
||||
oauthAccessTokenCiphertext: true,
|
||||
oauthAccessTokenExpiresAt: true,
|
||||
webhookSubscriptionId: true,
|
||||
webhookSubscriptionExpiresAt: true,
|
||||
webhookClientState: true,
|
||||
status: true,
|
||||
lastSyncAt: true,
|
||||
} as const;
|
||||
|
||||
async function loadCreds(client: EmailWorkerClient, tenantId: string, mailboxId: string): Promise<EmailCreds | null> {
|
||||
const row = await client.emailIntegrationMailbox.findFirst({
|
||||
where: { id: mailboxId, tenantId, archivedAt: null },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
if (!row?.oauthRefreshTokenCiphertext || !row.oauthAccessTokenCiphertext) {
|
||||
return null;
|
||||
}
|
||||
const [refreshToken, accessToken] = await Promise.all([
|
||||
decryptTenantField(tenantId, row.oauthRefreshTokenCiphertext, { client: client as never }),
|
||||
decryptTenantField(tenantId, row.oauthAccessTokenCiphertext, { client: client as never }),
|
||||
]);
|
||||
return { refreshToken, accessToken, expiresAt: row.oauthAccessTokenExpiresAt };
|
||||
}
|
||||
|
||||
async function refreshProviderTokens(provider: EmailProvider, refreshToken: string) {
|
||||
if (provider === "gmail") {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) throw new GmailError("not_configured");
|
||||
return refreshGmailAccessToken(config, refreshToken);
|
||||
}
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) throw new GraphMailError("not_configured");
|
||||
return refreshMicrosoftAccessToken(config, refreshToken);
|
||||
}
|
||||
|
||||
async function ensureFreshCreds(
|
||||
client: EmailWorkerClient,
|
||||
mailbox: { id: string; tenantId: string; provider: EmailProvider },
|
||||
creds: EmailCreds,
|
||||
now = new Date(),
|
||||
): Promise<EmailCreds> {
|
||||
if (creds.expiresAt && creds.expiresAt.getTime() > now.getTime() + 60_000) {
|
||||
return creds;
|
||||
}
|
||||
const refreshed = await refreshProviderTokens(mailbox.provider, creds.refreshToken);
|
||||
const nextRefreshToken = refreshed.refreshToken ?? creds.refreshToken;
|
||||
const [accessCiphertext, refreshCiphertext] = await Promise.all([
|
||||
encryptTenantField(mailbox.tenantId, refreshed.accessToken, { client: client as never }),
|
||||
encryptTenantField(mailbox.tenantId, nextRefreshToken, { client: client as never }),
|
||||
]);
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: mailbox.id, tenantId: mailbox.tenantId },
|
||||
data: {
|
||||
oauthAccessTokenCiphertext: accessCiphertext,
|
||||
oauthRefreshTokenCiphertext: refreshCiphertext,
|
||||
oauthAccessTokenExpiresAt: refreshed.expiresAt,
|
||||
status: "active",
|
||||
lastErrorText: null,
|
||||
},
|
||||
});
|
||||
return { accessToken: refreshed.accessToken, refreshToken: nextRefreshToken, expiresAt: refreshed.expiresAt };
|
||||
}
|
||||
|
||||
/**
|
||||
* Hook invoked after every message upsert — S6 wires the auto-match + activity
|
||||
* logging through this seam so the sync engine stays match-agnostic.
|
||||
*/
|
||||
export type EmailMessageUpsertedHook = (input: {
|
||||
client: EmailWorkerClient;
|
||||
tenantId: string;
|
||||
mailboxId: string;
|
||||
ownerUserId: string;
|
||||
ownerEmailAddress: string;
|
||||
messageId: string;
|
||||
created: boolean;
|
||||
message: MappedEmailMessage;
|
||||
}) => Promise<void>;
|
||||
|
||||
/**
|
||||
* Upsert one neutral message. Dedupe order (M09):
|
||||
* 1. internetMessageId within the mailbox (collapses the Graph sent-items
|
||||
* re-ingest onto the local outbound mirror; providerMessageId is adopted)
|
||||
* 2. the [tenantId, mailboxId, providerMessageId] unique key
|
||||
* Returns the row id + whether a new row was created.
|
||||
*/
|
||||
export async function upsertNeutralMessage(
|
||||
client: EmailWorkerClient,
|
||||
ctx: { tenantId: string; mailboxId: string },
|
||||
message: MappedEmailMessage,
|
||||
): Promise<{ id: string; created: boolean }> {
|
||||
const baseFields = {
|
||||
providerThreadId: message.providerThreadId,
|
||||
internetMessageId: message.internetMessageId,
|
||||
direction: message.direction,
|
||||
fromAddress: message.from.address,
|
||||
fromName: message.from.name ?? null,
|
||||
toAddresses: message.to as never,
|
||||
ccAddresses: message.cc as never,
|
||||
bccAddresses: message.bcc as never,
|
||||
subject: message.subject,
|
||||
snippet: message.snippet,
|
||||
bodyHtml: message.bodyHtml,
|
||||
bodyText: message.bodyText,
|
||||
sentAt: message.sentAt,
|
||||
receivedAt: message.receivedAt,
|
||||
isRead: message.isRead,
|
||||
isNewsletter: message.isNewsletter,
|
||||
hasAttachments: message.hasAttachments,
|
||||
providerLabels: message.providerLabels as never,
|
||||
};
|
||||
|
||||
if (message.internetMessageId) {
|
||||
const existingByRfcId = await client.emailIntegrationMessage.findFirst({
|
||||
where: { tenantId: ctx.tenantId, mailboxId: ctx.mailboxId, internetMessageId: message.internetMessageId },
|
||||
select: { id: true, providerMessageId: true },
|
||||
});
|
||||
if (existingByRfcId) {
|
||||
await client.emailIntegrationMessage.updateMany({
|
||||
where: { id: existingByRfcId.id, tenantId: ctx.tenantId },
|
||||
data: { ...baseFields, providerMessageId: message.providerMessageId },
|
||||
});
|
||||
return { id: existingByRfcId.id, created: false };
|
||||
}
|
||||
}
|
||||
|
||||
const existing = await client.emailIntegrationMessage.findFirst({
|
||||
where: { tenantId: ctx.tenantId, mailboxId: ctx.mailboxId, providerMessageId: message.providerMessageId },
|
||||
select: { id: true, providerMessageId: true },
|
||||
});
|
||||
if (existing) {
|
||||
await client.emailIntegrationMessage.updateMany({
|
||||
where: { id: existing.id, tenantId: ctx.tenantId },
|
||||
data: baseFields,
|
||||
});
|
||||
return { id: existing.id, created: false };
|
||||
}
|
||||
const created = await client.emailIntegrationMessage.create({
|
||||
data: { tenantId: ctx.tenantId, mailboxId: ctx.mailboxId, providerMessageId: message.providerMessageId, ...baseFields },
|
||||
});
|
||||
return { id: created.id, created: true };
|
||||
}
|
||||
|
||||
async function fetchGmailMapped(accessToken: string, messageIds: readonly string[]): Promise<MappedEmailMessage[]> {
|
||||
const mapped: MappedEmailMessage[] = [];
|
||||
for (const id of messageIds) {
|
||||
try {
|
||||
mapped.push(mapGmailMessage(await getGmailMessage(accessToken, id, "full")));
|
||||
} catch (error) {
|
||||
if (error instanceof GmailError && error.code === "message_not_found") {
|
||||
continue; // deleted between listing and fetching — not an error
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
return mapped;
|
||||
}
|
||||
|
||||
async function persistMessages(
|
||||
client: EmailWorkerClient,
|
||||
mailbox: EmailMailboxRow,
|
||||
messages: readonly MappedEmailMessage[],
|
||||
hook: EmailMessageUpsertedHook | undefined,
|
||||
): Promise<number> {
|
||||
let upserted = 0;
|
||||
for (const message of messages) {
|
||||
const result = await upsertNeutralMessage(client, { tenantId: mailbox.tenantId, mailboxId: mailbox.id }, message);
|
||||
upserted += 1;
|
||||
if (hook) {
|
||||
await hook({
|
||||
client,
|
||||
tenantId: mailbox.tenantId,
|
||||
mailboxId: mailbox.id,
|
||||
ownerUserId: mailbox.ownerUserId,
|
||||
ownerEmailAddress: mailbox.emailAddress,
|
||||
messageId: result.id,
|
||||
created: result.created,
|
||||
message,
|
||||
});
|
||||
}
|
||||
}
|
||||
return upserted;
|
||||
}
|
||||
|
||||
/** Reset a folder cursor for a bounded re-backfill after a provider 404/410. */
|
||||
async function resetCursorForResync(client: EmailWorkerClient, tenantId: string, mailboxId: string, externalFolderId: string): Promise<void> {
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { tenantId, mailboxId, externalFolderId },
|
||||
data: { cursorToken: null, initialSyncStatus: "pending", initialSyncProgress: null, errorText: null },
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Incremental sync of ONE mailbox (all its folders) from the stored cursors.
|
||||
* Gmail: history.list from the historyId anchor; Graph: delta per folder. An
|
||||
* expired cursor resets the folder to a bounded initial re-sync (next initial
|
||||
* run picks it up) instead of failing the drain.
|
||||
*/
|
||||
export async function syncMailboxIncremental(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
mailboxId: string,
|
||||
opts: { now?: Date; hook?: EmailMessageUpsertedHook } = {},
|
||||
): Promise<{ upserted: number; resyncScheduled: boolean }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const mailbox = await client.emailIntegrationMailbox.findFirst({
|
||||
where: { id: mailboxId, tenantId, archivedAt: null },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
if (!mailbox || mailbox.status === "revoked" || mailbox.status === "paused") {
|
||||
return { upserted: 0, resyncScheduled: false };
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, mailboxId);
|
||||
if (!baseCreds) {
|
||||
return { upserted: 0, resyncScheduled: false };
|
||||
}
|
||||
const creds = await ensureFreshCreds(client, mailbox, baseCreds, now);
|
||||
|
||||
let upserted = 0;
|
||||
let resyncScheduled = false;
|
||||
|
||||
if (mailbox.provider === "gmail") {
|
||||
const cursor = await client.emailIntegrationSyncCursor.findFirst({
|
||||
where: { tenantId, mailboxId, externalFolderId: EMAIL_GMAIL_FOLDER },
|
||||
select: { id: true, mailboxId: true, externalFolderId: true, cursorToken: true, initialSyncStatus: true, initialSyncProgress: true },
|
||||
});
|
||||
if (cursor?.cursorToken) {
|
||||
let pageToken: string | undefined;
|
||||
let latestHistoryId: string | undefined;
|
||||
try {
|
||||
do {
|
||||
const page = await listHistory(creds.accessToken, cursor.cursorToken, pageToken);
|
||||
upserted += await persistMessages(client, mailbox, await fetchGmailMapped(creds.accessToken, page.addedMessageIds), opts.hook);
|
||||
pageToken = page.nextPageToken;
|
||||
latestHistoryId = page.historyId ?? latestHistoryId;
|
||||
} while (pageToken);
|
||||
if (latestHistoryId) {
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { tenantId, mailboxId, externalFolderId: EMAIL_GMAIL_FOLDER },
|
||||
data: { cursorToken: latestHistoryId, lastCursorAdvanceAt: now },
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof GmailError && error.fullResyncRequired) {
|
||||
await resetCursorForResync(client, tenantId, mailboxId, EMAIL_GMAIL_FOLDER);
|
||||
resyncScheduled = true;
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
} else {
|
||||
for (const folderId of EMAIL_GRAPH_FOLDERS) {
|
||||
const cursor = await client.emailIntegrationSyncCursor.findFirst({
|
||||
where: { tenantId, mailboxId, externalFolderId: folderId },
|
||||
select: { id: true, mailboxId: true, externalFolderId: true, cursorToken: true, initialSyncStatus: true, initialSyncProgress: true },
|
||||
});
|
||||
if (!cursor?.cursorToken) {
|
||||
continue; // initial delta not completed yet — the initial-sync run owns it
|
||||
}
|
||||
let url: string | undefined = cursor.cursorToken;
|
||||
let newDeltaLink: string | undefined;
|
||||
try {
|
||||
while (url) {
|
||||
const page = await fetchDeltaPage(creds.accessToken, url);
|
||||
const mapped = page.messages.filter((m) => !m["@removed"]).map((m) => mapGraphMessage(m, folderId));
|
||||
upserted += await persistMessages(client, mailbox, mapped, opts.hook);
|
||||
url = page.nextLink;
|
||||
newDeltaLink = page.deltaLink ?? newDeltaLink;
|
||||
}
|
||||
if (newDeltaLink) {
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { tenantId, mailboxId, externalFolderId: folderId },
|
||||
data: { cursorToken: newDeltaLink, lastCursorAdvanceAt: now },
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof GraphMailError && error.fullResyncRequired) {
|
||||
await resetCursorForResync(client, tenantId, mailboxId, folderId);
|
||||
resyncScheduled = true;
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: mailboxId, tenantId },
|
||||
data: { lastSyncAt: now, status: "active", lastErrorText: null },
|
||||
});
|
||||
return { upserted, resyncScheduled };
|
||||
}
|
||||
|
||||
/**
|
||||
* Bounded, RESUMABLE initial sync (M09 Block D): processes at most
|
||||
* `INITIAL_SYNC_MAX_PAGES_PER_RUN` pages per pending/running folder cursor per
|
||||
* run and persists `{pageToken|nextLink, fetchedCount}` in the progress JSON so
|
||||
* an aborted run continues exactly where it stopped.
|
||||
*/
|
||||
export async function runEmailInitialSyncForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number; initialDays?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
): Promise<{ folders: number; fetched: number; completed: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const initialSince = new Date(now.getTime() - (opts.initialDays ?? INITIAL_SYNC_DAYS) * 86_400_000);
|
||||
const cursors = await client.emailIntegrationSyncCursor.findMany({
|
||||
where: { tenantId, initialSyncStatus: { in: ["pending", "running"] } },
|
||||
select: { id: true, mailboxId: true, externalFolderId: true, cursorToken: true, initialSyncStatus: true, initialSyncProgress: true },
|
||||
take: opts.take ?? DEFAULT_TAKE,
|
||||
});
|
||||
|
||||
let fetched = 0;
|
||||
let completed = 0;
|
||||
let failed = 0;
|
||||
|
||||
for (const cursor of cursors) {
|
||||
const mailbox = await client.emailIntegrationMailbox.findFirst({
|
||||
where: { id: cursor.mailboxId, tenantId, archivedAt: null },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
if (!mailbox || mailbox.status === "revoked" || mailbox.status === "paused") {
|
||||
continue;
|
||||
}
|
||||
const progress = (cursor.initialSyncProgress ?? {}) as { pageToken?: string; fetchedCount?: number };
|
||||
let pageToken: string | undefined = progress.pageToken;
|
||||
let fetchedCount = progress.fetchedCount ?? 0;
|
||||
|
||||
try {
|
||||
const baseCreds = await loadCreds(client, tenantId, mailbox.id);
|
||||
if (!baseCreds) {
|
||||
continue;
|
||||
}
|
||||
const creds = await ensureFreshCreds(client, mailbox, baseCreds, now);
|
||||
let done = false;
|
||||
|
||||
for (let page = 0; page < INITIAL_SYNC_MAX_PAGES_PER_RUN; page += 1) {
|
||||
if (mailbox.provider === "gmail") {
|
||||
const days = Math.max(1, Math.ceil((now.getTime() - initialSince.getTime()) / 86_400_000));
|
||||
const idPage = await listMessageIds(creds.accessToken, {
|
||||
q: `newer_than:${days}d -in:spam -in:trash`,
|
||||
pageToken,
|
||||
maxResults: 50,
|
||||
});
|
||||
const mapped = await fetchGmailMapped(creds.accessToken, idPage.messageIds);
|
||||
fetched += await persistMessages(client, mailbox, mapped, opts.hook);
|
||||
fetchedCount += mapped.length;
|
||||
pageToken = idPage.nextPageToken;
|
||||
} else {
|
||||
const url = pageToken ?? buildInitialDeltaUrl(cursor.externalFolderId, initialSince.toISOString());
|
||||
const deltaPage = await fetchDeltaPage(creds.accessToken, url);
|
||||
const mapped = deltaPage.messages.filter((m) => !m["@removed"]).map((m) => mapGraphMessage(m, cursor.externalFolderId));
|
||||
fetched += await persistMessages(client, mailbox, mapped, opts.hook);
|
||||
fetchedCount += mapped.length;
|
||||
pageToken = deltaPage.nextLink;
|
||||
if (!pageToken && deltaPage.deltaLink) {
|
||||
// Initial delta finished — the deltaLink becomes the incremental cursor.
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { id: cursor.id, tenantId },
|
||||
data: { cursorToken: deltaPage.deltaLink, lastCursorAdvanceAt: now },
|
||||
});
|
||||
}
|
||||
}
|
||||
if (!pageToken) {
|
||||
done = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { id: cursor.id, tenantId },
|
||||
data: done
|
||||
? { initialSyncStatus: "completed", initialSyncProgress: { fetchedCount, percent: 100 }, lastFullSyncAt: now, errorText: null }
|
||||
: { initialSyncStatus: "running", initialSyncProgress: { pageToken, fetchedCount }, errorText: null },
|
||||
});
|
||||
if (done) {
|
||||
completed += 1;
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: mailbox.id, tenantId },
|
||||
data: { lastSyncAt: now, status: "active", lastErrorText: null },
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
failed += 1;
|
||||
await client.emailIntegrationSyncCursor.updateMany({
|
||||
where: { id: cursor.id, tenantId },
|
||||
data: { initialSyncStatus: "failed", errorText: redactedError(error) },
|
||||
});
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: cursor.mailboxId, tenantId },
|
||||
data: { status: "error", lastErrorText: "emailInbox.health.unknown" },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { folders: cursors.length, fetched, completed, failed };
|
||||
}
|
||||
|
||||
/** Access-token refresh sweep (both providers; Graph rotates refresh tokens). */
|
||||
export async function refreshEmailTokensForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; windowMs?: number } = {},
|
||||
): Promise<{ refreshed: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const horizon = new Date(now.getTime() + (opts.windowMs ?? 10 * 60_000));
|
||||
const rows = await client.emailIntegrationMailbox.findMany({
|
||||
where: { tenantId, archivedAt: null, status: { in: ["active", "error", "connecting"] }, oauthAccessTokenExpiresAt: { not: null, lte: horizon } },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
let refreshed = 0;
|
||||
let failed = 0;
|
||||
for (const row of rows) {
|
||||
const creds = await loadCreds(client, tenantId, row.id);
|
||||
if (!creds) {
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
await ensureFreshCreds(client, row, creds, now);
|
||||
refreshed += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { status: "error", lastErrorText: "emailInbox.health.tokenExpired" },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { refreshed, failed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Push-subscription renewal for BOTH providers (Graph ~3 days, Gmail watch ~7
|
||||
* days), keyed by webhookSubscriptionExpiresAt within `thresholdMs`.
|
||||
*/
|
||||
export async function renewEmailWebhooksForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; thresholdMs?: number; graphWebhookUrl?: string } = {},
|
||||
): Promise<{ checked: number; renewed: number; failed: number; skipped: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const thresholdMs = opts.thresholdMs ?? 24 * 60 * 60_000;
|
||||
const rows = await client.emailIntegrationMailbox.findMany({
|
||||
where: { tenantId, archivedAt: null, status: "active" },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
|
||||
let renewed = 0;
|
||||
let failed = 0;
|
||||
let skipped = 0;
|
||||
for (const row of rows) {
|
||||
const needsRenewal =
|
||||
row.webhookSubscriptionId !== null &&
|
||||
(row.webhookSubscriptionExpiresAt === null || row.webhookSubscriptionExpiresAt.getTime() - now.getTime() <= thresholdMs);
|
||||
if (!needsRenewal) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, row.id);
|
||||
if (!baseCreds) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
const creds = await ensureFreshCreds(client, row, baseCreds, now);
|
||||
if (row.provider === "gmail") {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
const watch = await watchMailbox(creds.accessToken, config.pubsubTopic);
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { webhookSubscriptionExpiresAt: watch.expiresAt, lastErrorText: null },
|
||||
});
|
||||
} else {
|
||||
if (!opts.graphWebhookUrl || !row.webhookClientState) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
let subscription;
|
||||
try {
|
||||
subscription = await renewMailSubscription(creds.accessToken, row.webhookSubscriptionId ?? "");
|
||||
} catch (error) {
|
||||
// Expired at Microsoft → re-create with the stored clientState.
|
||||
if (error instanceof GraphMailError && error.code === "subscription_failed") {
|
||||
subscription = await createMailSubscription(creds.accessToken, opts.graphWebhookUrl, row.webhookClientState);
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { webhookSubscriptionId: subscription.id, webhookSubscriptionExpiresAt: subscription.expiresAt, lastErrorText: null },
|
||||
});
|
||||
}
|
||||
renewed += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { lastErrorText: "emailInbox.health.webhookSubscriptionFailed" },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { checked: rows.length, renewed, failed, skipped };
|
||||
}
|
||||
|
||||
/** Claim + process pending provider pushes (fast-ack rows from the webhook routes). */
|
||||
export async function drainEmailWebhookEventsForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
): Promise<{ claimed: number; completed: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const rows = await client.emailIntegrationWebhookEvent.findMany({
|
||||
where: { tenantId, processingStatus: "pending" },
|
||||
select: { id: true, tenantId: true, mailboxId: true },
|
||||
orderBy: { receivedAt: "asc" },
|
||||
take: opts.take ?? DEFAULT_TAKE,
|
||||
});
|
||||
let claimed = 0;
|
||||
let completed = 0;
|
||||
let failed = 0;
|
||||
// Multiple pushes for the same mailbox collapse into one incremental sync.
|
||||
const syncedMailboxes = new Set<string>();
|
||||
for (const row of rows) {
|
||||
const claim = await client.emailIntegrationWebhookEvent.updateMany({
|
||||
where: { id: row.id, tenantId, processingStatus: "pending" },
|
||||
data: { processingStatus: "processing" },
|
||||
});
|
||||
if (claim.count !== 1) {
|
||||
continue;
|
||||
}
|
||||
claimed += 1;
|
||||
try {
|
||||
if (!syncedMailboxes.has(row.mailboxId)) {
|
||||
await syncMailboxIncremental(client, tenantId, row.mailboxId, { now, hook: opts.hook });
|
||||
syncedMailboxes.add(row.mailboxId);
|
||||
}
|
||||
await client.emailIntegrationWebhookEvent.update({
|
||||
where: { id: row.id },
|
||||
data: { processingStatus: "completed", processedAt: now, processingErrorText: null },
|
||||
});
|
||||
completed += 1;
|
||||
} catch (error) {
|
||||
failed += 1;
|
||||
await client.emailIntegrationWebhookEvent.update({
|
||||
where: { id: row.id },
|
||||
data: { processingStatus: "failed", processedAt: now, processingErrorText: redactedError(error) },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { claimed, completed, failed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Fallback poll (M09 Block D): mailboxes that saw no successful sync for
|
||||
* `staleMs` (default 4h) get one incremental pull — the safety net when a push
|
||||
* channel silently dies. Push remains the primary mechanism.
|
||||
*/
|
||||
export async function pollStaleEmailMailboxesForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; staleMs?: number; take?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
): Promise<{ polled: number; failed: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const staleBefore = new Date(now.getTime() - (opts.staleMs ?? 4 * 60 * 60_000));
|
||||
const rows = await client.emailIntegrationMailbox.findMany({
|
||||
where: { tenantId, archivedAt: null, status: "active", lastSyncAt: { lte: staleBefore } },
|
||||
select: MAILBOX_SELECT,
|
||||
});
|
||||
let polled = 0;
|
||||
let failed = 0;
|
||||
for (const row of rows.slice(0, opts.take ?? DEFAULT_TAKE)) {
|
||||
try {
|
||||
await syncMailboxIncremental(client, tenantId, row.id, { now, hook: opts.hook });
|
||||
polled += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.emailIntegrationMailbox.updateMany({
|
||||
where: { id: row.id, tenantId },
|
||||
data: { status: "error", lastErrorText: "emailInbox.health.unknown" },
|
||||
});
|
||||
}
|
||||
}
|
||||
return { polled, failed };
|
||||
}
|
||||
|
||||
/** 30-day webhook-event retention (failed rows: 90 days for diagnosis). */
|
||||
export async function cleanupEmailWebhookEventsForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date } = {},
|
||||
): Promise<{ deleted: number }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const doneBefore = new Date(now.getTime() - WEBHOOK_RETENTION_DAYS * 86_400_000);
|
||||
const failedBefore = new Date(now.getTime() - WEBHOOK_FAILED_RETENTION_DAYS * 86_400_000);
|
||||
const done = await client.emailIntegrationWebhookEvent.deleteMany({
|
||||
where: { tenantId, processingStatus: { in: ["completed", "skipped"] }, receivedAt: { lte: doneBefore } },
|
||||
});
|
||||
const failedRows = await client.emailIntegrationWebhookEvent.deleteMany({
|
||||
where: { tenantId, processingStatus: "failed", receivedAt: { lte: failedBefore } },
|
||||
});
|
||||
return { deleted: done.count + failedRows.count };
|
||||
}
|
||||
|
||||
function redactedError(error: unknown): string {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return message
|
||||
.replace(/(authorization\s*:\s*Bearer\s+)\S+/gi, "$1[redacted]")
|
||||
.replace(/(token|secret|password)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]")
|
||||
.slice(0, 500);
|
||||
}
|
||||
+188
@@ -0,0 +1,188 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
GMAIL_SCOPES,
|
||||
GmailError,
|
||||
buildGmailAuthorizationUrl,
|
||||
exchangeGmailCodeForTokens,
|
||||
getMessage,
|
||||
listHistory,
|
||||
listMessageIds,
|
||||
modifyMessageLabels,
|
||||
refreshGmailAccessToken,
|
||||
resolveGmailOAuthConfig,
|
||||
revokeGmailToken,
|
||||
sendRawMessage,
|
||||
watchMailbox,
|
||||
} from "./gmailApi.js";
|
||||
|
||||
// VA-P23 — Gmail client unit tests. All network I/O is mocked; these pin the
|
||||
// request shapes (endpoints, params, bodies) and the Klartext error mapping.
|
||||
|
||||
const CONFIG = {
|
||||
clientId: "cid",
|
||||
clientSecret: "csecret",
|
||||
redirectUri: "https://app.hivegrid.de/integrations/email/google/oauth/callback",
|
||||
pubsubTopic: "projects/hg/topics/hivegrid-gmail-sync",
|
||||
};
|
||||
|
||||
function jsonResponse(status: number, body: unknown): Response {
|
||||
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
|
||||
}
|
||||
|
||||
let fetchMock: ReturnType<typeof vi.fn>;
|
||||
|
||||
beforeEach(() => {
|
||||
fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe("resolveGmailOAuthConfig", () => {
|
||||
it("returns null when any env key is missing", () => {
|
||||
expect(resolveGmailOAuthConfig({})).toBeNull();
|
||||
expect(resolveGmailOAuthConfig({ GOOGLE_GMAIL_CLIENT_ID: "x" })).toBeNull();
|
||||
});
|
||||
|
||||
it("resolves the full config incl. the Pub/Sub topic", () => {
|
||||
const env = {
|
||||
GOOGLE_GMAIL_CLIENT_ID: "cid",
|
||||
GOOGLE_GMAIL_CLIENT_SECRET: "cs",
|
||||
GOOGLE_GMAIL_REDIRECT_URI: "https://app.hivegrid.de/cb",
|
||||
GOOGLE_GMAIL_PUBSUB_TOPIC: "projects/p/topics/t",
|
||||
};
|
||||
expect(resolveGmailOAuthConfig(env)).toEqual({
|
||||
clientId: "cid",
|
||||
clientSecret: "cs",
|
||||
redirectUri: "https://app.hivegrid.de/cb",
|
||||
pubsubTopic: "projects/p/topics/t",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGmailAuthorizationUrl", () => {
|
||||
it("requests offline access with the restricted Gmail scopes and state", () => {
|
||||
const url = new URL(buildGmailAuthorizationUrl(CONFIG, "signed-state"));
|
||||
expect(url.origin + url.pathname).toBe("https://accounts.google.com/o/oauth2/v2/auth");
|
||||
expect(url.searchParams.get("scope")).toBe(GMAIL_SCOPES.join(" "));
|
||||
expect(url.searchParams.get("access_type")).toBe("offline");
|
||||
expect(url.searchParams.get("state")).toBe("signed-state");
|
||||
expect(url.searchParams.get("redirect_uri")).toBe(CONFIG.redirectUri);
|
||||
});
|
||||
});
|
||||
|
||||
describe("token exchange + refresh", () => {
|
||||
it("exchanges the code and parses the token set", async () => {
|
||||
fetchMock.mockResolvedValueOnce(
|
||||
jsonResponse(200, { access_token: "at", refresh_token: "rt", expires_in: 3600, scope: "a b" }),
|
||||
);
|
||||
const tokens = await exchangeGmailCodeForTokens(CONFIG, "the-code");
|
||||
expect(tokens.accessToken).toBe("at");
|
||||
expect(tokens.refreshToken).toBe("rt");
|
||||
expect(tokens.scopes).toEqual(["a", "b"]);
|
||||
const [url, init] = fetchMock.mock.calls[0];
|
||||
expect(url).toBe("https://oauth2.googleapis.com/token");
|
||||
expect(String(init.body)).toContain("grant_type=authorization_code");
|
||||
});
|
||||
|
||||
it("keeps the previous refresh token when Google omits it on refresh", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { access_token: "at2", expires_in: 3600 }));
|
||||
const tokens = await refreshGmailAccessToken(CONFIG, "old-rt");
|
||||
expect(tokens.refreshToken).toBe("old-rt");
|
||||
});
|
||||
|
||||
it("maps invalid_grant to auth_token_expired", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(400, { error: "invalid_grant" }));
|
||||
await expect(refreshGmailAccessToken(CONFIG, "dead")).rejects.toMatchObject({
|
||||
name: "GmailError",
|
||||
code: "auth_token_expired",
|
||||
});
|
||||
});
|
||||
|
||||
it("treats an already-revoked token as idempotent success on revoke", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(400, {}));
|
||||
await expect(revokeGmailToken("gone")).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("watchMailbox", () => {
|
||||
it("subscribes INBOX+SENT to the shared Pub/Sub topic and parses expiry", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { historyId: "100", expiration: "1750000000000" }));
|
||||
const watch = await watchMailbox("at", CONFIG.pubsubTopic);
|
||||
expect(watch.historyId).toBe("100");
|
||||
expect(watch.expiresAt).toEqual(new Date(1750000000000));
|
||||
const [url, init] = fetchMock.mock.calls[0];
|
||||
expect(url).toContain("/gmail/v1/users/me/watch");
|
||||
expect(JSON.parse(String(init.body))).toMatchObject({ topicName: CONFIG.pubsubTopic, labelIds: ["INBOX", "SENT"] });
|
||||
});
|
||||
|
||||
it("maps a failed watch to watch_subscription_failed", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(403, {}));
|
||||
await expect(watchMailbox("at", CONFIG.pubsubTopic)).rejects.toMatchObject({ code: "watch_subscription_failed" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("listHistory", () => {
|
||||
it("dedupes added message ids across history entries", async () => {
|
||||
fetchMock.mockResolvedValueOnce(
|
||||
jsonResponse(200, {
|
||||
history: [
|
||||
{ messagesAdded: [{ message: { id: "m1" } }, { message: { id: "m2" } }] },
|
||||
{ messagesAdded: [{ message: { id: "m2" } }] },
|
||||
],
|
||||
historyId: "222",
|
||||
}),
|
||||
);
|
||||
const page = await listHistory("at", "100");
|
||||
expect(page.addedMessageIds).toEqual(["m1", "m2"]);
|
||||
expect(page.historyId).toBe("222");
|
||||
});
|
||||
|
||||
it("marks an expired historyId (404) as fullResyncRequired", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(404, {}));
|
||||
const error = await listHistory("at", "1").catch((e: unknown) => e);
|
||||
expect(error).toBeInstanceOf(GmailError);
|
||||
expect((error as GmailError).code).toBe("history_expired");
|
||||
expect((error as GmailError).fullResyncRequired).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("messages", () => {
|
||||
it("lists message ids with the initial-sync query", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { messages: [{ id: "a" }, { id: "b" }], nextPageToken: "npt" }));
|
||||
const page = await listMessageIds("at", { q: "newer_than:90d", maxResults: 50 });
|
||||
expect(page.messageIds).toEqual(["a", "b"]);
|
||||
expect(page.nextPageToken).toBe("npt");
|
||||
const [url] = fetchMock.mock.calls[0];
|
||||
expect(String(url)).toContain("q=newer_than%3A90d");
|
||||
expect(String(url)).toContain("maxResults=50");
|
||||
});
|
||||
|
||||
it("fetches a message with the requested format", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { id: "m1", threadId: "t1" }));
|
||||
const message = await getMessage("at", "m1", "metadata");
|
||||
expect(message.threadId).toBe("t1");
|
||||
expect(String(fetchMock.mock.calls[0][0])).toContain("format=metadata");
|
||||
});
|
||||
|
||||
it("sends a raw message inside a thread", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { id: "sent1", threadId: "t9" }));
|
||||
const result = await sendRawMessage("at", "cmF3", "t9");
|
||||
expect(result).toEqual({ id: "sent1", threadId: "t9" });
|
||||
expect(JSON.parse(String(fetchMock.mock.calls[0][1].body))).toEqual({ raw: "cmF3", threadId: "t9" });
|
||||
});
|
||||
|
||||
it("modifies read state via label changes", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, {}));
|
||||
await modifyMessageLabels("at", "m1", { removeLabelIds: ["UNREAD"] });
|
||||
expect(JSON.parse(String(fetchMock.mock.calls[0][1].body))).toEqual({ addLabelIds: [], removeLabelIds: ["UNREAD"] });
|
||||
});
|
||||
|
||||
it("maps 429 to rate_limit_exceeded", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(429, {}));
|
||||
await expect(getMessage("at", "m1")).rejects.toMatchObject({ code: "rate_limit_exceeded" });
|
||||
});
|
||||
});
|
||||
+415
@@ -0,0 +1,415 @@
|
||||
// VA-P23 · Gmail REST/OAuth client (shared web + worker).
|
||||
//
|
||||
// Plain `fetch` against Google's public REST + OAuth2 endpoints — NO Google SDK
|
||||
// (EU-stack: the SDK is a US client lib; raw HTTPS to Google's API is the
|
||||
// accepted external provider boundary, same as googleCalendarApi.ts). This
|
||||
// module is provider-typed and pure of any app/Prisma import so both apps/web
|
||||
// (mailbox connect / send) and apps/worker (sync drain / renewal crons) use it.
|
||||
//
|
||||
// All errors are mapped to a stable `GmailErrorCode` (Klartext-ready, M002) —
|
||||
// never a bare provider status leaks to the UI. Gmail signals an expired
|
||||
// `historyId` with HTTP 404 on history.list → `fullResyncRequired`.
|
||||
|
||||
const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
|
||||
const OAUTH_REVOKE_URL = "https://oauth2.googleapis.com/revoke";
|
||||
const GMAIL_API_BASE = "https://gmail.googleapis.com/gmail/v1/users/me";
|
||||
|
||||
/** Stable Klartext error codes (mapped to i18n keys at the module boundary). */
|
||||
export type GmailErrorCode =
|
||||
| "auth_token_expired"
|
||||
| "auth_scope_missing"
|
||||
| "rate_limit_exceeded"
|
||||
| "quota_exceeded"
|
||||
| "history_expired"
|
||||
| "message_not_found"
|
||||
| "watch_subscription_failed"
|
||||
| "provider_outage"
|
||||
| "not_configured"
|
||||
| "unknown";
|
||||
|
||||
export class GmailError extends Error {
|
||||
readonly code: GmailErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
/** True when Gmail invalidated the history cursor (404 on history.list) → full resync. */
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: GmailErrorCode, httpStatus?: number, message?: string) {
|
||||
super(message ?? code);
|
||||
this.name = "GmailError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
this.fullResyncRequired = code === "history_expired";
|
||||
}
|
||||
}
|
||||
|
||||
/** OAuth client config read from env (registered in EXT-13/VEXT-5). */
|
||||
export interface GmailOAuthConfig {
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
/** Must match a Google-registered redirect URI exactly. */
|
||||
readonly redirectUri: string;
|
||||
/** Pub/Sub topic every mailbox watch publishes to (one per GCP project). */
|
||||
readonly pubsubTopic: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the Gmail OAuth config from env. The redirect URI is
|
||||
* `https://{app|staging-app}.hivegrid.de/integrations/email/google/oauth/callback`
|
||||
* (no tenant prefix — tenant+user travel in the signed `state`). Absent env →
|
||||
* not configured (VEXT-5 gates the restricted-scope verification).
|
||||
*/
|
||||
export function resolveGmailOAuthConfig(env: NodeJS.ProcessEnv = process.env): GmailOAuthConfig | null {
|
||||
const clientId = env.GOOGLE_GMAIL_CLIENT_ID;
|
||||
const clientSecret = env.GOOGLE_GMAIL_CLIENT_SECRET;
|
||||
const redirectUri = env.GOOGLE_GMAIL_REDIRECT_URI;
|
||||
const pubsubTopic = env.GOOGLE_GMAIL_PUBSUB_TOPIC;
|
||||
if (!clientId || !clientSecret || !redirectUri || !pubsubTopic) {
|
||||
return null;
|
||||
}
|
||||
return { clientId, clientSecret, redirectUri, pubsubTopic };
|
||||
}
|
||||
|
||||
/**
|
||||
* Gmail OAuth scopes (M09 Block B). `gmail.modify` + `gmail.send` are RESTRICTED
|
||||
* scopes → Google verification/CASA (VEXT-5); until approved the app runs in
|
||||
* test mode with allow-listed accounts.
|
||||
*/
|
||||
export const GMAIL_SCOPES = [
|
||||
"https://www.googleapis.com/auth/gmail.modify",
|
||||
"https://www.googleapis.com/auth/gmail.send",
|
||||
"https://www.googleapis.com/auth/gmail.labels",
|
||||
"openid",
|
||||
"email",
|
||||
] as const;
|
||||
|
||||
/** Build the consent-screen URL. `state` carries a signed tenant+user token. */
|
||||
export function buildGmailAuthorizationUrl(config: GmailOAuthConfig, state: string): string {
|
||||
const params = new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
redirect_uri: config.redirectUri,
|
||||
response_type: "code",
|
||||
scope: GMAIL_SCOPES.join(" "),
|
||||
access_type: "offline",
|
||||
prompt: "consent",
|
||||
include_granted_scopes: "true",
|
||||
state,
|
||||
});
|
||||
return `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
|
||||
}
|
||||
|
||||
export interface GmailTokenSet {
|
||||
readonly accessToken: string;
|
||||
/** Present on the first authorization-code exchange; absent on refresh. */
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}
|
||||
|
||||
interface GmailTokenResponse {
|
||||
access_token: string;
|
||||
refresh_token?: string;
|
||||
expires_in: number;
|
||||
scope?: string;
|
||||
error?: string;
|
||||
error_description?: string;
|
||||
}
|
||||
|
||||
function tokenSetFromResponse(body: GmailTokenResponse, now: number): GmailTokenSet {
|
||||
return {
|
||||
accessToken: body.access_token,
|
||||
refreshToken: body.refresh_token,
|
||||
expiresAt: new Date(now + body.expires_in * 1000),
|
||||
scopes: body.scope ? body.scope.split(" ") : [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Exchange the authorization `code` for a token set (initial connect). */
|
||||
export async function exchangeGmailCodeForTokens(config: GmailOAuthConfig, code: string): Promise<GmailTokenSet> {
|
||||
const res = await fetch(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
redirect_uri: config.redirectUri,
|
||||
grant_type: "authorization_code",
|
||||
code,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GmailTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
return tokenSetFromResponse(body, Date.now());
|
||||
}
|
||||
|
||||
/** Refresh an access token from a stored refresh token. */
|
||||
export async function refreshGmailAccessToken(config: GmailOAuthConfig, refreshToken: string): Promise<GmailTokenSet> {
|
||||
const res = await fetch(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: refreshToken,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GmailTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
// Google omits refresh_token on refresh → caller keeps the existing one.
|
||||
return tokenSetFromResponse({ ...body, refresh_token: body.refresh_token ?? refreshToken }, Date.now());
|
||||
}
|
||||
|
||||
/** Revoke a token pair at Google (disconnect, M09 Block B). Idempotent. */
|
||||
export async function revokeGmailToken(token: string): Promise<void> {
|
||||
const res = await fetch(`${OAUTH_REVOKE_URL}?token=${encodeURIComponent(token)}`, { method: "POST" });
|
||||
// 400 = token already invalid/revoked → idempotent success.
|
||||
if (res.ok || res.status === 400) {
|
||||
return;
|
||||
}
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
|
||||
function mapOAuthError(status: number, body: { error?: string }): GmailError {
|
||||
if (body.error === "invalid_grant") {
|
||||
return new GmailError("auth_token_expired", status, body.error);
|
||||
}
|
||||
if (status === 429) {
|
||||
return new GmailError("rate_limit_exceeded", status);
|
||||
}
|
||||
if (status >= 500) {
|
||||
return new GmailError("provider_outage", status);
|
||||
}
|
||||
return new GmailError("unknown", status, body.error);
|
||||
}
|
||||
|
||||
/** Minimal identity used to fill `emailAddress` / `externalAccountId`. */
|
||||
export interface GmailUserInfo {
|
||||
readonly email: string;
|
||||
readonly sub: string;
|
||||
}
|
||||
|
||||
export async function fetchGmailUserInfo(accessToken: string): Promise<GmailUserInfo> {
|
||||
const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { email?: string; sub?: string };
|
||||
return { email: body.email ?? "", sub: body.sub ?? "" };
|
||||
}
|
||||
|
||||
export interface GmailWatchResult {
|
||||
/** Anchor for the incremental history pulls. */
|
||||
readonly historyId: string;
|
||||
/** Gmail watches expire after ~7 days → renewal cron re-issues users.watch. */
|
||||
readonly expiresAt: Date | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe the mailbox to push notifications (users.watch → Pub/Sub topic).
|
||||
* Google publishes `{emailAddress, historyId}` to the topic; Pub/Sub pushes it
|
||||
* to our webhook endpoint. ONE topic serves every mailbox (per GCP project).
|
||||
*/
|
||||
export async function watchMailbox(accessToken: string, pubsubTopic: string): Promise<GmailWatchResult> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/watch`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ topicName: pubsubTopic, labelIds: ["INBOX", "SENT"], labelFilterBehavior: "INCLUDE" }),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw new GmailError("watch_subscription_failed", res.status);
|
||||
}
|
||||
const body = (await res.json()) as { historyId?: string; expiration?: string };
|
||||
return {
|
||||
historyId: body.historyId ?? "",
|
||||
expiresAt: body.expiration ? new Date(Number(body.expiration)) : null,
|
||||
};
|
||||
}
|
||||
|
||||
/** Stop push notifications for the mailbox (disconnect). Idempotent. */
|
||||
export async function stopWatchMailbox(accessToken: string): Promise<void> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/stop`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (res.ok || res.status === 404) {
|
||||
return;
|
||||
}
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
|
||||
export interface GmailHistoryPage {
|
||||
/** Message ids added since the cursor (deduped; deletions are ignored v1). */
|
||||
readonly addedMessageIds: readonly string[];
|
||||
readonly nextPageToken?: string;
|
||||
/** New cursor to persist once the page set is fully processed. */
|
||||
readonly historyId?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Incremental pull: list history since `startHistoryId`. A 404 means the cursor
|
||||
* is too old (Gmail keeps ~1 week of history) → `history_expired` with
|
||||
* `fullResyncRequired` so the caller re-runs a bounded initial sync.
|
||||
*/
|
||||
export async function listHistory(
|
||||
accessToken: string,
|
||||
startHistoryId: string,
|
||||
pageToken?: string,
|
||||
): Promise<GmailHistoryPage> {
|
||||
const params = new URLSearchParams({ startHistoryId, historyTypes: "messageAdded", maxResults: "100" });
|
||||
if (pageToken) params.set("pageToken", pageToken);
|
||||
const res = await fetch(`${GMAIL_API_BASE}/history?${params.toString()}`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (res.status === 404) {
|
||||
throw new GmailError("history_expired", res.status);
|
||||
}
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as {
|
||||
history?: Array<{ messagesAdded?: Array<{ message?: { id?: string } }> }>;
|
||||
nextPageToken?: string;
|
||||
historyId?: string;
|
||||
};
|
||||
const ids = new Set<string>();
|
||||
for (const entry of body.history ?? []) {
|
||||
for (const added of entry.messagesAdded ?? []) {
|
||||
if (added.message?.id) ids.add(added.message.id);
|
||||
}
|
||||
}
|
||||
return { addedMessageIds: [...ids], nextPageToken: body.nextPageToken, historyId: body.historyId };
|
||||
}
|
||||
|
||||
export interface GmailMessageIdPage {
|
||||
readonly messageIds: readonly string[];
|
||||
readonly nextPageToken?: string;
|
||||
readonly resultSizeEstimate?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* List message ids for the bounded initial sync (M09 Block D: last 90 days).
|
||||
* `q` uses Gmail search syntax, e.g. `newer_than:90d in:anywhere -in:spam -in:trash`.
|
||||
*/
|
||||
export async function listMessageIds(
|
||||
accessToken: string,
|
||||
opts: { q?: string; pageToken?: string; maxResults?: number },
|
||||
): Promise<GmailMessageIdPage> {
|
||||
const params = new URLSearchParams({ maxResults: String(opts.maxResults ?? 100) });
|
||||
if (opts.q) params.set("q", opts.q);
|
||||
if (opts.pageToken) params.set("pageToken", opts.pageToken);
|
||||
const res = await fetch(`${GMAIL_API_BASE}/messages?${params.toString()}`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { messages?: Array<{ id: string }>; nextPageToken?: string; resultSizeEstimate?: number };
|
||||
return {
|
||||
messageIds: (body.messages ?? []).map((m) => m.id),
|
||||
nextPageToken: body.nextPageToken,
|
||||
resultSizeEstimate: body.resultSizeEstimate,
|
||||
};
|
||||
}
|
||||
|
||||
/** Raw Gmail message (format=full). MIME mapping happens in the module adapter. */
|
||||
export interface GmailMessage {
|
||||
readonly id: string;
|
||||
readonly threadId?: string;
|
||||
readonly labelIds?: readonly string[];
|
||||
readonly snippet?: string;
|
||||
readonly internalDate?: string;
|
||||
readonly payload?: GmailMessagePart;
|
||||
readonly historyId?: string;
|
||||
}
|
||||
|
||||
export interface GmailMessagePart {
|
||||
readonly partId?: string;
|
||||
readonly mimeType?: string;
|
||||
readonly filename?: string;
|
||||
readonly headers?: ReadonlyArray<{ name: string; value: string }>;
|
||||
readonly body?: { attachmentId?: string; size?: number; data?: string };
|
||||
readonly parts?: readonly GmailMessagePart[];
|
||||
}
|
||||
|
||||
export async function getMessage(accessToken: string, messageId: string, format: "full" | "metadata" = "full"): Promise<GmailMessage> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/messages/${encodeURIComponent(messageId)}?format=${format}`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
return (await res.json()) as GmailMessage;
|
||||
}
|
||||
|
||||
export interface GmailSendResult {
|
||||
readonly id: string;
|
||||
readonly threadId?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a raw RFC-2822 message (base64url encoded by the caller). `threadId`
|
||||
* keeps a reply inside the provider thread (M09 Block G).
|
||||
*/
|
||||
export async function sendRawMessage(accessToken: string, rawBase64Url: string, threadId?: string): Promise<GmailSendResult> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/messages/send`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify(threadId ? { raw: rawBase64Url, threadId } : { raw: rawBase64Url }),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; threadId?: string };
|
||||
return { id: body.id, threadId: body.threadId };
|
||||
}
|
||||
|
||||
/** Mirror a read/unread toggle back to the provider (M09 Block F bulk actions). */
|
||||
export async function modifyMessageLabels(
|
||||
accessToken: string,
|
||||
messageId: string,
|
||||
changes: { addLabelIds?: readonly string[]; removeLabelIds?: readonly string[] },
|
||||
): Promise<void> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/messages/${encodeURIComponent(messageId)}/modify`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ addLabelIds: changes.addLabelIds ?? [], removeLabelIds: changes.removeLabelIds ?? [] }),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
}
|
||||
|
||||
/** Download an attachment body (base64url `data`). Lazy, on-demand (size cap in caller). */
|
||||
export async function getAttachment(accessToken: string, messageId: string, attachmentId: string): Promise<{ data: string; size: number }> {
|
||||
const res = await fetch(
|
||||
`${GMAIL_API_BASE}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`,
|
||||
{ headers: { authorization: `Bearer ${accessToken}` } },
|
||||
);
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { data?: string; size?: number };
|
||||
return { data: body.data ?? "", size: body.size ?? 0 };
|
||||
}
|
||||
|
||||
function mapApiError(status: number): GmailError {
|
||||
switch (status) {
|
||||
case 401:
|
||||
return new GmailError("auth_token_expired", status);
|
||||
case 403:
|
||||
// Gmail reports both missing scopes and daily quota exhaustion as 403;
|
||||
// the caller distinguishes by context (send path → quota Klartext).
|
||||
return new GmailError("auth_scope_missing", status);
|
||||
case 404:
|
||||
return new GmailError("message_not_found", status);
|
||||
case 429:
|
||||
return new GmailError("rate_limit_exceeded", status);
|
||||
default:
|
||||
return status >= 500 ? new GmailError("provider_outage", status) : new GmailError("unknown", status);
|
||||
}
|
||||
}
|
||||
+381
@@ -0,0 +1,381 @@
|
||||
// AK-P16a · Google Calendar REST/OAuth client (shared web + worker).
|
||||
//
|
||||
// Plain `fetch` against Google's public REST + OAuth2 endpoints — NO Google SDK
|
||||
// (EU-stack: the SDK is a US client lib; raw HTTPS to Google's API is the accepted
|
||||
// external provider boundary, M25 LP-13). This module is provider-typed and pure
|
||||
// of any app/Prisma import so both apps/web (per-user CalendarAdapter) and
|
||||
// apps/worker (token-refresh / webhook-renewal crons) can call it.
|
||||
//
|
||||
// All errors are mapped to a stable `GoogleCalendarErrorCode` (Klartext-ready,
|
||||
// M002) — never a bare provider status leaks to the UI.
|
||||
|
||||
const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
|
||||
const CALENDAR_API_BASE = "https://www.googleapis.com/calendar/v3";
|
||||
|
||||
/** Stable Klartext error codes (mapped to i18n keys at the module boundary). */
|
||||
export type GoogleCalendarErrorCode =
|
||||
| "auth_token_expired"
|
||||
| "auth_scope_missing"
|
||||
| "rate_limit_exceeded"
|
||||
| "calendar_not_found"
|
||||
| "sync_token_invalid"
|
||||
| "webhook_subscription_failed"
|
||||
| "provider_outage"
|
||||
| "not_configured"
|
||||
| "unknown";
|
||||
|
||||
export class GoogleCalendarError extends Error {
|
||||
readonly code: GoogleCalendarErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
/** True when Google invalidated the delta cursor (HTTP 410) → full resync. */
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: GoogleCalendarErrorCode, httpStatus?: number, message?: string) {
|
||||
super(message ?? code);
|
||||
this.name = "GoogleCalendarError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
this.fullResyncRequired = httpStatus === 410;
|
||||
}
|
||||
}
|
||||
|
||||
/** OAuth client config read from env (set by EXT-10). Absent → not_configured. */
|
||||
export interface GoogleOAuthConfig {
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
/** Must match an EXT-10 registered redirect URI exactly. */
|
||||
readonly redirectUri: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the Google OAuth config from env. EXT-10 registered the redirect URIs
|
||||
* `https://{app|staging-app}.hivegrid.de/integrations/google/oauth/callback`, so
|
||||
* `GOOGLE_CALENDAR_REDIRECT_URI` MUST be one of those (no tenant prefix).
|
||||
*/
|
||||
export function resolveGoogleOAuthConfig(env: NodeJS.ProcessEnv = process.env): GoogleOAuthConfig | null {
|
||||
const clientId = env.GOOGLE_CALENDAR_CLIENT_ID;
|
||||
const clientSecret = env.GOOGLE_CALENDAR_CLIENT_SECRET;
|
||||
const redirectUri = env.GOOGLE_CALENDAR_REDIRECT_URI;
|
||||
if (!clientId || !clientSecret || !redirectUri) {
|
||||
return null;
|
||||
}
|
||||
return { clientId, clientSecret, redirectUri };
|
||||
}
|
||||
|
||||
/** Calendar OAuth scopes (Phase 1 — calendar.events + identity, no Gmail). */
|
||||
export const GOOGLE_CALENDAR_SCOPES = [
|
||||
"https://www.googleapis.com/auth/calendar.events",
|
||||
"openid",
|
||||
"email",
|
||||
] as const;
|
||||
|
||||
/** Build the consent-screen URL. `state` carries a signed tenant+user token. */
|
||||
export function buildAuthorizationUrl(config: GoogleOAuthConfig, state: string): string {
|
||||
const params = new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
redirect_uri: config.redirectUri,
|
||||
response_type: "code",
|
||||
scope: GOOGLE_CALENDAR_SCOPES.join(" "),
|
||||
access_type: "offline",
|
||||
prompt: "consent",
|
||||
include_granted_scopes: "true",
|
||||
state,
|
||||
});
|
||||
return `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
|
||||
}
|
||||
|
||||
export interface GoogleTokenSet {
|
||||
readonly accessToken: string;
|
||||
/** Present on the first authorization-code exchange; absent on refresh. */
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}
|
||||
|
||||
interface GoogleTokenResponse {
|
||||
access_token: string;
|
||||
refresh_token?: string;
|
||||
expires_in: number;
|
||||
scope?: string;
|
||||
error?: string;
|
||||
error_description?: string;
|
||||
}
|
||||
|
||||
function tokenSetFromResponse(body: GoogleTokenResponse, now: number): GoogleTokenSet {
|
||||
return {
|
||||
accessToken: body.access_token,
|
||||
refreshToken: body.refresh_token,
|
||||
expiresAt: new Date(now + body.expires_in * 1000),
|
||||
scopes: body.scope ? body.scope.split(" ") : [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Exchange the authorization `code` for a token set (initial connect). */
|
||||
export async function exchangeCodeForTokens(config: GoogleOAuthConfig, code: string): Promise<GoogleTokenSet> {
|
||||
const res = await fetch(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
redirect_uri: config.redirectUri,
|
||||
grant_type: "authorization_code",
|
||||
code,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GoogleTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
return tokenSetFromResponse(body, Date.now());
|
||||
}
|
||||
|
||||
/** Refresh an access token from a stored refresh token. */
|
||||
export async function refreshAccessToken(config: GoogleOAuthConfig, refreshToken: string): Promise<GoogleTokenSet> {
|
||||
const res = await fetch(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: refreshToken,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GoogleTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
// Google omits refresh_token on refresh → caller keeps the existing one.
|
||||
return tokenSetFromResponse({ ...body, refresh_token: body.refresh_token ?? refreshToken }, Date.now());
|
||||
}
|
||||
|
||||
function mapOAuthError(status: number, body: { error?: string }): GoogleCalendarError {
|
||||
if (body.error === "invalid_grant") {
|
||||
return new GoogleCalendarError("auth_token_expired", status, body.error);
|
||||
}
|
||||
if (status === 429) {
|
||||
return new GoogleCalendarError("rate_limit_exceeded", status);
|
||||
}
|
||||
if (status >= 500) {
|
||||
return new GoogleCalendarError("provider_outage", status);
|
||||
}
|
||||
return new GoogleCalendarError("unknown", status, body.error);
|
||||
}
|
||||
|
||||
/** Minimal identity used to fill `externalAccountEmail` / `externalAccountId`. */
|
||||
export interface GoogleUserInfo {
|
||||
readonly email: string;
|
||||
readonly sub: string;
|
||||
}
|
||||
|
||||
export async function fetchUserInfo(accessToken: string): Promise<GoogleUserInfo> {
|
||||
const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { email?: string; sub?: string };
|
||||
return { email: body.email ?? "", sub: body.sub ?? "" };
|
||||
}
|
||||
|
||||
export interface GoogleCalendarListEntry {
|
||||
readonly id: string;
|
||||
readonly summary: string;
|
||||
readonly primary: boolean;
|
||||
}
|
||||
|
||||
export async function listCalendars(accessToken: string): Promise<GoogleCalendarListEntry[]> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/users/me/calendarList`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { items?: Array<{ id: string; summary?: string; primary?: boolean }> };
|
||||
return (body.items ?? []).map((c) => ({ id: c.id, summary: c.summary ?? c.id, primary: c.primary ?? false }));
|
||||
}
|
||||
|
||||
/** Provider event shape (the fields the calendar module maps into CalendarEvent). */
|
||||
export interface GoogleEvent {
|
||||
readonly id: string;
|
||||
readonly status?: string;
|
||||
readonly summary?: string;
|
||||
readonly description?: string;
|
||||
readonly location?: string;
|
||||
readonly start?: { dateTime?: string; date?: string; timeZone?: string };
|
||||
readonly end?: { dateTime?: string; date?: string; timeZone?: string };
|
||||
readonly recurrence?: string[];
|
||||
readonly attendees?: Array<{ email?: string; responseStatus?: string }>;
|
||||
readonly transparency?: string; // "transparent" = Free (not busy)
|
||||
readonly etag?: string;
|
||||
readonly updated?: string;
|
||||
}
|
||||
|
||||
export interface DeltaPage {
|
||||
readonly events: readonly GoogleEvent[];
|
||||
readonly nextSyncToken?: string;
|
||||
readonly nextPageToken?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* List events for the incremental sync. With `syncToken` Google returns only the
|
||||
* delta; HTTP 410 (`sync_token_invalid`) means the cursor expired → full resync.
|
||||
* For an initial pull pass `timeMin`/`timeMax` and no `syncToken`.
|
||||
*/
|
||||
export async function listEvents(
|
||||
accessToken: string,
|
||||
calendarId: string,
|
||||
opts: { syncToken?: string; pageToken?: string; timeMin?: string; timeMax?: string },
|
||||
): Promise<DeltaPage> {
|
||||
const params = new URLSearchParams({ singleEvents: "true", showDeleted: "true", maxResults: "250" });
|
||||
if (opts.syncToken) {
|
||||
params.set("syncToken", opts.syncToken);
|
||||
} else {
|
||||
if (opts.timeMin) params.set("timeMin", opts.timeMin);
|
||||
if (opts.timeMax) params.set("timeMax", opts.timeMax);
|
||||
}
|
||||
if (opts.pageToken) params.set("pageToken", opts.pageToken);
|
||||
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events?${params.toString()}`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { items?: GoogleEvent[]; nextSyncToken?: string; nextPageToken?: string };
|
||||
return { events: body.items ?? [], nextSyncToken: body.nextSyncToken, nextPageToken: body.nextPageToken };
|
||||
}
|
||||
|
||||
/** Payload for creating/updating a mirror event (HiveGrid → Google). */
|
||||
export interface GoogleEventInput {
|
||||
readonly summary: string;
|
||||
readonly description?: string;
|
||||
readonly location?: string;
|
||||
readonly start: { dateTime?: string; date?: string; timeZone?: string };
|
||||
readonly end: { dateTime?: string; date?: string; timeZone?: string };
|
||||
readonly attendees?: Array<{ email: string }>;
|
||||
}
|
||||
|
||||
export interface GoogleWriteResult {
|
||||
readonly id: string;
|
||||
readonly etag?: string;
|
||||
}
|
||||
|
||||
export async function insertEvent(accessToken: string, calendarId: string, input: GoogleEventInput): Promise<GoogleWriteResult> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify(input),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; etag?: string };
|
||||
return { id: body.id, etag: body.etag };
|
||||
}
|
||||
|
||||
/**
|
||||
* Patch an existing mirror event with optimistic locking. `ifMatchEtag` sends the
|
||||
* `If-Match` header — a 412 maps to `provider_outage`? No: 412 means a concurrent
|
||||
* external edit (M25 Block F) → thrown as `GoogleCalendarError("rate_limit"...)`?
|
||||
* It is surfaced specifically so the ConflictResolver can apply Last-Write-Wins.
|
||||
*/
|
||||
export async function patchEvent(
|
||||
accessToken: string,
|
||||
calendarId: string,
|
||||
eventId: string,
|
||||
input: Partial<GoogleEventInput>,
|
||||
ifMatchEtag?: string,
|
||||
): Promise<GoogleWriteResult> {
|
||||
const headers: Record<string, string> = { authorization: `Bearer ${accessToken}`, "content-type": "application/json" };
|
||||
if (ifMatchEtag) headers["if-match"] = ifMatchEtag;
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, {
|
||||
method: "PATCH",
|
||||
headers,
|
||||
body: JSON.stringify(input),
|
||||
});
|
||||
if (res.status === 412) {
|
||||
throw new GoogleCalendarError("rate_limit_exceeded", 412, "precondition_failed");
|
||||
}
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; etag?: string };
|
||||
return { id: body.id, etag: body.etag };
|
||||
}
|
||||
|
||||
export async function deleteEvent(accessToken: string, calendarId: string, eventId: string): Promise<void> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, {
|
||||
method: "DELETE",
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
// 404/410 = already gone → idempotent success (M25 Block F-3).
|
||||
if (res.ok || res.status === 404 || res.status === 410) {
|
||||
return;
|
||||
}
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
|
||||
export interface GoogleWatchChannel {
|
||||
readonly channelId: string;
|
||||
readonly resourceId: string;
|
||||
readonly expiresAt: Date | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribe to push notifications for a calendar (Google `events.watch`). The
|
||||
* `address` is the public webhook endpoint; `token` is the per-connection secret
|
||||
* verified on each notification (`X-Goog-Channel-Token`).
|
||||
*/
|
||||
export async function watchCalendar(
|
||||
accessToken: string,
|
||||
calendarId: string,
|
||||
channelId: string,
|
||||
address: string,
|
||||
token: string,
|
||||
): Promise<GoogleWatchChannel> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events/watch`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ id: channelId, type: "web_hook", address, token }),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw new GoogleCalendarError("webhook_subscription_failed", res.status);
|
||||
}
|
||||
const body = (await res.json()) as { resourceId?: string; expiration?: string };
|
||||
return {
|
||||
channelId,
|
||||
resourceId: body.resourceId ?? "",
|
||||
expiresAt: body.expiration ? new Date(Number(body.expiration)) : null,
|
||||
};
|
||||
}
|
||||
|
||||
export async function stopChannel(accessToken: string, channelId: string, resourceId: string): Promise<void> {
|
||||
const res = await fetch("https://www.googleapis.com/calendar/v3/channels/stop", {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ id: channelId, resourceId }),
|
||||
});
|
||||
if (res.ok || res.status === 404) {
|
||||
return;
|
||||
}
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
|
||||
function mapApiError(status: number): GoogleCalendarError {
|
||||
switch (status) {
|
||||
case 401:
|
||||
return new GoogleCalendarError("auth_token_expired", status);
|
||||
case 403:
|
||||
return new GoogleCalendarError("auth_scope_missing", status);
|
||||
case 404:
|
||||
return new GoogleCalendarError("calendar_not_found", status);
|
||||
case 410:
|
||||
return new GoogleCalendarError("sync_token_invalid", status);
|
||||
case 429:
|
||||
return new GoogleCalendarError("rate_limit_exceeded", status);
|
||||
default:
|
||||
return status >= 500 ? new GoogleCalendarError("provider_outage", status) : new GoogleCalendarError("unknown", status);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
// @hivegrid/integrations — the Apps-Engine catalog + adapter registry (R-P5).
|
||||
// The IntegrationAdapter CONTRACT lives in @hivegrid/foundation; this package owns
|
||||
// the concrete catalog + adapters + the registry barrel so BOTH web and worker
|
||||
// can resolve adapters (e.g. the worker token-refresh / health crons).
|
||||
export * from "./catalog.js";
|
||||
export * from "./catalog-seed.js";
|
||||
export * from "./registry.js";
|
||||
// AK-P16a · the shared Google Calendar REST/OAuth client (web + worker).
|
||||
export * from "./google/googleCalendarApi.js";
|
||||
export * from "./calendar-webhook-renewal.js";
|
||||
// VA-P23 · the shared Gmail + Microsoft Graph mail REST/OAuth clients (web + worker).
|
||||
export * from "./google/gmailApi.js";
|
||||
export * from "./microsoft/graphMailApi.js";
|
||||
export * from "./email-message-mapping.js";
|
||||
export * from "./email-match.js";
|
||||
+167
@@ -0,0 +1,167 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
GRAPH_MAIL_SUBSCRIPTION_LIFETIME_MS,
|
||||
GraphMailError,
|
||||
MICROSOFT_MAIL_SCOPES,
|
||||
buildInitialDeltaUrl,
|
||||
buildMicrosoftAuthorizationUrl,
|
||||
createMailSubscription,
|
||||
deleteMailSubscription,
|
||||
exchangeMicrosoftCodeForTokens,
|
||||
fetchDeltaPage,
|
||||
fetchGraphUserProfile,
|
||||
refreshMicrosoftAccessToken,
|
||||
renewMailSubscription,
|
||||
resolveMicrosoftMailOAuthConfig,
|
||||
sendGraphMail,
|
||||
setGraphMessageRead,
|
||||
} from "./graphMailApi.js";
|
||||
|
||||
// VA-P23 — Graph mail client unit tests. All network I/O is mocked; these pin
|
||||
// the request shapes (endpoints, params, bodies) and the Klartext error mapping.
|
||||
|
||||
const CONFIG = {
|
||||
clientId: "cid",
|
||||
clientSecret: "csecret",
|
||||
redirectUri: "https://app.hivegrid.de/integrations/email/microsoft/oauth/callback",
|
||||
tenant: "common",
|
||||
};
|
||||
|
||||
function jsonResponse(status: number, body: unknown): Response {
|
||||
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
|
||||
}
|
||||
|
||||
let fetchMock: ReturnType<typeof vi.fn>;
|
||||
|
||||
beforeEach(() => {
|
||||
fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe("resolveMicrosoftMailOAuthConfig", () => {
|
||||
it("returns null when any env key is missing", () => {
|
||||
expect(resolveMicrosoftMailOAuthConfig({})).toBeNull();
|
||||
});
|
||||
|
||||
it("defaults the AAD tenant to common", () => {
|
||||
const config = resolveMicrosoftMailOAuthConfig({
|
||||
MICROSOFT_MAIL_CLIENT_ID: "cid",
|
||||
MICROSOFT_MAIL_CLIENT_SECRET: "cs",
|
||||
MICROSOFT_MAIL_REDIRECT_URI: "https://app.hivegrid.de/cb",
|
||||
});
|
||||
expect(config?.tenant).toBe("common");
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildMicrosoftAuthorizationUrl", () => {
|
||||
it("targets the v2 authorize endpoint with the mail scopes", () => {
|
||||
const url = new URL(buildMicrosoftAuthorizationUrl(CONFIG, "signed-state"));
|
||||
expect(url.origin + url.pathname).toBe("https://login.microsoftonline.com/common/oauth2/v2.0/authorize");
|
||||
expect(url.searchParams.get("scope")).toBe(MICROSOFT_MAIL_SCOPES.join(" "));
|
||||
expect(url.searchParams.get("state")).toBe("signed-state");
|
||||
});
|
||||
});
|
||||
|
||||
describe("token exchange + refresh", () => {
|
||||
it("exchanges the code against the tenant token endpoint", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { access_token: "at", refresh_token: "rt", expires_in: 3600 }));
|
||||
const tokens = await exchangeMicrosoftCodeForTokens(CONFIG, "the-code");
|
||||
expect(tokens.accessToken).toBe("at");
|
||||
expect(String(fetchMock.mock.calls[0][0])).toBe("https://login.microsoftonline.com/common/oauth2/v2.0/token");
|
||||
});
|
||||
|
||||
it("persists the ROTATED refresh token from a refresh response", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { access_token: "at2", refresh_token: "rt-rotated", expires_in: 3600 }));
|
||||
const tokens = await refreshMicrosoftAccessToken(CONFIG, "rt-old");
|
||||
expect(tokens.refreshToken).toBe("rt-rotated");
|
||||
});
|
||||
|
||||
it("maps invalid_grant to auth_token_expired", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(400, { error: "invalid_grant" }));
|
||||
await expect(refreshMicrosoftAccessToken(CONFIG, "dead")).rejects.toMatchObject({
|
||||
name: "GraphMailError",
|
||||
code: "auth_token_expired",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("subscriptions", () => {
|
||||
it("creates the /me/messages subscription with clientState and ~3d lifetime", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(201, { id: "sub1", expirationDateTime: "2026-07-05T00:00:00Z" }));
|
||||
const before = Date.now();
|
||||
const sub = await createMailSubscription("at", "https://app.hivegrid.de/webhooks/email/microsoft", "cs-secret");
|
||||
expect(sub.id).toBe("sub1");
|
||||
const body = JSON.parse(String(fetchMock.mock.calls[0][1].body));
|
||||
expect(body).toMatchObject({ resource: "/me/messages", clientState: "cs-secret", changeType: "created,updated" });
|
||||
const requestedExpiry = new Date(body.expirationDateTime).getTime();
|
||||
expect(requestedExpiry).toBeGreaterThan(before);
|
||||
expect(requestedExpiry).toBeLessThanOrEqual(before + GRAPH_MAIL_SUBSCRIPTION_LIFETIME_MS + 5000);
|
||||
});
|
||||
|
||||
it("signals an expired subscription on renew (404) so the caller re-creates", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(404, {}));
|
||||
await expect(renewMailSubscription("at", "sub-gone")).rejects.toMatchObject({ code: "subscription_failed" });
|
||||
});
|
||||
|
||||
it("deletes idempotently (404 = already gone)", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(404, {}));
|
||||
await expect(deleteMailSubscription("at", "sub1")).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("delta sync", () => {
|
||||
it("builds the initial per-folder delta URL with a receivedDateTime bound", () => {
|
||||
const url = buildInitialDeltaUrl("inbox", "2026-04-03T00:00:00Z");
|
||||
expect(url).toContain("/me/mailFolders/inbox/messages/delta");
|
||||
expect(url).toContain("receivedDateTime+ge+2026-04-03T00%3A00%3A00Z");
|
||||
});
|
||||
|
||||
it("follows links verbatim and surfaces next/delta links", async () => {
|
||||
fetchMock.mockResolvedValueOnce(
|
||||
jsonResponse(200, {
|
||||
value: [{ id: "g1", conversationId: "c1" }],
|
||||
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/next-delta",
|
||||
}),
|
||||
);
|
||||
const page = await fetchDeltaPage("at", "https://graph.microsoft.com/v1.0/whatever");
|
||||
expect(page.messages).toHaveLength(1);
|
||||
expect(page.deltaLink).toBe("https://graph.microsoft.com/v1.0/next-delta");
|
||||
expect(fetchMock.mock.calls[0][0]).toBe("https://graph.microsoft.com/v1.0/whatever");
|
||||
});
|
||||
|
||||
it("marks an invalid delta token (410) as fullResyncRequired", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(410, {}));
|
||||
const error = await fetchDeltaPage("at", "https://graph.microsoft.com/v1.0/x").catch((e: unknown) => e);
|
||||
expect(error).toBeInstanceOf(GraphMailError);
|
||||
expect((error as GraphMailError).fullResyncRequired).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("profile, send, read state", () => {
|
||||
it("falls back to userPrincipalName when mail is empty", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { id: "u1", userPrincipalName: "u@x.de" }));
|
||||
const profile = await fetchGraphUserProfile("at");
|
||||
expect(profile.email).toBe("u@x.de");
|
||||
});
|
||||
|
||||
it("accepts sendMail's 202-without-id contract", async () => {
|
||||
fetchMock.mockResolvedValueOnce(new Response(null, { status: 202 }));
|
||||
await expect(
|
||||
sendGraphMail("at", { subject: "s", bodyHtml: "<p>x</p>", to: [{ address: "a@b.de" }] }),
|
||||
).resolves.toBeUndefined();
|
||||
const body = JSON.parse(String(fetchMock.mock.calls[0][1].body));
|
||||
expect(body.saveToSentItems).toBe(true);
|
||||
expect(body.message.toRecipients).toEqual([{ emailAddress: { address: "a@b.de" } }]);
|
||||
});
|
||||
|
||||
it("patches the isRead flag", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, {}));
|
||||
await setGraphMessageRead("at", "m1", true);
|
||||
expect(JSON.parse(String(fetchMock.mock.calls[0][1].body))).toEqual({ isRead: true });
|
||||
});
|
||||
});
|
||||
+460
@@ -0,0 +1,460 @@
|
||||
// VA-P23 · Microsoft Graph Mail REST/OAuth client (shared web + worker).
|
||||
//
|
||||
// Plain `fetch` against the Microsoft identity platform + Graph REST endpoints —
|
||||
// NO Microsoft SDK (same EU-stack boundary as gmailApi.ts/googleCalendarApi.ts).
|
||||
// Provider-typed, pure of any app/Prisma import so apps/web (connect/send) and
|
||||
// apps/worker (delta drain / subscription renewal) share it.
|
||||
//
|
||||
// Graph specifics that shape this client (M09 Block D):
|
||||
// - Subscriptions on /me/messages live at most ~4230 minutes (~3 days) → the
|
||||
// renewal cron PATCHes the expiration daily.
|
||||
// - `clientState` is the ONLY auth mechanism on notifications: generated per
|
||||
// mailbox, stored, and compared on every push.
|
||||
// - Delta queries are PER FOLDER (inbox, sentitems, …) — the caller keeps one
|
||||
// cursor per folder and follows @odata.nextLink/@odata.deltaLink verbatim.
|
||||
// - sendMail returns 202 WITHOUT a message id → the sent-items delta re-ingest
|
||||
// dedupes onto the local outbound mirror via internetMessageId.
|
||||
|
||||
const GRAPH_API_BASE = "https://graph.microsoft.com/v1.0";
|
||||
|
||||
/** Stable Klartext error codes (mapped to i18n keys at the module boundary). */
|
||||
export type GraphMailErrorCode =
|
||||
| "auth_token_expired"
|
||||
| "auth_scope_missing"
|
||||
| "rate_limit_exceeded"
|
||||
| "message_not_found"
|
||||
| "delta_token_invalid"
|
||||
| "subscription_failed"
|
||||
| "provider_outage"
|
||||
| "not_configured"
|
||||
| "unknown";
|
||||
|
||||
export class GraphMailError extends Error {
|
||||
readonly code: GraphMailErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
/** True when Graph invalidated the delta cursor (410 Gone) → full resync. */
|
||||
readonly fullResyncRequired: boolean;
|
||||
constructor(code: GraphMailErrorCode, httpStatus?: number, message?: string) {
|
||||
super(message ?? code);
|
||||
this.name = "GraphMailError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
this.fullResyncRequired = code === "delta_token_invalid";
|
||||
}
|
||||
}
|
||||
|
||||
/** OAuth client config read from env (Azure app registration, VEXT-5 §bridge). */
|
||||
export interface MicrosoftMailOAuthConfig {
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
/** Must match an Azure-registered redirect URI exactly. */
|
||||
readonly redirectUri: string;
|
||||
/** AAD tenant segment; `common` = any Microsoft account (default). */
|
||||
readonly tenant: string;
|
||||
}
|
||||
|
||||
export function resolveMicrosoftMailOAuthConfig(env: NodeJS.ProcessEnv = process.env): MicrosoftMailOAuthConfig | null {
|
||||
const clientId = env.MICROSOFT_MAIL_CLIENT_ID;
|
||||
const clientSecret = env.MICROSOFT_MAIL_CLIENT_SECRET;
|
||||
const redirectUri = env.MICROSOFT_MAIL_REDIRECT_URI;
|
||||
if (!clientId || !clientSecret || !redirectUri) {
|
||||
return null;
|
||||
}
|
||||
return { clientId, clientSecret, redirectUri, tenant: env.MICROSOFT_MAIL_TENANT || "common" };
|
||||
}
|
||||
|
||||
/** Graph mail scopes (M09 Block B). `offline_access` yields the refresh token. */
|
||||
export const MICROSOFT_MAIL_SCOPES = ["offline_access", "Mail.ReadWrite", "Mail.Send", "User.Read"] as const;
|
||||
|
||||
function oauthBase(tenant: string): string {
|
||||
return `https://login.microsoftonline.com/${encodeURIComponent(tenant)}/oauth2/v2.0`;
|
||||
}
|
||||
|
||||
/** Build the consent-screen URL. `state` carries a signed tenant+user token. */
|
||||
export function buildMicrosoftAuthorizationUrl(config: MicrosoftMailOAuthConfig, state: string): string {
|
||||
const params = new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
redirect_uri: config.redirectUri,
|
||||
response_type: "code",
|
||||
response_mode: "query",
|
||||
scope: MICROSOFT_MAIL_SCOPES.join(" "),
|
||||
prompt: "select_account",
|
||||
state,
|
||||
});
|
||||
return `${oauthBase(config.tenant)}/authorize?${params.toString()}`;
|
||||
}
|
||||
|
||||
export interface GraphTokenSet {
|
||||
readonly accessToken: string;
|
||||
/** Graph rotates the refresh token on every grant — persist the new one. */
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}
|
||||
|
||||
interface GraphTokenResponse {
|
||||
access_token: string;
|
||||
refresh_token?: string;
|
||||
expires_in: number;
|
||||
scope?: string;
|
||||
error?: string;
|
||||
error_description?: string;
|
||||
}
|
||||
|
||||
function tokenSetFromResponse(body: GraphTokenResponse, now: number): GraphTokenSet {
|
||||
return {
|
||||
accessToken: body.access_token,
|
||||
refreshToken: body.refresh_token,
|
||||
expiresAt: new Date(now + body.expires_in * 1000),
|
||||
scopes: body.scope ? body.scope.split(" ") : [],
|
||||
};
|
||||
}
|
||||
|
||||
/** Exchange the authorization `code` for a token set (initial connect). */
|
||||
export async function exchangeMicrosoftCodeForTokens(config: MicrosoftMailOAuthConfig, code: string): Promise<GraphTokenSet> {
|
||||
const res = await fetch(`${oauthBase(config.tenant)}/token`, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
redirect_uri: config.redirectUri,
|
||||
grant_type: "authorization_code",
|
||||
scope: MICROSOFT_MAIL_SCOPES.join(" "),
|
||||
code,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GraphTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
return tokenSetFromResponse(body, Date.now());
|
||||
}
|
||||
|
||||
/** Refresh an access token. Graph returns a ROTATED refresh token — persist it. */
|
||||
export async function refreshMicrosoftAccessToken(config: MicrosoftMailOAuthConfig, refreshToken: string): Promise<GraphTokenSet> {
|
||||
const res = await fetch(`${oauthBase(config.tenant)}/token`, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
grant_type: "refresh_token",
|
||||
scope: MICROSOFT_MAIL_SCOPES.join(" "),
|
||||
refresh_token: refreshToken,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GraphTokenResponse;
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
return tokenSetFromResponse({ ...body, refresh_token: body.refresh_token ?? refreshToken }, Date.now());
|
||||
}
|
||||
|
||||
// NOTE: the Microsoft identity platform has no simple app-side token-revoke
|
||||
// endpoint for delegated tokens. Disconnect = delete the Graph subscription +
|
||||
// drop the ciphertexts; the refresh token dies with the user's own revocation
|
||||
// or its natural expiry. Documented in MailboxConnectionService.disconnect.
|
||||
|
||||
function mapOAuthError(status: number, body: { error?: string }): GraphMailError {
|
||||
if (body.error === "invalid_grant") {
|
||||
return new GraphMailError("auth_token_expired", status, body.error);
|
||||
}
|
||||
if (status === 429) {
|
||||
return new GraphMailError("rate_limit_exceeded", status);
|
||||
}
|
||||
if (status >= 500) {
|
||||
return new GraphMailError("provider_outage", status);
|
||||
}
|
||||
return new GraphMailError("unknown", status, body.error);
|
||||
}
|
||||
|
||||
/** Minimal identity used to fill `emailAddress` / `externalAccountId`. */
|
||||
export interface GraphUserProfile {
|
||||
readonly id: string;
|
||||
readonly email: string;
|
||||
readonly displayName?: string;
|
||||
}
|
||||
|
||||
export async function fetchGraphUserProfile(accessToken: string): Promise<GraphUserProfile> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/me?$select=id,mail,userPrincipalName,displayName`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id?: string; mail?: string; userPrincipalName?: string; displayName?: string };
|
||||
return { id: body.id ?? "", email: body.mail || body.userPrincipalName || "", displayName: body.displayName };
|
||||
}
|
||||
|
||||
export interface GraphSubscription {
|
||||
readonly id: string;
|
||||
readonly expiresAt: Date;
|
||||
}
|
||||
|
||||
/** Max subscription lifetime for /me/messages (~4230 minutes ≈ 3 days). */
|
||||
export const GRAPH_MAIL_SUBSCRIPTION_LIFETIME_MS = 4230 * 60 * 1000;
|
||||
|
||||
/**
|
||||
* Create the push subscription on /me/messages. `clientState` is generated per
|
||||
* mailbox, stored on the mailbox row, and verified on every notification.
|
||||
*/
|
||||
export async function createMailSubscription(
|
||||
accessToken: string,
|
||||
notificationUrl: string,
|
||||
clientState: string,
|
||||
): Promise<GraphSubscription> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/subscriptions`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
changeType: "created,updated",
|
||||
notificationUrl,
|
||||
resource: "/me/messages",
|
||||
expirationDateTime: new Date(Date.now() + GRAPH_MAIL_SUBSCRIPTION_LIFETIME_MS).toISOString(),
|
||||
clientState,
|
||||
}),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw new GraphMailError("subscription_failed", res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; expirationDateTime: string };
|
||||
return { id: body.id, expiresAt: new Date(body.expirationDateTime) };
|
||||
}
|
||||
|
||||
/** Renew (PATCH) an existing subscription's expiration (daily renewal cron). */
|
||||
export async function renewMailSubscription(accessToken: string, subscriptionId: string): Promise<GraphSubscription> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/subscriptions/${encodeURIComponent(subscriptionId)}`, {
|
||||
method: "PATCH",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ expirationDateTime: new Date(Date.now() + GRAPH_MAIL_SUBSCRIPTION_LIFETIME_MS).toISOString() }),
|
||||
});
|
||||
if (res.status === 404) {
|
||||
// Subscription already expired at Microsoft → caller re-creates it.
|
||||
throw new GraphMailError("subscription_failed", res.status, "subscription_expired");
|
||||
}
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; expirationDateTime: string };
|
||||
return { id: body.id, expiresAt: new Date(body.expirationDateTime) };
|
||||
}
|
||||
|
||||
/** Delete the subscription (disconnect). Idempotent. */
|
||||
export async function deleteMailSubscription(accessToken: string, subscriptionId: string): Promise<void> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/subscriptions/${encodeURIComponent(subscriptionId)}`, {
|
||||
method: "DELETE",
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (res.ok || res.status === 404) {
|
||||
return;
|
||||
}
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
|
||||
/** The Graph message projection this module maps into EmailIntegrationMessage. */
|
||||
export interface GraphMessage {
|
||||
readonly id: string;
|
||||
readonly conversationId?: string;
|
||||
readonly internetMessageId?: string;
|
||||
readonly subject?: string;
|
||||
readonly bodyPreview?: string;
|
||||
readonly body?: { contentType?: string; content?: string };
|
||||
readonly from?: { emailAddress?: { address?: string; name?: string } };
|
||||
readonly toRecipients?: ReadonlyArray<{ emailAddress?: { address?: string; name?: string } }>;
|
||||
readonly ccRecipients?: ReadonlyArray<{ emailAddress?: { address?: string; name?: string } }>;
|
||||
readonly bccRecipients?: ReadonlyArray<{ emailAddress?: { address?: string; name?: string } }>;
|
||||
readonly sentDateTime?: string;
|
||||
readonly receivedDateTime?: string;
|
||||
readonly isRead?: boolean;
|
||||
readonly hasAttachments?: boolean;
|
||||
readonly internetMessageHeaders?: ReadonlyArray<{ name?: string; value?: string }>;
|
||||
/** Present in delta responses for removed items. */
|
||||
readonly "@removed"?: { reason?: string };
|
||||
}
|
||||
|
||||
const MESSAGE_SELECT = [
|
||||
"id",
|
||||
"conversationId",
|
||||
"internetMessageId",
|
||||
"subject",
|
||||
"bodyPreview",
|
||||
"body",
|
||||
"from",
|
||||
"toRecipients",
|
||||
"ccRecipients",
|
||||
"bccRecipients",
|
||||
"sentDateTime",
|
||||
"receivedDateTime",
|
||||
"isRead",
|
||||
"hasAttachments",
|
||||
].join(",");
|
||||
|
||||
export interface GraphDeltaPage {
|
||||
readonly messages: readonly GraphMessage[];
|
||||
/** Follow verbatim until absent. */
|
||||
readonly nextLink?: string;
|
||||
/** Persist as the folder cursor once the page set is fully processed. */
|
||||
readonly deltaLink?: string;
|
||||
}
|
||||
|
||||
/** Build the INITIAL delta URL for a folder, bounded for the 90-day initial sync. */
|
||||
export function buildInitialDeltaUrl(folderId: string, receivedAfterIso?: string): string {
|
||||
const params = new URLSearchParams({ $select: MESSAGE_SELECT });
|
||||
if (receivedAfterIso) {
|
||||
params.set("$filter", `receivedDateTime ge ${receivedAfterIso}`);
|
||||
}
|
||||
return `${GRAPH_API_BASE}/me/mailFolders/${encodeURIComponent(folderId)}/messages/delta?${params.toString()}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch one delta page. `url` is either the initial folder delta URL or a stored
|
||||
* @odata.nextLink/@odata.deltaLink — Graph links are followed VERBATIM. A 410
|
||||
* means the delta token expired → full resync for that folder.
|
||||
*/
|
||||
export async function fetchDeltaPage(accessToken: string, url: string): Promise<GraphDeltaPage> {
|
||||
const res = await fetch(url, { headers: { authorization: `Bearer ${accessToken}` } });
|
||||
if (res.status === 410) {
|
||||
throw new GraphMailError("delta_token_invalid", res.status);
|
||||
}
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as {
|
||||
value?: GraphMessage[];
|
||||
"@odata.nextLink"?: string;
|
||||
"@odata.deltaLink"?: string;
|
||||
};
|
||||
return { messages: body.value ?? [], nextLink: body["@odata.nextLink"], deltaLink: body["@odata.deltaLink"] };
|
||||
}
|
||||
|
||||
export async function getGraphMessage(accessToken: string, messageId: string): Promise<GraphMessage> {
|
||||
const res = await fetch(
|
||||
`${GRAPH_API_BASE}/me/messages/${encodeURIComponent(messageId)}?$select=${MESSAGE_SELECT}&$expand=internetMessageHeaders`,
|
||||
{ headers: { authorization: `Bearer ${accessToken}` } },
|
||||
);
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
return (await res.json()) as GraphMessage;
|
||||
}
|
||||
|
||||
export interface GraphSendRecipient {
|
||||
readonly address: string;
|
||||
readonly name?: string;
|
||||
}
|
||||
|
||||
export interface GraphSendInput {
|
||||
readonly subject: string;
|
||||
readonly bodyHtml: string;
|
||||
readonly to: readonly GraphSendRecipient[];
|
||||
readonly cc?: readonly GraphSendRecipient[];
|
||||
readonly bcc?: readonly GraphSendRecipient[];
|
||||
/** fileAttachment content as base64 (v1 cap: ≤3 MB per attachment). */
|
||||
readonly attachments?: ReadonlyArray<{ name: string; contentType: string; contentBase64: string }>;
|
||||
/** Internet-message-id being replied to (threads the message client-side). */
|
||||
readonly inReplyToInternetMessageId?: string;
|
||||
}
|
||||
|
||||
function graphRecipients(list: readonly GraphSendRecipient[] | undefined) {
|
||||
return (list ?? []).map((r) => ({ emailAddress: { address: r.address, ...(r.name ? { name: r.name } : {}) } }));
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a message (/me/sendMail, saveToSentItems). Graph answers 202 with NO
|
||||
* message id — the caller mirrors the outbound locally and the sent-items delta
|
||||
* later dedupes via internetMessageId.
|
||||
*/
|
||||
export async function sendGraphMail(accessToken: string, input: GraphSendInput): Promise<void> {
|
||||
const message: Record<string, unknown> = {
|
||||
subject: input.subject,
|
||||
body: { contentType: "HTML", content: input.bodyHtml },
|
||||
toRecipients: graphRecipients(input.to),
|
||||
ccRecipients: graphRecipients(input.cc),
|
||||
bccRecipients: graphRecipients(input.bcc),
|
||||
};
|
||||
if (input.attachments?.length) {
|
||||
message.attachments = input.attachments.map((a) => ({
|
||||
"@odata.type": "#microsoft.graph.fileAttachment",
|
||||
name: a.name,
|
||||
contentType: a.contentType,
|
||||
contentBytes: a.contentBase64,
|
||||
}));
|
||||
}
|
||||
const res = await fetch(`${GRAPH_API_BASE}/me/sendMail`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ message, saveToSentItems: true }),
|
||||
});
|
||||
if (!res.ok && res.status !== 202) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
}
|
||||
|
||||
/** Mirror a read/unread toggle back to the provider (M09 Block F bulk actions). */
|
||||
export async function setGraphMessageRead(accessToken: string, messageId: string, isRead: boolean): Promise<void> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/me/messages/${encodeURIComponent(messageId)}`, {
|
||||
method: "PATCH",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ isRead }),
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
}
|
||||
|
||||
export interface GraphAttachment {
|
||||
readonly id: string;
|
||||
readonly name: string;
|
||||
readonly contentType?: string;
|
||||
readonly sizeBytes: number;
|
||||
/** Present for fileAttachment when fetched individually (≤3 MB inline). */
|
||||
readonly contentBase64?: string;
|
||||
}
|
||||
|
||||
export async function listGraphAttachments(accessToken: string, messageId: string): Promise<GraphAttachment[]> {
|
||||
const res = await fetch(`${GRAPH_API_BASE}/me/messages/${encodeURIComponent(messageId)}/attachments?$select=id,name,contentType,size`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { value?: Array<{ id: string; name?: string; contentType?: string; size?: number }> };
|
||||
return (body.value ?? []).map((a) => ({ id: a.id, name: a.name ?? "attachment", contentType: a.contentType, sizeBytes: a.size ?? 0 }));
|
||||
}
|
||||
|
||||
/** Fetch one attachment (fileAttachment → contentBytes inline; >3 MB via $value stream is v2). */
|
||||
export async function getGraphAttachment(accessToken: string, messageId: string, attachmentId: string): Promise<GraphAttachment> {
|
||||
const res = await fetch(
|
||||
`${GRAPH_API_BASE}/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`,
|
||||
{ headers: { authorization: `Bearer ${accessToken}` } },
|
||||
);
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; name?: string; contentType?: string; size?: number; contentBytes?: string };
|
||||
return {
|
||||
id: body.id,
|
||||
name: body.name ?? "attachment",
|
||||
contentType: body.contentType,
|
||||
sizeBytes: body.size ?? 0,
|
||||
contentBase64: body.contentBytes,
|
||||
};
|
||||
}
|
||||
|
||||
function mapApiError(status: number): GraphMailError {
|
||||
switch (status) {
|
||||
case 401:
|
||||
return new GraphMailError("auth_token_expired", status);
|
||||
case 403:
|
||||
return new GraphMailError("auth_scope_missing", status);
|
||||
case 404:
|
||||
return new GraphMailError("message_not_found", status);
|
||||
case 410:
|
||||
return new GraphMailError("delta_token_invalid", status);
|
||||
case 429:
|
||||
return new GraphMailError("rate_limit_exceeded", status);
|
||||
default:
|
||||
return status >= 500 ? new GraphMailError("provider_outage", status) : new GraphMailError("unknown", status);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { getCatalogDrift, resolveAdapter } from "./registry.js";
|
||||
import { INTEGRATION_CATALOG } from "./catalog.js";
|
||||
|
||||
// R-P5 — the build-time drift gate (DoD #2): the shipped adapter registry and the
|
||||
// App catalog MUST agree. A new app added to the catalog without an adapter (or
|
||||
// vice versa) fails here, the same way the platform-admin warning surfaces it.
|
||||
|
||||
describe("integration registry ↔ catalog", () => {
|
||||
it("is fully in sync (no missing or orphan adapters)", () => {
|
||||
const drift = getCatalogDrift();
|
||||
expect(drift.missingAdapters, "catalog Apps without an adapter").toEqual([]);
|
||||
expect(drift.orphanAdapters, "adapters without a catalog App").toEqual([]);
|
||||
expect(drift.inSync).toBe(true);
|
||||
});
|
||||
|
||||
it("resolves every catalog app to a typed adapter with the right connection type", () => {
|
||||
for (const entry of INTEGRATION_CATALOG) {
|
||||
const adapter = resolveAdapter(entry.key);
|
||||
expect(adapter, `adapter for ${entry.key}`).toBeDefined();
|
||||
expect(adapter!.connectionType).toBe(entry.connectionType);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,31 @@
|
||||
// R-P5 (P5) — integration adapter registry barrel + drift check.
|
||||
//
|
||||
// Importing this module registers every shipped adapter (each adapter file calls
|
||||
// registerIntegrationAdapter on import). Web + worker import from here so the
|
||||
// adapters are guaranteed registered before use.
|
||||
//
|
||||
// `getCatalogDrift()` compares the registered adapters with the App catalog and
|
||||
// is surfaced as a Klartext warning in the platform admin (P19); the
|
||||
// registry.test.ts runs the same check as a build-time gate.
|
||||
|
||||
import { checkCatalogDrift, getIntegrationAdapter, listIntegrationAdapterKeys, type CatalogDrift, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
import { catalogKeys } from "./catalog.js";
|
||||
|
||||
// Side-effect imports: each registers its adapter on load. New integrations add
|
||||
// one import line here (+ a catalog entry) — no other core change (DoD #2).
|
||||
import "./adapters/sample-data-sync.js";
|
||||
import "./adapters/google-calendar.js"; // AK-P16a
|
||||
import "./adapters/ses-selfhosted.js"; // AK-P16d
|
||||
import "./adapters/pandadoc-byok.js"; // AK-P16d
|
||||
import "./adapters/gmail.js"; // VA-P23
|
||||
import "./adapters/microsoft-mail.js"; // VA-P23
|
||||
|
||||
/** Resolve a registered adapter by app key, or undefined. */
|
||||
export function resolveAdapter<Creds = Record<string, unknown>>(appKey: string): IntegrationAdapter<Creds> | undefined {
|
||||
return getIntegrationAdapter<Creds>(appKey);
|
||||
}
|
||||
|
||||
/** Current drift between the registered adapters and the App catalog. */
|
||||
export function getCatalogDrift(): CatalogDrift {
|
||||
return checkCatalogDrift(listIntegrationAdapterKeys(), catalogKeys());
|
||||
}
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
// R-P5 (P5) §P2d — shared per-tenant maintenance for DataConnections, used by the
|
||||
// worker crons (token refresh + health sweep). Lives here (not apps/web) because
|
||||
// the worker only depends on @hivegrid/db + @hivegrid/integrations, not apps/web.
|
||||
//
|
||||
// Both functions take an active Prisma client/tx (the caller wraps them in the
|
||||
// worker's withTenantRLS so the tenant GUC is set) and operate ONLY on that
|
||||
// tenant's rows. Credentials are decrypted/re-encrypted via the per-tenant DEK
|
||||
// envelope (Phase 1), passing the same client so the crypto store stays in the
|
||||
// tenant scope.
|
||||
|
||||
import { decryptTenantField, encryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
|
||||
import { createNotificationDelivery } from "@hivegrid/db/notifications.server";
|
||||
import { resolveAdapter } from "./registry.js";
|
||||
|
||||
/** Minimal structural client shape (satisfied by the full client or a tx). */
|
||||
type ConnectionRow = {
|
||||
id: string;
|
||||
appId: string;
|
||||
credentialsCiphertext: string | null;
|
||||
connectionStatus: string;
|
||||
createdByUserId: string | null;
|
||||
};
|
||||
|
||||
type WorkerDataConnectionClient = {
|
||||
dataConnection: {
|
||||
findMany(args: {
|
||||
where: Record<string, unknown>;
|
||||
select: { id: true; appId: true; credentialsCiphertext: true; connectionStatus: true; createdByUserId: true };
|
||||
}): Promise<ConnectionRow[]>;
|
||||
updateMany(args: { where: { id: string; tenantId: string }; data: Record<string, unknown> }): Promise<{ count: number }>;
|
||||
};
|
||||
};
|
||||
|
||||
const CONNECTION_SELECT = { id: true, appId: true, credentialsCiphertext: true, connectionStatus: true, createdByUserId: true } as const;
|
||||
|
||||
async function notifyOwner(tenantId: string, ownerUserId: string | null, connectionId: string, health: string): Promise<void> {
|
||||
if (!ownerUserId) {
|
||||
return;
|
||||
}
|
||||
await createNotificationDelivery({
|
||||
tenantId,
|
||||
userId: ownerUserId,
|
||||
channel: "in-app",
|
||||
category: "system",
|
||||
messageKey: "integrations.notify.connectionUnhealthy",
|
||||
status: "PENDING",
|
||||
payloadMetadata: { source: "integrations", connectionId, health },
|
||||
}).catch(() => undefined);
|
||||
}
|
||||
|
||||
/**
|
||||
* Refresh OAuth tokens that are within `windowMs` of expiry for one tenant. Only
|
||||
* adapters that implement refreshToken() participate; api_key/rest_api connections
|
||||
* are skipped. A refresh failure marks the connection broken + notifies the owner.
|
||||
* Returns the number of connections refreshed.
|
||||
*/
|
||||
export async function refreshExpiringTokensForTenant(
|
||||
client: WorkerDataConnectionClient,
|
||||
tenantId: string,
|
||||
opts?: { now?: Date; windowMs?: number },
|
||||
): Promise<{ refreshed: number; failed: number }> {
|
||||
const now = opts?.now ?? new Date();
|
||||
const horizon = new Date(now.getTime() + (opts?.windowMs ?? 10 * 60_000));
|
||||
const connections = await client.dataConnection.findMany({
|
||||
where: { tenantId, archivedAt: null, connectionStatus: "active", tokenExpiresAt: { not: null, lte: horizon } },
|
||||
select: CONNECTION_SELECT,
|
||||
});
|
||||
|
||||
let refreshed = 0;
|
||||
let failed = 0;
|
||||
for (const connection of connections) {
|
||||
const adapter = resolveAdapter(connection.appId);
|
||||
if (!adapter?.refreshToken || !connection.credentialsCiphertext) {
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
const creds = JSON.parse(await decryptTenantField(tenantId, connection.credentialsCiphertext, { client: client as never })) as Record<string, unknown>;
|
||||
const result = await adapter.refreshToken(creds);
|
||||
const ciphertext = await encryptTenantField(tenantId, JSON.stringify(result.creds), { client: client as never });
|
||||
await client.dataConnection.updateMany({
|
||||
where: { id: connection.id, tenantId },
|
||||
data: { credentialsCiphertext: ciphertext, tokenExpiresAt: result.expiresAt, connectionStatus: "active", lastHealthCheck: now },
|
||||
});
|
||||
refreshed += 1;
|
||||
} catch {
|
||||
failed += 1;
|
||||
await client.dataConnection.updateMany({ where: { id: connection.id, tenantId }, data: { connectionStatus: "broken", healthMessageKey: "integrations.health.refreshFailed", lastHealthCheck: now } });
|
||||
await notifyOwner(tenantId, connection.createdByUserId, connection.id, "broken");
|
||||
}
|
||||
}
|
||||
return { refreshed, failed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Probe every active connection's health for one tenant, persisting the new
|
||||
* status. Degraded/broken transitions notify the owner. Returns counts.
|
||||
*/
|
||||
export async function sweepConnectionHealthForTenant(
|
||||
client: WorkerDataConnectionClient,
|
||||
tenantId: string,
|
||||
opts?: { now?: Date },
|
||||
): Promise<{ checked: number; unhealthy: number }> {
|
||||
const now = opts?.now ?? new Date();
|
||||
const connections = await client.dataConnection.findMany({
|
||||
where: { tenantId, archivedAt: null, connectionStatus: { in: ["active", "degraded"] } },
|
||||
select: CONNECTION_SELECT,
|
||||
});
|
||||
|
||||
let checked = 0;
|
||||
let unhealthy = 0;
|
||||
for (const connection of connections) {
|
||||
const adapter = resolveAdapter(connection.appId);
|
||||
let health: "active" | "degraded" | "broken" = "broken";
|
||||
let messageKey = "integrations.health.notConnected";
|
||||
if (adapter && connection.credentialsCiphertext) {
|
||||
try {
|
||||
const creds = JSON.parse(await decryptTenantField(tenantId, connection.credentialsCiphertext, { client: client as never })) as Record<string, unknown>;
|
||||
const result = await adapter.healthCheck(creds);
|
||||
health = result.health;
|
||||
messageKey = result.messageKey;
|
||||
} catch {
|
||||
health = "broken";
|
||||
messageKey = "integrations.health.probeFailed";
|
||||
}
|
||||
}
|
||||
await client.dataConnection.updateMany({ where: { id: connection.id, tenantId }, data: { connectionStatus: health, lastHealthCheck: now, healthMessageKey: messageKey } });
|
||||
checked += 1;
|
||||
if (health !== "active") {
|
||||
unhealthy += 1;
|
||||
await notifyOwner(tenantId, connection.createdByUserId, connection.id, health);
|
||||
}
|
||||
}
|
||||
return { checked, unhealthy };
|
||||
}
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
// @vitest-environment node
|
||||
import { beforeEach, describe, expect, it } from "vitest";
|
||||
import { clearIntegrationAdapters, registerIntegrationAdapter, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
import { encryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
|
||||
import { refreshExpiringTokensForTenant, sweepConnectionHealthForTenant } from "./worker-tasks.server.js";
|
||||
|
||||
// R-P5 — worker maintenance sweeps. In-memory client (dataConnection + the crypto
|
||||
// store) + a test adapter; no DB. Proves the health sweep persists the adapter
|
||||
// verdict and the token refresh re-encrypts + extends expiry.
|
||||
|
||||
type DcRow = {
|
||||
id: string;
|
||||
tenantId: string;
|
||||
appId: string;
|
||||
label: string;
|
||||
credentialsCiphertext: string | null;
|
||||
connectionStatus: string;
|
||||
tokenExpiresAt: Date | null;
|
||||
archivedAt: Date | null;
|
||||
createdByUserId: string | null;
|
||||
healthMessageKey?: string | null;
|
||||
lastHealthCheck?: Date | null;
|
||||
};
|
||||
|
||||
function makeClient(rows: DcRow[]) {
|
||||
const keys = new Map<string, { tenantId: string; wrappedDek: Uint8Array; keyVersion: number }>();
|
||||
const matches = (row: DcRow, where: Record<string, any>): boolean => {
|
||||
if (where.tenantId && row.tenantId !== where.tenantId) return false;
|
||||
if (where.archivedAt === null && row.archivedAt !== null) return false;
|
||||
if (typeof where.connectionStatus === "string" && row.connectionStatus !== where.connectionStatus) return false;
|
||||
if (where.connectionStatus?.in && !where.connectionStatus.in.includes(row.connectionStatus)) return false;
|
||||
if (where.tokenExpiresAt?.lte && (!row.tokenExpiresAt || row.tokenExpiresAt > where.tokenExpiresAt.lte)) return false;
|
||||
return true;
|
||||
};
|
||||
return {
|
||||
rows,
|
||||
client: {
|
||||
dataConnection: {
|
||||
findMany: ({ where }: { where: Record<string, any> }) => Promise.resolve(rows.filter((r) => matches(r, where)) as never),
|
||||
updateMany: ({ where, data }: { where: { id: string; tenantId: string }; data: Record<string, unknown> }) => {
|
||||
const row = rows.find((r) => r.id === where.id && r.tenantId === where.tenantId);
|
||||
if (row) Object.assign(row, data);
|
||||
return Promise.resolve({ count: row ? 1 : 0 });
|
||||
},
|
||||
},
|
||||
tenantEncryptionKey: {
|
||||
findUnique: ({ where }: { where: { tenantId: string } }) => Promise.resolve(keys.get(where.tenantId) ?? null),
|
||||
create: ({ data }: { data: { tenantId: string; wrappedDek: Uint8Array; keyVersion: number } }) => {
|
||||
keys.set(data.tenantId, data);
|
||||
return Promise.resolve(data);
|
||||
},
|
||||
deleteMany: ({ where }: { where: { tenantId: string } }) => Promise.resolve({ count: keys.delete(where.tenantId) ? 1 : 0 }),
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const degradedAdapter: IntegrationAdapter = {
|
||||
key: "test-degraded",
|
||||
connectionType: "api_key",
|
||||
validateConnection: () => Promise.resolve({ ok: true, health: "active", messageKey: "integrations.health.active" }),
|
||||
healthCheck: () => Promise.resolve({ ok: false, health: "degraded", messageKey: "integrations.health.probeFailed" }),
|
||||
sync: () => Promise.resolve({ items: [], summaryKey: "integrations.sync.summary.empty" }),
|
||||
};
|
||||
|
||||
const oauthAdapter: IntegrationAdapter = {
|
||||
key: "test-oauth",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: () => Promise.resolve({ ok: true, health: "active", messageKey: "integrations.health.active" }),
|
||||
healthCheck: () => Promise.resolve({ ok: true, health: "active", messageKey: "integrations.health.active" }),
|
||||
refreshToken: (creds) => Promise.resolve({ creds: { ...creds, token: "fresh" }, expiresAt: new Date("2030-01-01") }),
|
||||
sync: () => Promise.resolve({ items: [], summaryKey: "integrations.sync.summary.empty" }),
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
process.env.CRYPTO_SECRET = "test-master-key-aaaaaaaaaaaaaaaaaaaaaa";
|
||||
clearIntegrationAdapters();
|
||||
});
|
||||
|
||||
describe("sweepConnectionHealthForTenant", () => {
|
||||
it("persists the adapter's degraded verdict and counts it unhealthy", async () => {
|
||||
registerIntegrationAdapter(degradedAdapter);
|
||||
const { client, rows } = makeClient([]);
|
||||
const ct = await encryptTenantField("ten_1", JSON.stringify({ apiKey: "x" }), { client: client as never });
|
||||
rows.push({ id: "dc1", tenantId: "ten_1", appId: "test-degraded", label: "L", credentialsCiphertext: ct, connectionStatus: "active", tokenExpiresAt: null, archivedAt: null, createdByUserId: null });
|
||||
|
||||
const result = await sweepConnectionHealthForTenant(client, "ten_1");
|
||||
expect(result).toEqual({ checked: 1, unhealthy: 1 });
|
||||
expect(rows[0].connectionStatus).toBe("degraded");
|
||||
expect(rows[0].healthMessageKey).toBe("integrations.health.probeFailed");
|
||||
});
|
||||
});
|
||||
|
||||
describe("refreshExpiringTokensForTenant", () => {
|
||||
it("refreshes an expiring oauth token, re-encrypts, and extends expiry", async () => {
|
||||
registerIntegrationAdapter(oauthAdapter);
|
||||
const { client, rows } = makeClient([]);
|
||||
const ct = await encryptTenantField("ten_1", JSON.stringify({ token: "stale" }), { client: client as never });
|
||||
rows.push({ id: "dc1", tenantId: "ten_1", appId: "test-oauth", label: "L", credentialsCiphertext: ct, connectionStatus: "active", tokenExpiresAt: new Date("2020-01-01"), archivedAt: null, createdByUserId: null });
|
||||
|
||||
const result = await refreshExpiringTokensForTenant(client, "ten_1");
|
||||
expect(result).toEqual({ refreshed: 1, failed: 0 });
|
||||
expect(rows[0].tokenExpiresAt).toEqual(new Date("2030-01-01"));
|
||||
expect(rows[0].credentialsCiphertext).not.toBe(ct); // re-encrypted
|
||||
});
|
||||
|
||||
it("skips connections whose adapter has no refreshToken (api_key)", async () => {
|
||||
registerIntegrationAdapter(degradedAdapter); // no refreshToken
|
||||
const { client, rows } = makeClient([]);
|
||||
const ct = await encryptTenantField("ten_1", JSON.stringify({ apiKey: "x" }), { client: client as never });
|
||||
rows.push({ id: "dc1", tenantId: "ten_1", appId: "test-degraded", label: "L", credentialsCiphertext: ct, connectionStatus: "active", tokenExpiresAt: new Date("2020-01-01"), archivedAt: null, createdByUserId: null });
|
||||
|
||||
const result = await refreshExpiringTokensForTenant(client, "ten_1");
|
||||
expect(result).toEqual({ refreshed: 0, failed: 0 });
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user