Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
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" }),
});
@@ -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" }),
});
@@ -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" }),
});
@@ -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);
});
});
@@ -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",
}),
});
@@ -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",
}),
});
@@ -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",
}),
});
@@ -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);
});
});
@@ -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" };
}
@@ -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" }));
});
});
@@ -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);
}
@@ -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);
}
@@ -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".
}
};
}
@@ -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,
};
}
@@ -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");
});
});
@@ -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(/=+$/, "");
}
@@ -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"));
});
});
@@ -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);
}
@@ -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" });
});
});
@@ -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);
}
}
@@ -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";
@@ -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 });
});
});
@@ -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());
}
@@ -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 };
}
@@ -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 });
});
});