Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -6,8 +6,33 @@
|
||||
"exports": {
|
||||
".": "./src/index.ts",
|
||||
"./calendar-worker-tasks.server": "./src/calendar-worker-tasks.server.ts",
|
||||
"./kwp-archive-discovery.server": "./src/kwp/archive-discovery.server.ts",
|
||||
"./kwp-archive-file.server": "./src/kwp/archive-file.server.ts",
|
||||
"./email-worker-tasks.server": "./src/email-worker-tasks.server.ts",
|
||||
"./admin-email-worker-tasks.server": "./src/admin-email-worker-tasks.server.ts",
|
||||
"./admin-email-attachments.server": "./src/admin-email-attachments.server.ts",
|
||||
"./admin-email-tracking": "./src/admin-email-tracking.ts",
|
||||
"./admin-email-domain": "./src/admin-email-domain.ts",
|
||||
"./admin-email-domain-worker.server": "./src/admin-email-domain-worker.server.ts",
|
||||
"./admin-email-provider-events": "./src/admin-email-provider-events.ts",
|
||||
"./admin-telephony-worker.server": "./src/admin-telephony-worker.server.ts",
|
||||
"./admin-outbound-calls.server": "./src/admin-outbound-calls.server.ts",
|
||||
"./admin-call-recordings.server": "./src/admin-call-recordings.server.ts",
|
||||
"./admin-calendar-provider": "./src/admin-calendar-provider.ts",
|
||||
"./admin-calendar-oauth.server": "./src/admin-calendar-oauth.server.ts",
|
||||
"./admin-calendar-sync-worker.server": "./src/admin-calendar-sync-worker.server.ts",
|
||||
"./admin-booking-provider.server": "./src/admin-booking-provider.server.ts",
|
||||
"./admin-booking-worker.server": "./src/admin-booking-worker.server.ts",
|
||||
"./microsoft/graph-calendar-api": "./src/microsoft/graphCalendarApi.ts",
|
||||
"./admin-mail-sync-provider.server": "./src/admin-mail-sync-provider.server.ts",
|
||||
"./email-match-hook.server": "./src/email-match-hook.server.ts",
|
||||
"./kwp-contract-sentinel.server": "./src/kwp/contract-sentinel.server.ts",
|
||||
"./kwp-inbound-reader": "./src/kwp/inbound-reader.ts",
|
||||
"./kwp-inbound-sync.server": "./src/kwp/inbound-sync.server.ts",
|
||||
"./kwp-project-catalog.server": "./src/kwp/project-catalog.server.ts",
|
||||
"./kwp-project-domain.server": "./src/kwp/project-domain.server.ts",
|
||||
"./kwp-project-sync.server": "./src/kwp/project-sync.server.ts",
|
||||
"./kwp-resource-client.server": "./src/kwp/resource-client.server.ts",
|
||||
"./worker-tasks.server": "./src/worker-tasks.server.ts"
|
||||
},
|
||||
"scripts": {
|
||||
@@ -16,8 +41,16 @@
|
||||
},
|
||||
"dependencies": {
|
||||
"@hivegrid/activity": "workspace:*",
|
||||
"@hivegrid/config": "workspace:*",
|
||||
"@hivegrid/db": "workspace:*",
|
||||
"@hivegrid/foundation": "workspace:*"
|
||||
"@hivegrid/entitlements": "workspace:*",
|
||||
"@hivegrid/foundation": "workspace:*",
|
||||
"@hivegrid/logger": "workspace:*",
|
||||
"@hivegrid/queue": "workspace:*",
|
||||
"@hivegrid/search": "workspace:*",
|
||||
"@hivegrid/shared-store": "workspace:*",
|
||||
"ajv": "^8.20.0",
|
||||
"zod": "3.25.76"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^25.6.0",
|
||||
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const google = vi.hoisted(() => ({
|
||||
insertEvent: vi.fn(),
|
||||
patchEvent: vi.fn(),
|
||||
deleteEvent: vi.fn(),
|
||||
}));
|
||||
const microsoft = vi.hoisted(() => ({
|
||||
createGraphCalendarEvent: vi.fn(),
|
||||
patchGraphCalendarEvent: vi.fn(),
|
||||
deleteGraphCalendarEvent: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("./google/googleCalendarApi.js", () => google);
|
||||
vi.mock("./microsoft/graphCalendarApi.js", () => microsoft);
|
||||
|
||||
import {
|
||||
googleAdminBookingProvider,
|
||||
microsoftAdminBookingProvider,
|
||||
} from "./admin-booking-provider.server.js";
|
||||
|
||||
const event = {
|
||||
calendarId: "primary",
|
||||
subject: "HiveGrid Demo",
|
||||
bodyText: "Termin aus HiveGrid",
|
||||
startsAt: new Date("2026-08-03T08:00:00.000Z"),
|
||||
endsAt: new Date("2026-08-03T08:45:00.000Z"),
|
||||
timeZone: "Europe/Berlin",
|
||||
attendee: { email: "ada@example.com", name: "Ada Lovelace" },
|
||||
};
|
||||
|
||||
describe("admin booking provider adapters", () => {
|
||||
beforeEach(() => vi.clearAllMocks());
|
||||
|
||||
it("maps booking data to Google and preserves the opaque etag", async () => {
|
||||
google.insertEvent.mockResolvedValue({ id: "g-1", etag: "v1" });
|
||||
|
||||
await expect(
|
||||
googleAdminBookingProvider.createEvent("access", event)
|
||||
).resolves.toEqual({
|
||||
externalEventId: "g-1",
|
||||
opaqueVersion: "v1",
|
||||
});
|
||||
expect(google.insertEvent).toHaveBeenCalledWith(
|
||||
"access",
|
||||
"primary",
|
||||
expect.objectContaining({
|
||||
summary: "HiveGrid Demo",
|
||||
attendees: [{ email: "ada@example.com" }],
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("maps booking data to Microsoft and passes optimistic versions", async () => {
|
||||
microsoft.patchGraphCalendarEvent.mockResolvedValue({
|
||||
id: "m-1",
|
||||
changeKey: "v2",
|
||||
});
|
||||
|
||||
await expect(
|
||||
microsoftAdminBookingProvider.updateEvent(
|
||||
"access",
|
||||
"m-1",
|
||||
event,
|
||||
"v1"
|
||||
)
|
||||
).resolves.toEqual({
|
||||
externalEventId: "m-1",
|
||||
opaqueVersion: "v2",
|
||||
});
|
||||
expect(microsoft.patchGraphCalendarEvent).toHaveBeenCalledWith(
|
||||
"access",
|
||||
"primary",
|
||||
"m-1",
|
||||
expect.objectContaining({
|
||||
attendees: [
|
||||
{
|
||||
emailAddress: {
|
||||
address: "ada@example.com",
|
||||
name: "Ada Lovelace",
|
||||
},
|
||||
type: "required",
|
||||
},
|
||||
],
|
||||
}),
|
||||
"v1"
|
||||
);
|
||||
});
|
||||
|
||||
it("uses provider delete operations as the idempotent cancellation edge", async () => {
|
||||
await googleAdminBookingProvider.deleteEvent(
|
||||
"access",
|
||||
"primary",
|
||||
"g-1"
|
||||
);
|
||||
await microsoftAdminBookingProvider.deleteEvent(
|
||||
"access",
|
||||
"primary",
|
||||
"m-1"
|
||||
);
|
||||
|
||||
expect(google.deleteEvent).toHaveBeenCalledWith(
|
||||
"access",
|
||||
"primary",
|
||||
"g-1"
|
||||
);
|
||||
expect(microsoft.deleteGraphCalendarEvent).toHaveBeenCalledWith(
|
||||
"access",
|
||||
"primary",
|
||||
"m-1"
|
||||
);
|
||||
});
|
||||
});
|
||||
+152
@@ -0,0 +1,152 @@
|
||||
import {
|
||||
deleteEvent,
|
||||
insertEvent,
|
||||
patchEvent,
|
||||
} from "./google/googleCalendarApi.js";
|
||||
import {
|
||||
createGraphCalendarEvent,
|
||||
deleteGraphCalendarEvent,
|
||||
patchGraphCalendarEvent,
|
||||
} from "./microsoft/graphCalendarApi.js";
|
||||
|
||||
export type AdminBookingProviderEventInput = {
|
||||
readonly calendarId: string;
|
||||
readonly subject: string;
|
||||
readonly bodyText?: string | null;
|
||||
readonly startsAt: Date;
|
||||
readonly endsAt: Date;
|
||||
readonly timeZone: string;
|
||||
readonly attendee: {
|
||||
readonly email: string;
|
||||
readonly name: string;
|
||||
};
|
||||
};
|
||||
|
||||
export type AdminBookingProviderEventResult = {
|
||||
readonly externalEventId: string;
|
||||
readonly opaqueVersion?: string | null;
|
||||
};
|
||||
|
||||
export interface AdminBookingProviderPort {
|
||||
createEvent(
|
||||
accessToken: string,
|
||||
input: AdminBookingProviderEventInput
|
||||
): Promise<AdminBookingProviderEventResult>;
|
||||
updateEvent(
|
||||
accessToken: string,
|
||||
externalEventId: string,
|
||||
input: AdminBookingProviderEventInput,
|
||||
opaqueVersion?: string | null
|
||||
): Promise<AdminBookingProviderEventResult>;
|
||||
deleteEvent(
|
||||
accessToken: string,
|
||||
calendarId: string,
|
||||
externalEventId: string
|
||||
): Promise<void>;
|
||||
}
|
||||
|
||||
export const googleAdminBookingProvider: AdminBookingProviderPort = {
|
||||
async createEvent(accessToken, input) {
|
||||
const result = await insertEvent(
|
||||
accessToken,
|
||||
input.calendarId,
|
||||
toGoogleEvent(input)
|
||||
);
|
||||
return {
|
||||
externalEventId: result.id,
|
||||
opaqueVersion: result.etag,
|
||||
};
|
||||
},
|
||||
async updateEvent(
|
||||
accessToken,
|
||||
externalEventId,
|
||||
input,
|
||||
opaqueVersion
|
||||
) {
|
||||
const result = await patchEvent(
|
||||
accessToken,
|
||||
input.calendarId,
|
||||
externalEventId,
|
||||
toGoogleEvent(input),
|
||||
opaqueVersion ?? undefined
|
||||
);
|
||||
return {
|
||||
externalEventId: result.id,
|
||||
opaqueVersion: result.etag,
|
||||
};
|
||||
},
|
||||
deleteEvent,
|
||||
};
|
||||
|
||||
export const microsoftAdminBookingProvider: AdminBookingProviderPort = {
|
||||
async createEvent(accessToken, input) {
|
||||
const result = await createGraphCalendarEvent(
|
||||
accessToken,
|
||||
input.calendarId,
|
||||
toMicrosoftEvent(input)
|
||||
);
|
||||
return {
|
||||
externalEventId: result.id,
|
||||
opaqueVersion: result.changeKey,
|
||||
};
|
||||
},
|
||||
async updateEvent(
|
||||
accessToken,
|
||||
externalEventId,
|
||||
input,
|
||||
opaqueVersion
|
||||
) {
|
||||
const result = await patchGraphCalendarEvent(
|
||||
accessToken,
|
||||
input.calendarId,
|
||||
externalEventId,
|
||||
toMicrosoftEvent(input),
|
||||
opaqueVersion ?? undefined
|
||||
);
|
||||
return {
|
||||
externalEventId: result.id,
|
||||
opaqueVersion: result.changeKey,
|
||||
};
|
||||
},
|
||||
deleteEvent: deleteGraphCalendarEvent,
|
||||
};
|
||||
|
||||
function toGoogleEvent(input: AdminBookingProviderEventInput) {
|
||||
return {
|
||||
summary: input.subject,
|
||||
description: input.bodyText ?? undefined,
|
||||
start: {
|
||||
dateTime: input.startsAt.toISOString(),
|
||||
timeZone: input.timeZone,
|
||||
},
|
||||
end: {
|
||||
dateTime: input.endsAt.toISOString(),
|
||||
timeZone: input.timeZone,
|
||||
},
|
||||
attendees: [{ email: input.attendee.email }],
|
||||
};
|
||||
}
|
||||
|
||||
function toMicrosoftEvent(input: AdminBookingProviderEventInput) {
|
||||
return {
|
||||
subject: input.subject,
|
||||
bodyText: input.bodyText ?? undefined,
|
||||
start: {
|
||||
dateTime: input.startsAt.toISOString(),
|
||||
timeZone: input.timeZone,
|
||||
},
|
||||
end: {
|
||||
dateTime: input.endsAt.toISOString(),
|
||||
timeZone: input.timeZone,
|
||||
},
|
||||
attendees: [
|
||||
{
|
||||
emailAddress: {
|
||||
address: input.attendee.email,
|
||||
name: input.attendee.name,
|
||||
},
|
||||
type: "required" as const,
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
+382
@@ -0,0 +1,382 @@
|
||||
import {
|
||||
createAdminBookingLifecycleService,
|
||||
createPrismaAdminBookingLifecycleRepository,
|
||||
} from "@hivegrid/db/admin-booking-lifecycle.server";
|
||||
import type { DbClient } from "@hivegrid/db/client.server";
|
||||
import {
|
||||
openAdminConnectionCredentials,
|
||||
sealAdminConnectionCredentials,
|
||||
} from "@hivegrid/db/crypto/admin-connection-envelope.server";
|
||||
|
||||
import {
|
||||
googleAdminBookingProvider,
|
||||
microsoftAdminBookingProvider,
|
||||
type AdminBookingProviderPort,
|
||||
} from "./admin-booking-provider.server.js";
|
||||
import {
|
||||
refreshAccessToken,
|
||||
resolveGoogleOAuthConfig,
|
||||
} from "./google/googleCalendarApi.js";
|
||||
import {
|
||||
refreshMicrosoftCalendarToken,
|
||||
resolveMicrosoftCalendarOAuthConfig,
|
||||
} from "./microsoft/graphCalendarApi.js";
|
||||
|
||||
type AdminBookingWorkerClient = Pick<
|
||||
DbClient,
|
||||
| "$transaction"
|
||||
| "adminBooking"
|
||||
| "adminCalendarConnection"
|
||||
| "adminDataConnection"
|
||||
| "adminConnectionCredential"
|
||||
>;
|
||||
|
||||
type CredentialBundle = {
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken: string;
|
||||
readonly expiresAt: string;
|
||||
readonly scopes: readonly string[];
|
||||
};
|
||||
|
||||
type AdminBookingProviderEvent = {
|
||||
readonly bookingId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly calendarConnectionId: string;
|
||||
readonly provider: "google_calendar" | "microsoft_calendar";
|
||||
readonly accessToken: string;
|
||||
readonly externalEventId?: string | null;
|
||||
readonly externalEventVersion?: string | null;
|
||||
readonly calendarId: string;
|
||||
readonly subject: string;
|
||||
readonly bodyText?: string | null;
|
||||
readonly startsAt: Date;
|
||||
readonly endsAt: Date;
|
||||
readonly timeZone: string;
|
||||
readonly attendee: { readonly email: string; readonly name: string };
|
||||
};
|
||||
|
||||
type AdminBookingWorkerDependencies = {
|
||||
readonly loadEvent: (
|
||||
bookingId: string,
|
||||
adminUserId: string
|
||||
) => Promise<AdminBookingProviderEvent>;
|
||||
readonly createEvent: (
|
||||
event: AdminBookingProviderEvent
|
||||
) => Promise<{
|
||||
readonly externalEventId: string;
|
||||
readonly opaqueVersion?: string | null;
|
||||
}>;
|
||||
readonly updateEvent: (
|
||||
event: AdminBookingProviderEvent,
|
||||
externalEventId: string,
|
||||
opaqueVersion?: string | null
|
||||
) => Promise<{
|
||||
readonly externalEventId: string;
|
||||
readonly opaqueVersion?: string | null;
|
||||
}>;
|
||||
readonly deleteEvent: (event: AdminBookingProviderEvent) => Promise<void>;
|
||||
readonly confirm: (input: {
|
||||
readonly bookingId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly calendarConnectionId: string;
|
||||
readonly providerEventId: string;
|
||||
readonly providerEventVersion?: string | null;
|
||||
readonly syncedAt: Date;
|
||||
}) => Promise<void>;
|
||||
readonly markFailed: (input: {
|
||||
readonly bookingId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly errorCode: string;
|
||||
}) => Promise<void>;
|
||||
readonly now: () => Date;
|
||||
};
|
||||
|
||||
export function createAdminBookingOutboxDependencies(input: {
|
||||
readonly client: AdminBookingWorkerClient;
|
||||
readonly env?: NodeJS.ProcessEnv;
|
||||
readonly now?: () => Date;
|
||||
}): AdminBookingWorkerDependencies {
|
||||
const env = input.env ?? process.env;
|
||||
const now = input.now ?? (() => new Date());
|
||||
const lifecycle = createAdminBookingLifecycleService({
|
||||
repository: createPrismaAdminBookingLifecycleRepository(
|
||||
input.client as never
|
||||
),
|
||||
authorize: () => undefined,
|
||||
});
|
||||
|
||||
return {
|
||||
now,
|
||||
loadEvent: (bookingId, adminUserId) =>
|
||||
loadProviderEvent(input.client, {
|
||||
bookingId,
|
||||
adminUserId,
|
||||
env,
|
||||
now,
|
||||
}),
|
||||
createEvent: (event) =>
|
||||
providerFor(event.provider).createEvent(event.accessToken, event),
|
||||
updateEvent: (event, externalEventId, opaqueVersion) =>
|
||||
providerFor(event.provider).updateEvent(
|
||||
event.accessToken,
|
||||
externalEventId,
|
||||
event,
|
||||
opaqueVersion
|
||||
),
|
||||
deleteEvent: async (event) => {
|
||||
if (!event.externalEventId) return;
|
||||
await providerFor(event.provider).deleteEvent(
|
||||
event.accessToken,
|
||||
event.calendarId,
|
||||
event.externalEventId
|
||||
);
|
||||
},
|
||||
confirm: async (command) => {
|
||||
await lifecycle.confirmProviderEvent(command);
|
||||
},
|
||||
markFailed: async (command) => {
|
||||
await lifecycle.markProviderSyncFailed(command);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function loadProviderEvent(
|
||||
client: AdminBookingWorkerClient,
|
||||
input: {
|
||||
readonly bookingId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly env: NodeJS.ProcessEnv;
|
||||
readonly now: () => Date;
|
||||
}
|
||||
): Promise<AdminBookingProviderEvent> {
|
||||
const booking = await client.adminBooking.findFirst({
|
||||
where: { id: input.bookingId, adminUserId: input.adminUserId },
|
||||
include: {
|
||||
meetingType: { select: { name: true, description: true } },
|
||||
participants: {
|
||||
where: { isOrganizer: false },
|
||||
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
|
||||
take: 1,
|
||||
select: { email: true, name: true },
|
||||
},
|
||||
calendarConnection: {
|
||||
include: {
|
||||
dataConnection: {
|
||||
include: { credential: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
if (!booking) throw new AdminBookingWorkerError("booking_unavailable");
|
||||
|
||||
const calendar =
|
||||
booking.calendarConnection ??
|
||||
(await client.adminCalendarConnection.findFirst({
|
||||
where: {
|
||||
adminUserId: input.adminUserId,
|
||||
status: "active",
|
||||
archivedAt: null,
|
||||
dataConnection: {
|
||||
status: { in: ["active", "degraded"] },
|
||||
archivedAt: null,
|
||||
},
|
||||
},
|
||||
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
|
||||
include: {
|
||||
dataConnection: {
|
||||
include: { credential: true },
|
||||
},
|
||||
},
|
||||
}));
|
||||
if (!calendar) {
|
||||
throw new AdminBookingWorkerError("calendar_unavailable");
|
||||
}
|
||||
const provider = calendar.dataConnection.provider;
|
||||
if (
|
||||
provider !== "google_calendar" &&
|
||||
provider !== "microsoft_calendar"
|
||||
) {
|
||||
throw new AdminBookingWorkerError("provider_unavailable");
|
||||
}
|
||||
const credentials = await freshCredentials(client, {
|
||||
connection: calendar.dataConnection,
|
||||
provider,
|
||||
adminUserId: input.adminUserId,
|
||||
env: input.env,
|
||||
now: input.now,
|
||||
});
|
||||
const attendee = booking.participants[0];
|
||||
if (!attendee) throw new AdminBookingWorkerError("attendee_unavailable");
|
||||
|
||||
return {
|
||||
bookingId: booking.id,
|
||||
adminUserId: booking.adminUserId,
|
||||
calendarConnectionId: calendar.id,
|
||||
provider,
|
||||
accessToken: credentials.accessToken,
|
||||
externalEventId: booking.providerEventId,
|
||||
externalEventVersion: booking.providerEventVersion,
|
||||
calendarId: calendar.externalCalendarId,
|
||||
subject: booking.meetingType.name,
|
||||
bodyText: booking.meetingType.description,
|
||||
startsAt: booking.startsAt,
|
||||
endsAt: booking.endsAt,
|
||||
timeZone: calendar.timeZone,
|
||||
attendee,
|
||||
};
|
||||
}
|
||||
|
||||
async function freshCredentials(
|
||||
client: AdminBookingWorkerClient,
|
||||
input: {
|
||||
readonly connection: {
|
||||
readonly id: string;
|
||||
readonly adminUserId: string;
|
||||
readonly tokenExpiresAt: Date | null;
|
||||
readonly credential: {
|
||||
readonly wrappedDek: Uint8Array;
|
||||
readonly ciphertext: string;
|
||||
readonly keyVersion: number;
|
||||
readonly revokedAt: Date | null;
|
||||
} | null;
|
||||
};
|
||||
readonly provider: "google_calendar" | "microsoft_calendar";
|
||||
readonly adminUserId: string;
|
||||
readonly env: NodeJS.ProcessEnv;
|
||||
readonly now: () => Date;
|
||||
}
|
||||
): Promise<CredentialBundle> {
|
||||
const credential = input.connection.credential;
|
||||
if (
|
||||
input.connection.adminUserId !== input.adminUserId ||
|
||||
!credential ||
|
||||
credential.revokedAt
|
||||
) {
|
||||
throw new AdminBookingWorkerError("credential_unavailable");
|
||||
}
|
||||
const current = parseCredentialBundle(
|
||||
await openAdminConnectionCredentials(credential)
|
||||
);
|
||||
const expiresAt =
|
||||
input.connection.tokenExpiresAt ?? new Date(current.expiresAt);
|
||||
if (
|
||||
Number.isFinite(expiresAt.getTime()) &&
|
||||
expiresAt.getTime() > input.now().getTime() + 60_000
|
||||
) {
|
||||
return current;
|
||||
}
|
||||
|
||||
const refreshed =
|
||||
input.provider === "google_calendar"
|
||||
? await refreshGoogle(input.env, current)
|
||||
: await refreshMicrosoft(input.env, current);
|
||||
const envelope = await sealAdminConnectionCredentials(
|
||||
JSON.stringify(refreshed)
|
||||
);
|
||||
await client.$transaction(async (tx) => {
|
||||
await tx.adminDataConnection.update({
|
||||
where: {
|
||||
id: input.connection.id,
|
||||
adminUserId: input.adminUserId,
|
||||
},
|
||||
data: {
|
||||
status: "active",
|
||||
tokenExpiresAt: new Date(refreshed.expiresAt),
|
||||
scopes: [...refreshed.scopes],
|
||||
lastHealthCheckAt: input.now(),
|
||||
healthMessageKey:
|
||||
"admin.sales.booking.calendars.health.connected",
|
||||
},
|
||||
});
|
||||
await tx.adminConnectionCredential.update({
|
||||
where: { connectionId: input.connection.id },
|
||||
data: {
|
||||
wrappedDek: Uint8Array.from(envelope.wrappedDek),
|
||||
ciphertext: envelope.ciphertext,
|
||||
keyVersion: envelope.keyVersion,
|
||||
rotatedAt: input.now(),
|
||||
revokedAt: null,
|
||||
},
|
||||
});
|
||||
});
|
||||
return refreshed;
|
||||
}
|
||||
|
||||
async function refreshGoogle(
|
||||
env: NodeJS.ProcessEnv,
|
||||
current: CredentialBundle
|
||||
): Promise<CredentialBundle> {
|
||||
const config = resolveGoogleOAuthConfig(env);
|
||||
if (!config) throw new AdminBookingWorkerError("provider_not_configured");
|
||||
const refreshed = await refreshAccessToken(config, current.refreshToken);
|
||||
return {
|
||||
accessToken: refreshed.accessToken,
|
||||
refreshToken: refreshed.refreshToken ?? current.refreshToken,
|
||||
expiresAt: refreshed.expiresAt.toISOString(),
|
||||
scopes:
|
||||
refreshed.scopes.length > 0 ? refreshed.scopes : current.scopes,
|
||||
};
|
||||
}
|
||||
|
||||
async function refreshMicrosoft(
|
||||
env: NodeJS.ProcessEnv,
|
||||
current: CredentialBundle
|
||||
): Promise<CredentialBundle> {
|
||||
const config = resolveMicrosoftCalendarOAuthConfig(env);
|
||||
if (!config) throw new AdminBookingWorkerError("provider_not_configured");
|
||||
const refreshed = await refreshMicrosoftCalendarToken(
|
||||
config,
|
||||
current.refreshToken
|
||||
);
|
||||
return {
|
||||
accessToken: refreshed.accessToken,
|
||||
refreshToken: refreshed.refreshToken ?? current.refreshToken,
|
||||
expiresAt: refreshed.expiresAt.toISOString(),
|
||||
scopes:
|
||||
refreshed.scopes.length > 0 ? refreshed.scopes : current.scopes,
|
||||
};
|
||||
}
|
||||
|
||||
function parseCredentialBundle(value: string): CredentialBundle {
|
||||
let raw: unknown;
|
||||
try {
|
||||
raw = JSON.parse(value);
|
||||
} catch {
|
||||
throw new AdminBookingWorkerError("invalid_credential");
|
||||
}
|
||||
if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
|
||||
throw new AdminBookingWorkerError("invalid_credential");
|
||||
}
|
||||
const record = raw as Record<string, unknown>;
|
||||
if (
|
||||
typeof record.accessToken !== "string" ||
|
||||
typeof record.refreshToken !== "string" ||
|
||||
typeof record.expiresAt !== "string" ||
|
||||
!Array.isArray(record.scopes) ||
|
||||
record.scopes.some((scope) => typeof scope !== "string")
|
||||
) {
|
||||
throw new AdminBookingWorkerError("invalid_credential");
|
||||
}
|
||||
return {
|
||||
accessToken: record.accessToken,
|
||||
refreshToken: record.refreshToken,
|
||||
expiresAt: record.expiresAt,
|
||||
scopes: record.scopes as string[],
|
||||
};
|
||||
}
|
||||
|
||||
function providerFor(
|
||||
provider: AdminBookingProviderEvent["provider"]
|
||||
): AdminBookingProviderPort {
|
||||
return provider === "google_calendar"
|
||||
? googleAdminBookingProvider
|
||||
: microsoftAdminBookingProvider;
|
||||
}
|
||||
|
||||
export class AdminBookingWorkerError extends Error {
|
||||
constructor(readonly code: string) {
|
||||
super(code);
|
||||
this.name = "AdminBookingWorkerError";
|
||||
}
|
||||
}
|
||||
+120
@@ -0,0 +1,120 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { createAdminCalendarOAuthGateway } from "./admin-calendar-oauth.server.js";
|
||||
|
||||
const originalFetch = globalThis.fetch;
|
||||
|
||||
afterEach(() => {
|
||||
globalThis.fetch = originalFetch;
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe("admin calendar OAuth gateway", () => {
|
||||
it("exchanges a Google grant and selects the primary calendar", async () => {
|
||||
globalThis.fetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({
|
||||
access_token: "google-access",
|
||||
refresh_token: "google-refresh",
|
||||
expires_in: 3600,
|
||||
scope:
|
||||
"https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.freebusy openid email",
|
||||
})
|
||||
)
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({ sub: "google-1", email: "sales@example.test" })
|
||||
)
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({
|
||||
items: [
|
||||
{ id: "secondary", summary: "Other" },
|
||||
{ id: "primary", summary: "Sales", primary: true },
|
||||
],
|
||||
})
|
||||
);
|
||||
const gateway = createAdminCalendarOAuthGateway({
|
||||
GOOGLE_CALENDAR_CLIENT_ID: "client",
|
||||
GOOGLE_CALENDAR_CLIENT_SECRET: "secret",
|
||||
GOOGLE_CALENDAR_REDIRECT_URI: "https://admin.example.test/callback",
|
||||
});
|
||||
|
||||
const grant = await gateway.exchange("google_calendar", "code");
|
||||
|
||||
expect(grant).toMatchObject({
|
||||
account: {
|
||||
externalAccountId: "google-1",
|
||||
emailAddress: "sales@example.test",
|
||||
},
|
||||
calendar: {
|
||||
externalCalendarId: "primary",
|
||||
label: "Sales",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("exchanges a Microsoft grant and selects an editable default calendar", async () => {
|
||||
globalThis.fetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({
|
||||
access_token: "microsoft-access",
|
||||
refresh_token: "microsoft-refresh",
|
||||
expires_in: 3600,
|
||||
scope: "offline_access Calendars.ReadWrite User.Read",
|
||||
})
|
||||
)
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({
|
||||
id: "microsoft-1",
|
||||
mail: "sales@example.test",
|
||||
displayName: "Sales",
|
||||
})
|
||||
)
|
||||
.mockResolvedValueOnce(
|
||||
Response.json({
|
||||
value: [
|
||||
{
|
||||
id: "calendar-1",
|
||||
name: "Sales",
|
||||
isDefaultCalendar: true,
|
||||
canEdit: true,
|
||||
},
|
||||
],
|
||||
})
|
||||
);
|
||||
const gateway = createAdminCalendarOAuthGateway({
|
||||
MICROSOFT_CALENDAR_CLIENT_ID: "client",
|
||||
MICROSOFT_CALENDAR_CLIENT_SECRET: "secret",
|
||||
MICROSOFT_CALENDAR_REDIRECT_URI:
|
||||
"https://admin.example.test/callback",
|
||||
});
|
||||
|
||||
const grant = await gateway.exchange("microsoft_calendar", "code");
|
||||
|
||||
expect(grant).toMatchObject({
|
||||
account: {
|
||||
externalAccountId: "microsoft-1",
|
||||
emailAddress: "sales@example.test",
|
||||
},
|
||||
calendar: {
|
||||
externalCalendarId: "calendar-1",
|
||||
label: "Sales",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("exposes provider-specific authorization URLs without credentials", () => {
|
||||
const gateway = createAdminCalendarOAuthGateway({
|
||||
GOOGLE_CALENDAR_CLIENT_ID: "client",
|
||||
GOOGLE_CALENDAR_CLIENT_SECRET: "secret",
|
||||
GOOGLE_CALENDAR_REDIRECT_URI: "https://admin.example.test/callback",
|
||||
});
|
||||
const url = new URL(
|
||||
gateway.authorizationUrl("google_calendar", "state-1")
|
||||
);
|
||||
expect(url.hostname).toBe("accounts.google.com");
|
||||
expect(url.searchParams.get("state")).toBe("state-1");
|
||||
expect(url.searchParams.get("scope")).toContain("calendar.freebusy");
|
||||
});
|
||||
});
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
import {
|
||||
assertAdminCalendarScopes,
|
||||
type AdminCalendarProviderName,
|
||||
} from "./admin-calendar-provider.js";
|
||||
import {
|
||||
buildAuthorizationUrl,
|
||||
exchangeCodeForTokens,
|
||||
fetchUserInfo,
|
||||
listCalendars,
|
||||
resolveGoogleOAuthConfig,
|
||||
} from "./google/googleCalendarApi.js";
|
||||
import {
|
||||
buildMicrosoftCalendarAuthorizationUrl,
|
||||
exchangeMicrosoftCalendarCode,
|
||||
fetchGraphCalendarProfile,
|
||||
listGraphCalendars,
|
||||
resolveMicrosoftCalendarOAuthConfig,
|
||||
} from "./microsoft/graphCalendarApi.js";
|
||||
|
||||
export type AdminCalendarOAuthGrant = {
|
||||
readonly account: {
|
||||
readonly externalAccountId: string;
|
||||
readonly emailAddress: string;
|
||||
readonly displayName: string;
|
||||
};
|
||||
readonly calendar: {
|
||||
readonly externalCalendarId: string;
|
||||
readonly label: string;
|
||||
readonly timeZone: string;
|
||||
};
|
||||
readonly credentials: {
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken: string;
|
||||
readonly expiresAt: string;
|
||||
readonly scopes: readonly string[];
|
||||
};
|
||||
};
|
||||
|
||||
export function createAdminCalendarOAuthGateway(
|
||||
env: NodeJS.ProcessEnv = process.env
|
||||
) {
|
||||
return {
|
||||
configured(provider: AdminCalendarProviderName): boolean {
|
||||
return provider === "google_calendar"
|
||||
? Boolean(resolveGoogleOAuthConfig(env))
|
||||
: Boolean(resolveMicrosoftCalendarOAuthConfig(env));
|
||||
},
|
||||
|
||||
authorizationUrl(
|
||||
provider: AdminCalendarProviderName,
|
||||
state: string
|
||||
): string {
|
||||
if (provider === "google_calendar") {
|
||||
const config = resolveGoogleOAuthConfig(env);
|
||||
if (!config) throw new AdminCalendarOAuthError("not_configured");
|
||||
return buildAuthorizationUrl(config, state);
|
||||
}
|
||||
const config = resolveMicrosoftCalendarOAuthConfig(env);
|
||||
if (!config) throw new AdminCalendarOAuthError("not_configured");
|
||||
return buildMicrosoftCalendarAuthorizationUrl(config, state);
|
||||
},
|
||||
|
||||
async exchange(
|
||||
provider: AdminCalendarProviderName,
|
||||
code: string
|
||||
): Promise<AdminCalendarOAuthGrant> {
|
||||
const normalizedCode = required(code, "code");
|
||||
if (provider === "google_calendar") {
|
||||
const config = resolveGoogleOAuthConfig(env);
|
||||
if (!config) throw new AdminCalendarOAuthError("not_configured");
|
||||
const tokens = await exchangeCodeForTokens(config, normalizedCode);
|
||||
const refreshToken = required(
|
||||
tokens.refreshToken,
|
||||
"refresh_token"
|
||||
);
|
||||
assertAdminCalendarScopes(provider, tokens.scopes);
|
||||
const [profile, calendars] = await Promise.all([
|
||||
fetchUserInfo(tokens.accessToken),
|
||||
listCalendars(tokens.accessToken),
|
||||
]);
|
||||
const calendar =
|
||||
calendars.find((candidate) => candidate.primary) ?? calendars[0];
|
||||
if (!profile.sub || !profile.email || !calendar) {
|
||||
throw new AdminCalendarOAuthError("account_unavailable");
|
||||
}
|
||||
return {
|
||||
account: {
|
||||
externalAccountId: profile.sub,
|
||||
emailAddress: profile.email,
|
||||
displayName: profile.email,
|
||||
},
|
||||
calendar: {
|
||||
externalCalendarId: calendar.id,
|
||||
label: calendar.summary,
|
||||
timeZone: "Europe/Berlin",
|
||||
},
|
||||
credentials: {
|
||||
accessToken: tokens.accessToken,
|
||||
refreshToken,
|
||||
expiresAt: tokens.expiresAt.toISOString(),
|
||||
scopes: tokens.scopes,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const config = resolveMicrosoftCalendarOAuthConfig(env);
|
||||
if (!config) throw new AdminCalendarOAuthError("not_configured");
|
||||
const tokens = await exchangeMicrosoftCalendarCode(
|
||||
config,
|
||||
normalizedCode
|
||||
);
|
||||
const refreshToken = required(
|
||||
tokens.refreshToken,
|
||||
"refresh_token"
|
||||
);
|
||||
assertAdminCalendarScopes(provider, tokens.scopes);
|
||||
const [profile, calendars] = await Promise.all([
|
||||
fetchGraphCalendarProfile(tokens.accessToken),
|
||||
listGraphCalendars(tokens.accessToken),
|
||||
]);
|
||||
const calendar =
|
||||
calendars.find(
|
||||
(candidate) => candidate.isDefault && candidate.canEdit
|
||||
) ?? calendars.find((candidate) => candidate.canEdit);
|
||||
if (!profile.id || !profile.email || !calendar) {
|
||||
throw new AdminCalendarOAuthError("account_unavailable");
|
||||
}
|
||||
return {
|
||||
account: {
|
||||
externalAccountId: profile.id,
|
||||
emailAddress: profile.email,
|
||||
displayName: profile.displayName || profile.email,
|
||||
},
|
||||
calendar: {
|
||||
externalCalendarId: calendar.id,
|
||||
label: calendar.name,
|
||||
timeZone: "Europe/Berlin",
|
||||
},
|
||||
credentials: {
|
||||
accessToken: tokens.accessToken,
|
||||
refreshToken,
|
||||
expiresAt: tokens.expiresAt.toISOString(),
|
||||
scopes: tokens.scopes,
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function required(value: string | undefined, field: string): string {
|
||||
const normalized = value?.trim() ?? "";
|
||||
if (!normalized || normalized.length > 4_096) {
|
||||
throw new AdminCalendarOAuthError(`invalid_${field}`);
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
export class AdminCalendarOAuthError extends Error {
|
||||
constructor(readonly code: string) {
|
||||
super(code);
|
||||
this.name = "AdminCalendarOAuthError";
|
||||
}
|
||||
}
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
assertAdminCalendarScopes,
|
||||
mergeBusyIntervalDelta,
|
||||
projectGoogleBusyIntervals,
|
||||
projectMicrosoftBusyIntervals,
|
||||
} from "./admin-calendar-provider.js";
|
||||
|
||||
describe("admin calendar provider contract", () => {
|
||||
it("requires the complete provider-specific delegated scope set", () => {
|
||||
expect(() =>
|
||||
assertAdminCalendarScopes("microsoft_calendar", [
|
||||
"offline_access",
|
||||
"Calendars.ReadWrite",
|
||||
])
|
||||
).toThrowError(
|
||||
expect.objectContaining({
|
||||
code: "missing_required_scopes",
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("projects Google events to anonymous, stable busy intervals", () => {
|
||||
const result = projectGoogleBusyIntervals([
|
||||
{
|
||||
id: "private-event",
|
||||
summary: "Vertraulicher Termin",
|
||||
description: "darf nicht gespeichert werden",
|
||||
start: { dateTime: "2026-07-28T10:00:00+02:00" },
|
||||
end: { dateTime: "2026-07-28T11:00:00+02:00" },
|
||||
etag: "v1",
|
||||
},
|
||||
{
|
||||
id: "free-event",
|
||||
transparency: "transparent",
|
||||
start: { dateTime: "2026-07-28T12:00:00+02:00" },
|
||||
end: { dateTime: "2026-07-28T13:00:00+02:00" },
|
||||
},
|
||||
]);
|
||||
expect(result).toEqual([
|
||||
{
|
||||
externalEventId: "private-event",
|
||||
startsAt: "2026-07-28T08:00:00.000Z",
|
||||
endsAt: "2026-07-28T09:00:00.000Z",
|
||||
opaqueVersion: "v1",
|
||||
},
|
||||
]);
|
||||
expect(JSON.stringify(result)).not.toContain("Vertraulicher");
|
||||
});
|
||||
|
||||
it("drops free, cancelled and removed Microsoft events", () => {
|
||||
const result = projectMicrosoftBusyIntervals([
|
||||
{
|
||||
id: "busy",
|
||||
start: { dateTime: "2026-07-28T08:00:00Z" },
|
||||
end: { dateTime: "2026-07-28T09:00:00Z" },
|
||||
showAs: "busy",
|
||||
},
|
||||
{
|
||||
id: "free",
|
||||
start: { dateTime: "2026-07-28T09:00:00Z" },
|
||||
end: { dateTime: "2026-07-28T10:00:00Z" },
|
||||
showAs: "free",
|
||||
},
|
||||
{
|
||||
id: "removed",
|
||||
"@removed": { reason: "deleted" },
|
||||
},
|
||||
]);
|
||||
expect(result.map((entry) => entry.externalEventId)).toEqual(["busy"]);
|
||||
});
|
||||
|
||||
it("replaces changed events and removes provider tombstones deterministically", () => {
|
||||
expect(
|
||||
mergeBusyIntervalDelta({
|
||||
current: [
|
||||
{
|
||||
externalEventId: "changed",
|
||||
startsAt: "2026-07-28T08:00:00Z",
|
||||
endsAt: "2026-07-28T09:00:00Z",
|
||||
},
|
||||
{
|
||||
externalEventId: "deleted",
|
||||
startsAt: "2026-07-28T10:00:00Z",
|
||||
endsAt: "2026-07-28T11:00:00Z",
|
||||
},
|
||||
],
|
||||
upserts: [
|
||||
{
|
||||
externalEventId: "changed",
|
||||
startsAt: "2026-07-28T09:00:00Z",
|
||||
endsAt: "2026-07-28T10:00:00Z",
|
||||
},
|
||||
],
|
||||
removedExternalEventIds: ["deleted"],
|
||||
})
|
||||
).toEqual([
|
||||
{
|
||||
externalEventId: "changed",
|
||||
startsAt: "2026-07-28T09:00:00.000Z",
|
||||
endsAt: "2026-07-28T10:00:00.000Z",
|
||||
opaqueVersion: undefined,
|
||||
},
|
||||
]);
|
||||
});
|
||||
});
|
||||
+174
@@ -0,0 +1,174 @@
|
||||
import type { GoogleEvent } from "./google/googleCalendarApi.js";
|
||||
import type { GraphCalendarEvent } from "./microsoft/graphCalendarApi.js";
|
||||
|
||||
export type AdminCalendarProviderName =
|
||||
| "google_calendar"
|
||||
| "microsoft_calendar";
|
||||
|
||||
export const GOOGLE_ADMIN_CALENDAR_SCOPES = [
|
||||
"https://www.googleapis.com/auth/calendar.events",
|
||||
"https://www.googleapis.com/auth/calendar.freebusy",
|
||||
"openid",
|
||||
"email",
|
||||
] as const;
|
||||
|
||||
export const ADMIN_CALENDAR_CONNECTION_REGISTRY = Object.freeze({
|
||||
google_calendar: Object.freeze({
|
||||
provider: "google_calendar",
|
||||
capability: "calendar",
|
||||
requiredScopes: GOOGLE_ADMIN_CALENDAR_SCOPES,
|
||||
refreshTokenRotation: false,
|
||||
cursorKind: "sync_token",
|
||||
}),
|
||||
microsoft_calendar: Object.freeze({
|
||||
provider: "microsoft_calendar",
|
||||
capability: "calendar",
|
||||
requiredScopes: [
|
||||
"offline_access",
|
||||
"Calendars.ReadWrite",
|
||||
"User.Read",
|
||||
] as const,
|
||||
refreshTokenRotation: true,
|
||||
cursorKind: "delta_link",
|
||||
}),
|
||||
} satisfies Record<
|
||||
AdminCalendarProviderName,
|
||||
{
|
||||
readonly provider: AdminCalendarProviderName;
|
||||
readonly capability: "calendar";
|
||||
readonly requiredScopes: readonly string[];
|
||||
readonly refreshTokenRotation: boolean;
|
||||
readonly cursorKind: "sync_token" | "delta_link";
|
||||
}
|
||||
>);
|
||||
|
||||
export interface AdminBusyInterval {
|
||||
readonly externalEventId: string;
|
||||
readonly startsAt: string;
|
||||
readonly endsAt: string;
|
||||
readonly opaqueVersion?: string;
|
||||
}
|
||||
|
||||
export function assertAdminCalendarScopes(
|
||||
provider: AdminCalendarProviderName,
|
||||
scopes: readonly string[]
|
||||
): void {
|
||||
const granted = new Set(scopes.map((scope) => scope.trim()).filter(Boolean));
|
||||
const missing = ADMIN_CALENDAR_CONNECTION_REGISTRY[
|
||||
provider
|
||||
].requiredScopes.filter((scope) => !granted.has(scope));
|
||||
if (missing.length > 0) {
|
||||
throw new AdminCalendarProviderContractError("missing_required_scopes", {
|
||||
provider,
|
||||
missing,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
export function projectGoogleBusyIntervals(
|
||||
events: readonly GoogleEvent[]
|
||||
): readonly AdminBusyInterval[] {
|
||||
return normalizeBusyIntervals(
|
||||
events
|
||||
.filter(
|
||||
(event) =>
|
||||
event.status !== "cancelled" && event.transparency !== "transparent"
|
||||
)
|
||||
.flatMap((event) => {
|
||||
const startsAt = event.start?.dateTime;
|
||||
const endsAt = event.end?.dateTime;
|
||||
if (!startsAt || !endsAt) return [];
|
||||
return [
|
||||
{
|
||||
externalEventId: event.id,
|
||||
startsAt,
|
||||
endsAt,
|
||||
opaqueVersion: event.etag,
|
||||
},
|
||||
];
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
export function projectMicrosoftBusyIntervals(
|
||||
events: readonly GraphCalendarEvent[]
|
||||
): readonly AdminBusyInterval[] {
|
||||
return normalizeBusyIntervals(
|
||||
events
|
||||
.filter(
|
||||
(event) =>
|
||||
!event["@removed"] &&
|
||||
!event.isCancelled &&
|
||||
event.showAs !== "free" &&
|
||||
event.showAs !== "workingElsewhere"
|
||||
)
|
||||
.flatMap((event) => {
|
||||
const startsAt = event.start?.dateTime;
|
||||
const endsAt = event.end?.dateTime;
|
||||
if (!startsAt || !endsAt) return [];
|
||||
return [
|
||||
{
|
||||
externalEventId: event.id,
|
||||
startsAt,
|
||||
endsAt,
|
||||
opaqueVersion: event.changeKey,
|
||||
},
|
||||
];
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
export function normalizeBusyIntervals(
|
||||
intervals: readonly AdminBusyInterval[]
|
||||
): readonly AdminBusyInterval[] {
|
||||
const byEvent = new Map<string, AdminBusyInterval>();
|
||||
for (const interval of intervals) {
|
||||
const startsAt = new Date(interval.startsAt);
|
||||
const endsAt = new Date(interval.endsAt);
|
||||
if (
|
||||
!interval.externalEventId.trim() ||
|
||||
!Number.isFinite(startsAt.getTime()) ||
|
||||
!Number.isFinite(endsAt.getTime()) ||
|
||||
endsAt <= startsAt
|
||||
) {
|
||||
continue;
|
||||
}
|
||||
byEvent.set(interval.externalEventId, {
|
||||
externalEventId: interval.externalEventId,
|
||||
startsAt: startsAt.toISOString(),
|
||||
endsAt: endsAt.toISOString(),
|
||||
opaqueVersion: interval.opaqueVersion,
|
||||
});
|
||||
}
|
||||
return Object.freeze(
|
||||
[...byEvent.values()].sort(
|
||||
(left, right) =>
|
||||
Date.parse(left.startsAt) - Date.parse(right.startsAt) ||
|
||||
left.externalEventId.localeCompare(right.externalEventId)
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
export function mergeBusyIntervalDelta(input: {
|
||||
readonly current: readonly AdminBusyInterval[];
|
||||
readonly upserts: readonly AdminBusyInterval[];
|
||||
readonly removedExternalEventIds: readonly string[];
|
||||
}): readonly AdminBusyInterval[] {
|
||||
const removed = new Set(
|
||||
input.removedExternalEventIds.map((id) => id.trim()).filter(Boolean)
|
||||
);
|
||||
const retained = input.current.filter(
|
||||
(interval) => !removed.has(interval.externalEventId)
|
||||
);
|
||||
return normalizeBusyIntervals([...retained, ...input.upserts]);
|
||||
}
|
||||
|
||||
export class AdminCalendarProviderContractError extends Error {
|
||||
constructor(
|
||||
readonly code: "missing_required_scopes",
|
||||
readonly details: Readonly<Record<string, unknown>>
|
||||
) {
|
||||
super(code);
|
||||
this.name = "AdminCalendarProviderContractError";
|
||||
}
|
||||
}
|
||||
+99
@@ -0,0 +1,99 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
syncGoogleCalendarBusySnapshot,
|
||||
syncMicrosoftCalendarBusySnapshot,
|
||||
} from "./admin-calendar-sync-worker.server.js";
|
||||
|
||||
const originalFetch = globalThis.fetch;
|
||||
|
||||
afterEach(() => {
|
||||
globalThis.fetch = originalFetch;
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe("admin calendar busy snapshot sync", () => {
|
||||
it("applies Google deltas without retaining private event content", async () => {
|
||||
globalThis.fetch = vi.fn(async () =>
|
||||
Response.json({
|
||||
items: [
|
||||
{
|
||||
id: "busy-1",
|
||||
summary: "Private title",
|
||||
description: "Private details",
|
||||
start: { dateTime: "2026-07-26T08:00:00.000Z" },
|
||||
end: { dateTime: "2026-07-26T09:00:00.000Z" },
|
||||
etag: "v1",
|
||||
},
|
||||
{ id: "old", status: "cancelled" },
|
||||
],
|
||||
nextSyncToken: "cursor-2",
|
||||
})
|
||||
);
|
||||
const result = await syncGoogleCalendarBusySnapshot({
|
||||
provider: "google_calendar",
|
||||
accessToken: "token",
|
||||
externalCalendarId: "primary",
|
||||
cursorToken: "cursor-1",
|
||||
deltaLink: null,
|
||||
busyIntervals: [
|
||||
{
|
||||
externalEventId: "old",
|
||||
startsAt: "2026-07-25T08:00:00.000Z",
|
||||
endsAt: "2026-07-25T09:00:00.000Z",
|
||||
},
|
||||
],
|
||||
now: new Date("2026-07-25T10:00:00.000Z"),
|
||||
});
|
||||
expect(result).toEqual({
|
||||
busyIntervals: [
|
||||
{
|
||||
externalEventId: "busy-1",
|
||||
startsAt: "2026-07-26T08:00:00.000Z",
|
||||
endsAt: "2026-07-26T09:00:00.000Z",
|
||||
opaqueVersion: "v1",
|
||||
},
|
||||
],
|
||||
cursorToken: "cursor-2",
|
||||
deltaLink: null,
|
||||
});
|
||||
expect(JSON.stringify(result)).not.toContain("Private");
|
||||
});
|
||||
|
||||
it("applies Microsoft delta links and removes free events", async () => {
|
||||
globalThis.fetch = vi.fn(async () =>
|
||||
Response.json({
|
||||
value: [
|
||||
{
|
||||
id: "busy-2",
|
||||
start: { dateTime: "2026-07-27T08:00:00.000Z" },
|
||||
end: { dateTime: "2026-07-27T09:00:00.000Z" },
|
||||
showAs: "busy",
|
||||
changeKey: "v2",
|
||||
},
|
||||
{ id: "old", showAs: "free" },
|
||||
],
|
||||
"@odata.deltaLink":
|
||||
"https://graph.microsoft.com/v1.0/me/calendars/c/delta?$deltatoken=2",
|
||||
})
|
||||
);
|
||||
const result = await syncMicrosoftCalendarBusySnapshot({
|
||||
provider: "microsoft_calendar",
|
||||
accessToken: "token",
|
||||
externalCalendarId: "calendar",
|
||||
cursorToken: null,
|
||||
deltaLink:
|
||||
"https://graph.microsoft.com/v1.0/me/calendars/c/delta?$deltatoken=1",
|
||||
busyIntervals: [
|
||||
{
|
||||
externalEventId: "old",
|
||||
startsAt: "2026-07-25T08:00:00.000Z",
|
||||
endsAt: "2026-07-25T09:00:00.000Z",
|
||||
},
|
||||
],
|
||||
now: new Date("2026-07-25T10:00:00.000Z"),
|
||||
});
|
||||
expect(result.busyIntervals).toHaveLength(1);
|
||||
expect(result.busyIntervals[0]?.externalEventId).toBe("busy-2");
|
||||
expect(result.deltaLink).toContain("$deltatoken=2");
|
||||
});
|
||||
});
|
||||
+368
@@ -0,0 +1,368 @@
|
||||
import {
|
||||
createAdminCalendarService,
|
||||
createPrismaAdminCalendarRepository,
|
||||
type AdminCalendarBusyInterval,
|
||||
} from "@hivegrid/db/admin-calendar.server";
|
||||
import {
|
||||
createAdminConnectionsService,
|
||||
createPrismaAdminConnectionsRepository,
|
||||
} from "@hivegrid/db/admin-connections.server";
|
||||
import {
|
||||
GoogleCalendarError,
|
||||
listEvents,
|
||||
refreshAccessToken,
|
||||
resolveGoogleOAuthConfig,
|
||||
} from "./google/googleCalendarApi.js";
|
||||
import {
|
||||
buildInitialCalendarDeltaUrl,
|
||||
fetchCalendarDeltaPage,
|
||||
GraphCalendarError,
|
||||
refreshMicrosoftCalendarToken,
|
||||
resolveMicrosoftCalendarOAuthConfig,
|
||||
} from "./microsoft/graphCalendarApi.js";
|
||||
|
||||
type Provider = "google_calendar" | "microsoft_calendar";
|
||||
type SyncTarget = {
|
||||
readonly id: string;
|
||||
readonly adminUserId: string;
|
||||
readonly calendarConnectionId: string;
|
||||
readonly externalCalendarId: string;
|
||||
readonly cursorToken: string | null;
|
||||
readonly deltaLink: string | null;
|
||||
readonly busyIntervals: unknown;
|
||||
readonly status: string;
|
||||
readonly calendarConnection: {
|
||||
readonly dataConnectionId: string;
|
||||
readonly dataConnection: {
|
||||
readonly provider: Provider;
|
||||
readonly tokenExpiresAt: Date | null;
|
||||
};
|
||||
};
|
||||
};
|
||||
|
||||
export type AdminCalendarSyncWorkerClient = {
|
||||
readonly $transaction: (...args: never[]) => Promise<unknown>;
|
||||
readonly adminCalendarSyncCursor: {
|
||||
findMany(input: Record<string, unknown>): Promise<SyncTarget[]>;
|
||||
};
|
||||
};
|
||||
|
||||
type Credentials = {
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken: string;
|
||||
readonly expiresAt: string;
|
||||
readonly scopes: readonly string[];
|
||||
};
|
||||
|
||||
export type AdminCalendarProviderSyncInput = {
|
||||
readonly provider: Provider;
|
||||
readonly accessToken: string;
|
||||
readonly externalCalendarId: string;
|
||||
readonly cursorToken: string | null;
|
||||
readonly deltaLink: string | null;
|
||||
readonly busyIntervals: readonly AdminCalendarBusyInterval[];
|
||||
readonly now: Date;
|
||||
};
|
||||
|
||||
export async function syncAdminCalendarBusySnapshots(
|
||||
client: AdminCalendarSyncWorkerClient,
|
||||
options: {
|
||||
readonly now?: Date;
|
||||
readonly take?: number;
|
||||
readonly env?: NodeJS.ProcessEnv;
|
||||
readonly provider?: typeof defaultProvider;
|
||||
} = {}
|
||||
) {
|
||||
const now = options.now ?? new Date();
|
||||
const targets = await client.adminCalendarSyncCursor.findMany({
|
||||
where: {
|
||||
status: { in: ["pending", "active", "recovery_required", "failed"] },
|
||||
calendarConnection: {
|
||||
status: { in: ["active", "degraded"] },
|
||||
archivedAt: null,
|
||||
dataConnection: {
|
||||
status: { in: ["active", "degraded"] },
|
||||
archivedAt: null,
|
||||
},
|
||||
},
|
||||
},
|
||||
orderBy: [{ lastIncrementalSyncAt: "asc" }, { id: "asc" }],
|
||||
take: options.take ?? 25,
|
||||
select: {
|
||||
id: true,
|
||||
adminUserId: true,
|
||||
calendarConnectionId: true,
|
||||
externalCalendarId: true,
|
||||
cursorToken: true,
|
||||
deltaLink: true,
|
||||
busyIntervals: true,
|
||||
status: true,
|
||||
calendarConnection: {
|
||||
select: {
|
||||
dataConnectionId: true,
|
||||
dataConnection: {
|
||||
select: { provider: true, tokenExpiresAt: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
const connections = createAdminConnectionsService({
|
||||
repository: createPrismaAdminConnectionsRepository(client as never),
|
||||
authorize: () => undefined,
|
||||
permission: "admin_sales.booking.manage",
|
||||
});
|
||||
const calendars = createAdminCalendarService({
|
||||
repository: createPrismaAdminCalendarRepository(client as never),
|
||||
authorize: () => undefined,
|
||||
});
|
||||
const provider = options.provider ?? defaultProvider;
|
||||
const failed: string[] = [];
|
||||
let synced = 0;
|
||||
for (const target of targets) {
|
||||
try {
|
||||
await connections.withCredentials(
|
||||
target.calendarConnection.dataConnectionId,
|
||||
target.adminUserId,
|
||||
async (raw) => {
|
||||
let credentials = parseCredentials(raw);
|
||||
if (
|
||||
new Date(credentials.expiresAt).getTime() <=
|
||||
now.getTime() + 60_000
|
||||
) {
|
||||
credentials = await provider.refresh(
|
||||
target.calendarConnection.dataConnection.provider,
|
||||
credentials,
|
||||
options.env ?? process.env
|
||||
);
|
||||
await connections.refresh({
|
||||
connectionId: target.calendarConnection.dataConnectionId,
|
||||
adminUserId: target.adminUserId,
|
||||
credentials,
|
||||
scopes: credentials.scopes,
|
||||
tokenExpiresAt: new Date(credentials.expiresAt),
|
||||
actor: {
|
||||
adminUserId: target.adminUserId,
|
||||
email: "system@worker.invalid",
|
||||
reason: "Automatische Kalender-Token-Erneuerung",
|
||||
},
|
||||
});
|
||||
}
|
||||
const fullSync = target.status === "recovery_required";
|
||||
const result = await provider.sync({
|
||||
provider:
|
||||
target.calendarConnection.dataConnection.provider,
|
||||
accessToken: credentials.accessToken,
|
||||
externalCalendarId: target.externalCalendarId,
|
||||
cursorToken: fullSync ? null : target.cursorToken,
|
||||
deltaLink: fullSync ? null : target.deltaLink,
|
||||
busyIntervals: parseBusyIntervals(target.busyIntervals),
|
||||
now,
|
||||
});
|
||||
await calendars.applySync({
|
||||
adminUserId: target.adminUserId,
|
||||
calendarConnectionId: target.calendarConnectionId,
|
||||
externalCalendarId: target.externalCalendarId,
|
||||
busyIntervals: result.busyIntervals,
|
||||
cursorToken: result.cursorToken,
|
||||
deltaLink: result.deltaLink,
|
||||
fullSync: fullSync || (!target.cursorToken && !target.deltaLink),
|
||||
syncedAt: now,
|
||||
});
|
||||
}
|
||||
);
|
||||
synced += 1;
|
||||
} catch (error) {
|
||||
failed.push(target.id);
|
||||
if (
|
||||
(error instanceof GoogleCalendarError &&
|
||||
error.fullResyncRequired) ||
|
||||
(error instanceof GraphCalendarError &&
|
||||
error.fullResyncRequired)
|
||||
) {
|
||||
await calendars.requireRecovery({
|
||||
adminUserId: target.adminUserId,
|
||||
calendarConnectionId: target.calendarConnectionId,
|
||||
externalCalendarId: target.externalCalendarId,
|
||||
errorCode: "provider_cursor_expired",
|
||||
requestedAt: now,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return { inspected: targets.length, synced, failed };
|
||||
}
|
||||
|
||||
const defaultProvider = {
|
||||
async refresh(
|
||||
provider: Provider,
|
||||
current: Credentials,
|
||||
env: NodeJS.ProcessEnv
|
||||
): Promise<Credentials> {
|
||||
if (provider === "google_calendar") {
|
||||
const config = resolveGoogleOAuthConfig(env);
|
||||
if (!config) throw new Error("provider_not_configured");
|
||||
const next = await refreshAccessToken(config, current.refreshToken);
|
||||
return {
|
||||
accessToken: next.accessToken,
|
||||
refreshToken: next.refreshToken ?? current.refreshToken,
|
||||
expiresAt: next.expiresAt.toISOString(),
|
||||
scopes: next.scopes.length ? next.scopes : current.scopes,
|
||||
};
|
||||
}
|
||||
const config = resolveMicrosoftCalendarOAuthConfig(env);
|
||||
if (!config) throw new Error("provider_not_configured");
|
||||
const next = await refreshMicrosoftCalendarToken(
|
||||
config,
|
||||
current.refreshToken
|
||||
);
|
||||
return {
|
||||
accessToken: next.accessToken,
|
||||
refreshToken: next.refreshToken ?? current.refreshToken,
|
||||
expiresAt: next.expiresAt.toISOString(),
|
||||
scopes: next.scopes.length ? next.scopes : current.scopes,
|
||||
};
|
||||
},
|
||||
|
||||
async sync(input: AdminCalendarProviderSyncInput) {
|
||||
return input.provider === "google_calendar"
|
||||
? syncGoogleCalendarBusySnapshot(input)
|
||||
: syncMicrosoftCalendarBusySnapshot(input);
|
||||
},
|
||||
};
|
||||
|
||||
export async function syncGoogleCalendarBusySnapshot(
|
||||
input: AdminCalendarProviderSyncInput
|
||||
) {
|
||||
const intervals = new Map(
|
||||
input.busyIntervals.map((interval) => [
|
||||
interval.externalEventId,
|
||||
interval,
|
||||
])
|
||||
);
|
||||
let pageToken: string | undefined;
|
||||
let nextCursor: string | undefined;
|
||||
do {
|
||||
const page = await listEvents(
|
||||
input.accessToken,
|
||||
input.externalCalendarId,
|
||||
{
|
||||
syncToken: input.cursorToken ?? undefined,
|
||||
pageToken,
|
||||
timeMin: input.cursorToken
|
||||
? undefined
|
||||
: new Date(input.now.getTime() - 30 * 86_400_000).toISOString(),
|
||||
timeMax: input.cursorToken
|
||||
? undefined
|
||||
: new Date(input.now.getTime() + 365 * 86_400_000).toISOString(),
|
||||
}
|
||||
);
|
||||
for (const event of page.events) {
|
||||
const startsAt = event.start?.dateTime;
|
||||
const endsAt = event.end?.dateTime;
|
||||
if (
|
||||
event.status === "cancelled" ||
|
||||
event.transparency === "transparent" ||
|
||||
!startsAt ||
|
||||
!endsAt
|
||||
) {
|
||||
intervals.delete(event.id);
|
||||
} else {
|
||||
intervals.set(event.id, {
|
||||
externalEventId: event.id,
|
||||
startsAt: new Date(startsAt).toISOString(),
|
||||
endsAt: new Date(endsAt).toISOString(),
|
||||
opaqueVersion: event.etag,
|
||||
});
|
||||
}
|
||||
}
|
||||
pageToken = page.nextPageToken;
|
||||
nextCursor = page.nextSyncToken ?? nextCursor;
|
||||
} while (pageToken);
|
||||
if (!nextCursor) throw new Error("provider_cursor_missing");
|
||||
return {
|
||||
busyIntervals: [...intervals.values()],
|
||||
cursorToken: nextCursor,
|
||||
deltaLink: null,
|
||||
};
|
||||
}
|
||||
|
||||
export async function syncMicrosoftCalendarBusySnapshot(
|
||||
input: AdminCalendarProviderSyncInput
|
||||
) {
|
||||
const intervals = new Map(
|
||||
input.busyIntervals.map((interval) => [
|
||||
interval.externalEventId,
|
||||
interval,
|
||||
])
|
||||
);
|
||||
let url =
|
||||
input.deltaLink ??
|
||||
buildInitialCalendarDeltaUrl(
|
||||
input.externalCalendarId,
|
||||
new Date(input.now.getTime() - 30 * 86_400_000),
|
||||
new Date(input.now.getTime() + 365 * 86_400_000)
|
||||
);
|
||||
let deltaLink: string | undefined;
|
||||
do {
|
||||
const page = await fetchCalendarDeltaPage(input.accessToken, url);
|
||||
for (const event of page.events) {
|
||||
const startsAt = event.start?.dateTime;
|
||||
const endsAt = event.end?.dateTime;
|
||||
if (
|
||||
event["@removed"] ||
|
||||
event.isCancelled ||
|
||||
event.showAs === "free" ||
|
||||
!startsAt ||
|
||||
!endsAt
|
||||
) {
|
||||
intervals.delete(event.id);
|
||||
} else {
|
||||
intervals.set(event.id, {
|
||||
externalEventId: event.id,
|
||||
startsAt: new Date(startsAt).toISOString(),
|
||||
endsAt: new Date(endsAt).toISOString(),
|
||||
opaqueVersion: event.changeKey,
|
||||
});
|
||||
}
|
||||
}
|
||||
url = page.nextLink ?? "";
|
||||
deltaLink = page.deltaLink ?? deltaLink;
|
||||
} while (url);
|
||||
if (!deltaLink) throw new Error("provider_cursor_missing");
|
||||
return {
|
||||
busyIntervals: [...intervals.values()],
|
||||
cursorToken: null,
|
||||
deltaLink,
|
||||
};
|
||||
}
|
||||
|
||||
function parseCredentials(
|
||||
raw: Readonly<Record<string, unknown>>
|
||||
): Credentials {
|
||||
if (
|
||||
typeof raw.accessToken !== "string" ||
|
||||
typeof raw.refreshToken !== "string" ||
|
||||
typeof raw.expiresAt !== "string" ||
|
||||
!Array.isArray(raw.scopes) ||
|
||||
raw.scopes.some((scope) => typeof scope !== "string")
|
||||
) {
|
||||
throw new Error("invalid_calendar_credentials");
|
||||
}
|
||||
return raw as Credentials;
|
||||
}
|
||||
|
||||
function parseBusyIntervals(
|
||||
value: unknown
|
||||
): readonly AdminCalendarBusyInterval[] {
|
||||
if (!Array.isArray(value)) return [];
|
||||
return value.filter(
|
||||
(entry): entry is AdminCalendarBusyInterval =>
|
||||
typeof entry === "object" &&
|
||||
entry !== null &&
|
||||
typeof (entry as AdminCalendarBusyInterval).externalEventId ===
|
||||
"string" &&
|
||||
typeof (entry as AdminCalendarBusyInterval).startsAt === "string" &&
|
||||
typeof (entry as AdminCalendarBusyInterval).endsAt === "string"
|
||||
);
|
||||
}
|
||||
+321
@@ -0,0 +1,321 @@
|
||||
// @vitest-environment node
|
||||
import { createCipheriv, createHash, randomBytes } from "node:crypto";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import type { AdminCallRecording, AdminCallRecordingPlayback, AdminTelephonyRecordingRepository } from "@hivegrid/db/admin-telephony-recordings.server";
|
||||
import { sealAdminConnectionCredentials } from "@hivegrid/db/crypto/admin-connection-envelope.server";
|
||||
import type { KeyWrapper } from "@hivegrid/foundation/crypto";
|
||||
|
||||
import { createAdminCallRecordingProcessor, decryptAdminCallRecording, type AdminCallRecordingStorage } from "./admin-call-recordings.server.js";
|
||||
|
||||
const wrapper: KeyWrapper = {
|
||||
wrap: async (value) => Buffer.concat([Buffer.from("wrapped:"), value]),
|
||||
unwrap: async (value) => value.subarray(Buffer.from("wrapped:").length),
|
||||
};
|
||||
|
||||
async function fixtureRecording(sourceUrl = "https://aircall.s3.eu-central-1.amazonaws.com/recording.mp3"): Promise<AdminCallRecording> {
|
||||
const source = await sealAdminConnectionCredentials(sourceUrl, {
|
||||
wrapper,
|
||||
});
|
||||
return {
|
||||
id: "recording_1",
|
||||
createdAt: new Date("2026-07-20T08:00:00.000Z"),
|
||||
updatedAt: new Date("2026-07-20T08:00:00.000Z"),
|
||||
adminUserId: "admin_1",
|
||||
callSessionId: "call_1",
|
||||
status: "processing",
|
||||
providerUrlWrappedDek: Uint8Array.from(source.wrappedDek),
|
||||
providerUrlCiphertext: source.ciphertext,
|
||||
providerUrlKeyVersion: source.keyVersion,
|
||||
storageBucket: null,
|
||||
storageKey: null,
|
||||
encryptedSizeBytes: null,
|
||||
checksumSha256: null,
|
||||
wrappedDek: null,
|
||||
iv: null,
|
||||
authTag: null,
|
||||
processingAt: new Date("2026-07-20T08:01:00.000Z"),
|
||||
attemptCount: 1,
|
||||
lastErrorCode: null,
|
||||
scannedAt: null,
|
||||
retainedUntil: new Date("2026-10-18T08:00:00.000Z"),
|
||||
expiredAt: null,
|
||||
deletedAt: null,
|
||||
rejectionCode: null,
|
||||
};
|
||||
}
|
||||
|
||||
function repository(): AdminTelephonyRecordingRepository {
|
||||
return {
|
||||
queue: vi.fn(),
|
||||
settleClean: vi.fn().mockResolvedValue({ id: "recording_1" }),
|
||||
settleFailure: vi.fn().mockResolvedValue({ id: "recording_1" }),
|
||||
} as never;
|
||||
}
|
||||
|
||||
function storage(): AdminCallRecordingStorage & {
|
||||
putObject: ReturnType<typeof vi.fn>;
|
||||
deleteObject: ReturnType<typeof vi.fn>;
|
||||
} {
|
||||
return {
|
||||
putObject: vi.fn().mockResolvedValue({
|
||||
bucket: "eu-private",
|
||||
key: "recording.enc",
|
||||
}),
|
||||
deleteObject: vi.fn().mockResolvedValue(undefined),
|
||||
};
|
||||
}
|
||||
|
||||
describe("admin call recording processor", () => {
|
||||
it("scans plaintext, stores only encrypted bytes and settles clean", async () => {
|
||||
const repo = repository();
|
||||
const objectStorage = storage();
|
||||
const plaintext = Buffer.from("MP3 private conversation");
|
||||
const scanner = {
|
||||
scanBuffer: vi.fn().mockResolvedValue({
|
||||
verdict: "clean",
|
||||
engine: "clamav",
|
||||
}),
|
||||
};
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner,
|
||||
storage: objectStorage,
|
||||
keyWrapper: wrapper,
|
||||
download: vi.fn().mockResolvedValue({
|
||||
bytes: plaintext,
|
||||
contentType: "audio/mpeg",
|
||||
}),
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording());
|
||||
|
||||
expect(scanner.scanBuffer).toHaveBeenCalledWith(plaintext);
|
||||
const storedBody = objectStorage.putObject.mock.calls[0]?.[0].body as Uint8Array;
|
||||
expect(Buffer.from(storedBody).equals(plaintext)).toBe(false);
|
||||
expect(repo.settleClean).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
id: "recording_1",
|
||||
artifact: expect.objectContaining({
|
||||
storageBucket: "eu-private",
|
||||
storageKey: "recording.enc",
|
||||
encryptedSizeBytes: plaintext.byteLength,
|
||||
checksumSha256: "a7627b6266d24e77f57b127ed984b2a236191aaf3112528eec9fcf193fab2f21",
|
||||
}),
|
||||
})
|
||||
);
|
||||
expect(repo.settleFailure).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fails closed without storing when ClamAV finds malware", async () => {
|
||||
const repo = repository();
|
||||
const objectStorage = storage();
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: {
|
||||
scanBuffer: vi.fn().mockResolvedValue({
|
||||
verdict: "infected",
|
||||
signature: "Eicar-Test-Signature",
|
||||
}),
|
||||
},
|
||||
storage: objectStorage,
|
||||
keyWrapper: wrapper,
|
||||
download: vi.fn().mockResolvedValue({
|
||||
bytes: Buffer.from("infected"),
|
||||
}),
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording());
|
||||
|
||||
expect(objectStorage.putObject).not.toHaveBeenCalled();
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_infected",
|
||||
retryable: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects unsafe source URLs before download", async () => {
|
||||
const repo = repository();
|
||||
const download = vi.fn();
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: { scanBuffer: vi.fn() },
|
||||
storage: storage(),
|
||||
keyWrapper: wrapper,
|
||||
download,
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording("https://127.0.0.1/internal.mp3"));
|
||||
|
||||
expect(download).not.toHaveBeenCalled();
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_source_unsafe",
|
||||
retryable: false,
|
||||
});
|
||||
});
|
||||
|
||||
it.each(["http://recordings.example.test/call.mp3", "https://recordings.example.test:8443/call.mp3"])(
|
||||
"keeps the HTTPS and port-443-only source policy for %s",
|
||||
async (sourceUrl) => {
|
||||
const repo = repository();
|
||||
const download = vi.fn();
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: { scanBuffer: vi.fn() },
|
||||
storage: storage(),
|
||||
keyWrapper: wrapper,
|
||||
download,
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording(sourceUrl));
|
||||
|
||||
expect(download).not.toHaveBeenCalled();
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_source_unsafe",
|
||||
retryable: false,
|
||||
});
|
||||
}
|
||||
);
|
||||
|
||||
it("rejects a public recording hostname that resolves to a private address before fetch", async () => {
|
||||
const repo = repository();
|
||||
const fetchImpl = vi.fn();
|
||||
const addressResolver = vi.fn().mockResolvedValue(["10.42.0.4"]);
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: { scanBuffer: vi.fn() },
|
||||
storage: storage(),
|
||||
keyWrapper: wrapper,
|
||||
outboundHttp: { fetchImpl, addressResolver },
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording("https://recordings.example.test/internal.mp3"));
|
||||
|
||||
expect(addressResolver).toHaveBeenCalledWith("recordings.example.test");
|
||||
expect(fetchImpl).not.toHaveBeenCalled();
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_source_unsafe",
|
||||
retryable: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects a redirect whose hostname resolves to a private address", async () => {
|
||||
const repo = repository();
|
||||
const fetchImpl = vi.fn().mockResolvedValueOnce(
|
||||
new Response(null, {
|
||||
status: 302,
|
||||
headers: { Location: "https://metadata.example.test/recording.mp3" },
|
||||
})
|
||||
);
|
||||
const addressResolver = vi.fn(async (hostname: string) => (hostname === "metadata.example.test" ? ["169.254.169.254"] : ["203.0.113.10"]));
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: { scanBuffer: vi.fn() },
|
||||
storage: storage(),
|
||||
keyWrapper: wrapper,
|
||||
outboundHttp: { fetchImpl, addressResolver },
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording("https://recordings.example.test/redirect.mp3"));
|
||||
|
||||
expect(fetchImpl).toHaveBeenCalledTimes(1);
|
||||
expect(addressResolver).toHaveBeenNthCalledWith(1, "recordings.example.test");
|
||||
expect(addressResolver).toHaveBeenNthCalledWith(2, "metadata.example.test");
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_source_unsafe",
|
||||
retryable: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps the recording byte limit on the DNS-vetted download path", async () => {
|
||||
const repo = repository();
|
||||
const maxBytes = 8;
|
||||
const responseBody = Buffer.alloc(maxBytes + 1);
|
||||
const fetchImpl = vi.fn().mockResolvedValue(
|
||||
new Response(responseBody, {
|
||||
status: 200,
|
||||
headers: {
|
||||
"Content-Length": String(responseBody.byteLength),
|
||||
"Content-Type": "audio/mpeg",
|
||||
},
|
||||
})
|
||||
);
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: { scanBuffer: vi.fn() },
|
||||
storage: storage(),
|
||||
keyWrapper: wrapper,
|
||||
maxBytes,
|
||||
outboundHttp: {
|
||||
fetchImpl,
|
||||
addressResolver: vi.fn().mockResolvedValue(["203.0.113.10"]),
|
||||
},
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording());
|
||||
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_too_large",
|
||||
retryable: false,
|
||||
});
|
||||
});
|
||||
|
||||
it("marks unavailable AV as retryable and never stores unscanned bytes", async () => {
|
||||
const repo = repository();
|
||||
const objectStorage = storage();
|
||||
const processor = createAdminCallRecordingProcessor({
|
||||
repository: repo,
|
||||
scanner: {
|
||||
scanBuffer: vi.fn().mockRejectedValue(new Error("clamd offline")),
|
||||
},
|
||||
storage: objectStorage,
|
||||
keyWrapper: wrapper,
|
||||
download: vi.fn().mockResolvedValue({
|
||||
bytes: Buffer.from("conversation"),
|
||||
}),
|
||||
});
|
||||
|
||||
await processor.process(await fixtureRecording());
|
||||
|
||||
expect(objectStorage.putObject).not.toHaveBeenCalled();
|
||||
expect(repo.settleFailure).toHaveBeenCalledWith({
|
||||
id: "recording_1",
|
||||
errorCode: "recording_scan_unavailable",
|
||||
retryable: true,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("admin call recording playback", () => {
|
||||
it("decrypts a stored artifact and verifies its checksum", async () => {
|
||||
const plaintext = Buffer.from("recording bytes");
|
||||
const dek = randomBytes(32);
|
||||
const iv = randomBytes(12);
|
||||
const cipher = createCipheriv("aes-256-gcm", dek, iv);
|
||||
const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
|
||||
const recording: AdminCallRecordingPlayback = {
|
||||
id: "recording_1",
|
||||
adminUserId: "admin_1",
|
||||
callSessionId: "call_1",
|
||||
storageBucket: "eu-private",
|
||||
storageKey: "admin-call-recordings/recording_1.enc",
|
||||
encryptedSizeBytes: ciphertext.byteLength,
|
||||
checksumSha256: createHash("sha256").update(plaintext).digest("hex"),
|
||||
wrappedDek: await wrapper.wrap(dek),
|
||||
iv,
|
||||
authTag: cipher.getAuthTag(),
|
||||
retainedUntil: new Date("2026-10-18T08:00:00.000Z"),
|
||||
};
|
||||
|
||||
await expect(decryptAdminCallRecording(recording, ciphertext, wrapper)).resolves.toEqual(Uint8Array.from(plaintext));
|
||||
await expect(decryptAdminCallRecording({ ...recording, checksumSha256: "0".repeat(64) }, ciphertext, wrapper)).rejects.toMatchObject({
|
||||
code: "recording_checksum_mismatch",
|
||||
});
|
||||
});
|
||||
});
|
||||
+313
@@ -0,0 +1,313 @@
|
||||
import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
|
||||
|
||||
import type { AdminCallRecording, AdminCallRecordingPlayback, AdminTelephonyRecordingRepository } from "@hivegrid/db/admin-telephony-recordings.server";
|
||||
import { openAdminConnectionCredentials } from "@hivegrid/db/crypto/admin-connection-envelope.server";
|
||||
import { generateDek, type KeyWrapper } from "@hivegrid/foundation/crypto";
|
||||
import { fetchOutboundHttpWithRedirects, OutboundHttpUrlValidationError, type OutboundHttpFetchOptions } from "@hivegrid/foundation/outbound-http";
|
||||
|
||||
export const ADMIN_CALL_RECORDING_MAX_BYTES = 100 * 1024 * 1024;
|
||||
const RECORDING_FETCH_TIMEOUT_MS = 30_000;
|
||||
const MAX_REDIRECTS = 5;
|
||||
|
||||
export type AdminCallRecordingScanner = {
|
||||
scanBuffer(bytes: Buffer): Promise<
|
||||
| { readonly verdict: "clean"; readonly engine?: string }
|
||||
| {
|
||||
readonly verdict: "infected";
|
||||
readonly signature: string;
|
||||
readonly engine?: string;
|
||||
}
|
||||
>;
|
||||
};
|
||||
|
||||
export type AdminCallRecordingStorage = {
|
||||
putObject(input: {
|
||||
readonly key: string;
|
||||
readonly body: Uint8Array;
|
||||
readonly contentType: string;
|
||||
readonly metadata: Record<string, string>;
|
||||
}): Promise<{ readonly bucket: string; readonly key: string }>;
|
||||
deleteObject(input: { readonly bucket?: string; readonly key: string }): Promise<unknown>;
|
||||
};
|
||||
|
||||
export type AdminCallRecordingDownload = (input: { readonly url: string; readonly maxBytes: number }) => Promise<{
|
||||
readonly bytes: Uint8Array;
|
||||
readonly contentType?: string;
|
||||
}>;
|
||||
|
||||
type AdminCallRecordingOutboundHttpOptions = Pick<OutboundHttpFetchOptions, "fetchImpl" | "addressResolver">;
|
||||
|
||||
export function createAdminCallRecordingProcessor(input: {
|
||||
readonly repository: AdminTelephonyRecordingRepository;
|
||||
readonly scanner: AdminCallRecordingScanner;
|
||||
readonly storage: AdminCallRecordingStorage;
|
||||
readonly keyWrapper: KeyWrapper;
|
||||
readonly download?: AdminCallRecordingDownload;
|
||||
readonly outboundHttp?: AdminCallRecordingOutboundHttpOptions;
|
||||
readonly maxBytes?: number;
|
||||
}) {
|
||||
const maxBytes = input.maxBytes ?? ADMIN_CALL_RECORDING_MAX_BYTES;
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
|
||||
throw new Error("admin-call-recording: maxBytes must be positive");
|
||||
}
|
||||
return {
|
||||
async process(recording: AdminCallRecording): Promise<void> {
|
||||
let stored: { readonly bucket: string; readonly key: string } | null = null;
|
||||
try {
|
||||
const sourceUrl = await openRecordingSourceUrl(recording, input.keyWrapper);
|
||||
const downloaded = input.download
|
||||
? await input.download({ url: sourceUrl, maxBytes })
|
||||
: await downloadRecording({ url: sourceUrl, maxBytes }, input.outboundHttp);
|
||||
if (downloaded.bytes.byteLength === 0 || downloaded.bytes.byteLength > maxBytes) {
|
||||
throw new AdminCallRecordingProcessingError("recording_size_invalid", false);
|
||||
}
|
||||
let scan;
|
||||
try {
|
||||
scan = await input.scanner.scanBuffer(Buffer.from(downloaded.bytes));
|
||||
} catch (cause) {
|
||||
throw new AdminCallRecordingProcessingError("recording_scan_unavailable", true, { cause });
|
||||
}
|
||||
if (scan.verdict !== "clean") {
|
||||
throw new AdminCallRecordingProcessingError("recording_infected", false);
|
||||
}
|
||||
const encrypted = await encryptRecording(downloaded.bytes, input.keyWrapper);
|
||||
const checksumSha256 = createHash("sha256").update(downloaded.bytes).digest("hex");
|
||||
try {
|
||||
stored = await input.storage.putObject({
|
||||
key: ["admin-call-recordings", safeKeyPart(recording.adminUserId), safeKeyPart(recording.id), `${checksumSha256}.enc`].join("/"),
|
||||
body: encrypted.ciphertext,
|
||||
contentType: "application/octet-stream",
|
||||
metadata: {
|
||||
checksumSha256,
|
||||
source: "admin-telephony",
|
||||
originalContentType: downloaded.contentType ?? "audio/mpeg",
|
||||
},
|
||||
});
|
||||
} catch (cause) {
|
||||
throw new AdminCallRecordingProcessingError("recording_storage_failed", true, { cause });
|
||||
}
|
||||
await input.repository.settleClean({
|
||||
id: recording.id,
|
||||
artifact: {
|
||||
storageBucket: stored.bucket,
|
||||
storageKey: stored.key,
|
||||
encryptedSizeBytes: encrypted.ciphertext.byteLength,
|
||||
checksumSha256,
|
||||
wrappedDek: encrypted.wrappedDek,
|
||||
iv: encrypted.iv,
|
||||
authTag: encrypted.authTag,
|
||||
scannedAt: new Date(),
|
||||
},
|
||||
});
|
||||
} catch (error) {
|
||||
const cleanupTarget = stored as {
|
||||
readonly bucket: string;
|
||||
readonly key: string;
|
||||
} | null;
|
||||
if (cleanupTarget) {
|
||||
await input.storage
|
||||
.deleteObject({
|
||||
bucket: cleanupTarget.bucket,
|
||||
key: cleanupTarget.key,
|
||||
})
|
||||
.catch(() => undefined);
|
||||
}
|
||||
const normalized =
|
||||
error instanceof AdminCallRecordingProcessingError
|
||||
? error
|
||||
: new AdminCallRecordingProcessingError("recording_processing_failed", true, { cause: error });
|
||||
await input.repository.settleFailure({
|
||||
id: recording.id,
|
||||
errorCode: normalized.code,
|
||||
retryable: normalized.retryable,
|
||||
});
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export async function decryptAdminCallRecording(recording: AdminCallRecordingPlayback, encryptedBytes: Uint8Array, wrapper: KeyWrapper): Promise<Uint8Array> {
|
||||
if (encryptedBytes.byteLength !== recording.encryptedSizeBytes || recording.iv.byteLength !== 12 || recording.authTag.byteLength !== 16) {
|
||||
throw new AdminCallRecordingProcessingError("recording_artifact_invalid", false);
|
||||
}
|
||||
try {
|
||||
const dek = await wrapper.unwrap(Buffer.from(recording.wrappedDek));
|
||||
const decipher = createDecipheriv("aes-256-gcm", dek, Buffer.from(recording.iv));
|
||||
decipher.setAuthTag(Buffer.from(recording.authTag));
|
||||
const plaintext = Buffer.concat([decipher.update(encryptedBytes), decipher.final()]);
|
||||
const checksum = createHash("sha256").update(plaintext).digest("hex");
|
||||
if (checksum !== recording.checksumSha256) {
|
||||
throw new AdminCallRecordingProcessingError("recording_checksum_mismatch", false);
|
||||
}
|
||||
return Uint8Array.from(plaintext);
|
||||
} catch (cause) {
|
||||
if (cause instanceof AdminCallRecordingProcessingError) throw cause;
|
||||
throw new AdminCallRecordingProcessingError("recording_decryption_failed", false, { cause });
|
||||
}
|
||||
}
|
||||
|
||||
async function openRecordingSourceUrl(recording: AdminCallRecording, wrapper: KeyWrapper): Promise<string> {
|
||||
if (!recording.providerUrlCiphertext || !recording.providerUrlWrappedDek || !recording.providerUrlKeyVersion) {
|
||||
throw new AdminCallRecordingProcessingError("recording_source_missing", false);
|
||||
}
|
||||
try {
|
||||
const sourceUrl = await openAdminConnectionCredentials(
|
||||
{
|
||||
ciphertext: recording.providerUrlCiphertext,
|
||||
wrappedDek: recording.providerUrlWrappedDek,
|
||||
keyVersion: recording.providerUrlKeyVersion,
|
||||
},
|
||||
{ wrapper }
|
||||
);
|
||||
return validateRecordingSourceUrl(sourceUrl);
|
||||
} catch (cause) {
|
||||
if (cause instanceof AdminCallRecordingProcessingError) throw cause;
|
||||
throw new AdminCallRecordingProcessingError("recording_source_invalid", false, { cause });
|
||||
}
|
||||
}
|
||||
|
||||
async function downloadRecording(
|
||||
input: {
|
||||
readonly url: string;
|
||||
readonly maxBytes: number;
|
||||
},
|
||||
outboundHttp: AdminCallRecordingOutboundHttpOptions = {}
|
||||
): Promise<{ readonly bytes: Uint8Array; readonly contentType?: string }> {
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetchOutboundHttpWithRedirects(
|
||||
input.url,
|
||||
{
|
||||
method: "GET",
|
||||
headers: { Accept: "audio/mpeg,application/octet-stream" },
|
||||
},
|
||||
{
|
||||
...outboundHttp,
|
||||
timeoutMs: RECORDING_FETCH_TIMEOUT_MS,
|
||||
redirectLimit: MAX_REDIRECTS,
|
||||
allowCrossOriginRedirects: true,
|
||||
urlValidator: validateRecordingSourceUrl,
|
||||
}
|
||||
);
|
||||
} catch (cause) {
|
||||
if (cause instanceof AdminCallRecordingProcessingError) {
|
||||
throw cause;
|
||||
}
|
||||
if (cause instanceof OutboundHttpUrlValidationError) {
|
||||
if (cause.message.includes("redirect limit")) {
|
||||
throw new AdminCallRecordingProcessingError("recording_redirect_limit", false, { cause });
|
||||
}
|
||||
if (cause.message.includes("could not be resolved")) {
|
||||
throw new AdminCallRecordingProcessingError("recording_download_failed", true, { cause });
|
||||
}
|
||||
throw new AdminCallRecordingProcessingError("recording_source_unsafe", false, { cause });
|
||||
}
|
||||
throw new AdminCallRecordingProcessingError("recording_download_failed", true, { cause });
|
||||
}
|
||||
if (!response.ok || !response.body) {
|
||||
throw new AdminCallRecordingProcessingError("recording_download_failed", response.status >= 500 || response.status === 429);
|
||||
}
|
||||
const declaredLength = Number(response.headers.get("content-length") ?? "0");
|
||||
if (Number.isFinite(declaredLength) && declaredLength > input.maxBytes) {
|
||||
await response.body.cancel().catch(() => undefined);
|
||||
throw new AdminCallRecordingProcessingError("recording_too_large", false);
|
||||
}
|
||||
const reader = response.body.getReader();
|
||||
const chunks: Uint8Array[] = [];
|
||||
let size = 0;
|
||||
while (true) {
|
||||
const { done, value } = await reader.read();
|
||||
if (done) break;
|
||||
size += value.byteLength;
|
||||
if (size > input.maxBytes) {
|
||||
await reader.cancel();
|
||||
throw new AdminCallRecordingProcessingError("recording_too_large", false);
|
||||
}
|
||||
chunks.push(value);
|
||||
}
|
||||
const bytes = new Uint8Array(size);
|
||||
let offset = 0;
|
||||
for (const chunk of chunks) {
|
||||
bytes.set(chunk, offset);
|
||||
offset += chunk.byteLength;
|
||||
}
|
||||
return {
|
||||
bytes,
|
||||
...(response.headers.get("content-type") ? { contentType: response.headers.get("content-type")! } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
async function encryptRecording(
|
||||
plaintext: Uint8Array,
|
||||
wrapper: KeyWrapper
|
||||
): Promise<{
|
||||
readonly ciphertext: Uint8Array;
|
||||
readonly wrappedDek: Uint8Array;
|
||||
readonly iv: Uint8Array;
|
||||
readonly authTag: Uint8Array;
|
||||
}> {
|
||||
const dek = generateDek();
|
||||
const iv = randomBytes(12);
|
||||
const cipher = createCipheriv("aes-256-gcm", dek, iv);
|
||||
const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
|
||||
return {
|
||||
ciphertext,
|
||||
wrappedDek: await wrapper.wrap(dek),
|
||||
iv,
|
||||
authTag: cipher.getAuthTag(),
|
||||
};
|
||||
}
|
||||
|
||||
function validateRecordingSourceUrl(value: string): string {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(value);
|
||||
} catch (cause) {
|
||||
throw new AdminCallRecordingProcessingError("recording_source_invalid", false, { cause });
|
||||
}
|
||||
const hostname = url.hostname.toLowerCase();
|
||||
if (
|
||||
url.protocol !== "https:" ||
|
||||
url.username ||
|
||||
url.password ||
|
||||
(url.port && url.port !== "443") ||
|
||||
hostname === "localhost" ||
|
||||
hostname.endsWith(".localhost") ||
|
||||
isPrivateIpLiteral(hostname)
|
||||
) {
|
||||
throw new AdminCallRecordingProcessingError("recording_source_unsafe", false);
|
||||
}
|
||||
return url.toString();
|
||||
}
|
||||
|
||||
function isPrivateIpLiteral(hostname: string): boolean {
|
||||
if (hostname === "::1" || hostname.startsWith("fc") || hostname.startsWith("fd")) {
|
||||
return true;
|
||||
}
|
||||
const octets = hostname.split(".").map(Number);
|
||||
if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
|
||||
return false;
|
||||
}
|
||||
return (
|
||||
octets[0] === 10 ||
|
||||
octets[0] === 127 ||
|
||||
(octets[0] === 169 && octets[1] === 254) ||
|
||||
(octets[0] === 172 && (octets[1] ?? 0) >= 16 && (octets[1] ?? 0) <= 31) ||
|
||||
(octets[0] === 192 && octets[1] === 168)
|
||||
);
|
||||
}
|
||||
|
||||
function safeKeyPart(value: string): string {
|
||||
return encodeURIComponent(value.trim()).replace(/%/gu, "_");
|
||||
}
|
||||
|
||||
export class AdminCallRecordingProcessingError extends Error {
|
||||
constructor(
|
||||
readonly code: string,
|
||||
readonly retryable: boolean,
|
||||
options: { readonly cause?: unknown } = {}
|
||||
) {
|
||||
super(code, options);
|
||||
this.name = "AdminCallRecordingProcessingError";
|
||||
}
|
||||
}
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
ADMIN_MAIL_CONNECTION_REGISTRY,
|
||||
AdminConnectionContractError,
|
||||
normalizeAdminOAuthCredentialBundle,
|
||||
} from "./admin-connections.js";
|
||||
|
||||
describe("admin mail connection registry", () => {
|
||||
it("keeps Google and Microsoft on the email capability with reviewed scopes", () => {
|
||||
expect(Object.keys(ADMIN_MAIL_CONNECTION_REGISTRY)).toEqual([
|
||||
"google_mail",
|
||||
"microsoft_mail",
|
||||
]);
|
||||
expect(
|
||||
ADMIN_MAIL_CONNECTION_REGISTRY.google_mail.requiredScopes
|
||||
).toContain("https://www.googleapis.com/auth/gmail.modify");
|
||||
expect(
|
||||
ADMIN_MAIL_CONNECTION_REGISTRY.microsoft_mail.requiredScopes
|
||||
).toContain("Mail.ReadWrite");
|
||||
});
|
||||
|
||||
it("normalizes a credential bundle without retaining duplicate scopes", () => {
|
||||
const required =
|
||||
ADMIN_MAIL_CONNECTION_REGISTRY.microsoft_mail.requiredScopes;
|
||||
expect(
|
||||
normalizeAdminOAuthCredentialBundle("microsoft_mail", {
|
||||
accessToken: " access ",
|
||||
refreshToken: " refresh ",
|
||||
expiresAt: "2027-01-01T00:00:00+00:00",
|
||||
scopes: [...required, required[0]],
|
||||
})
|
||||
).toEqual({
|
||||
accessToken: "access",
|
||||
refreshToken: "refresh",
|
||||
expiresAt: "2027-01-01T00:00:00.000Z",
|
||||
scopes: [...required].sort(),
|
||||
});
|
||||
});
|
||||
|
||||
it("fails closed when the provider grant omits a required scope", () => {
|
||||
expect(() =>
|
||||
normalizeAdminOAuthCredentialBundle("google_mail", {
|
||||
accessToken: "access",
|
||||
refreshToken: "refresh",
|
||||
expiresAt: "2027-01-01T00:00:00.000Z",
|
||||
scopes: ["openid", "email"],
|
||||
})
|
||||
).toThrowError(
|
||||
expect.objectContaining<Partial<AdminConnectionContractError>>({
|
||||
code: "missing_required_scopes",
|
||||
})
|
||||
);
|
||||
});
|
||||
});
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
import { GMAIL_SCOPES } from "./google/gmailApi.js";
|
||||
import { MICROSOFT_MAIL_SCOPES } from "./microsoft/graphMailApi.js";
|
||||
|
||||
export type AdminMailConnectionProvider = "google_mail" | "microsoft_mail";
|
||||
|
||||
export type AdminConnectionDefinition = {
|
||||
readonly provider: AdminMailConnectionProvider;
|
||||
readonly capability: "email";
|
||||
readonly oauth: true;
|
||||
readonly requiredScopes: readonly string[];
|
||||
readonly healthMessageKey: string;
|
||||
};
|
||||
|
||||
export const ADMIN_MAIL_CONNECTION_REGISTRY = Object.freeze({
|
||||
google_mail: Object.freeze({
|
||||
provider: "google_mail",
|
||||
capability: "email",
|
||||
oauth: true,
|
||||
requiredScopes: GMAIL_SCOPES,
|
||||
healthMessageKey: "admin.sales.email.connections.health.google",
|
||||
}),
|
||||
microsoft_mail: Object.freeze({
|
||||
provider: "microsoft_mail",
|
||||
capability: "email",
|
||||
oauth: true,
|
||||
requiredScopes: MICROSOFT_MAIL_SCOPES,
|
||||
healthMessageKey: "admin.sales.email.connections.health.microsoft",
|
||||
}),
|
||||
} satisfies Record<AdminMailConnectionProvider, AdminConnectionDefinition>);
|
||||
|
||||
export type AdminOAuthCredentialBundle = {
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken: string;
|
||||
readonly expiresAt: string;
|
||||
readonly scopes: readonly string[];
|
||||
};
|
||||
|
||||
export function normalizeAdminOAuthCredentialBundle(
|
||||
provider: AdminMailConnectionProvider,
|
||||
input: AdminOAuthCredentialBundle
|
||||
): AdminOAuthCredentialBundle {
|
||||
const accessToken = normalizeSecret(input.accessToken, "accessToken");
|
||||
const refreshToken = normalizeSecret(input.refreshToken, "refreshToken");
|
||||
const expiresAt = normalizeExpiry(input.expiresAt);
|
||||
const scopes = normalizeScopes(input.scopes);
|
||||
assertAdminConnectionScopes(provider, scopes);
|
||||
return Object.freeze({ accessToken, refreshToken, expiresAt, scopes });
|
||||
}
|
||||
|
||||
export function assertAdminConnectionScopes(
|
||||
provider: AdminMailConnectionProvider,
|
||||
grantedScopes: readonly string[]
|
||||
): void {
|
||||
const granted = new Set(normalizeScopes(grantedScopes));
|
||||
const missing = ADMIN_MAIL_CONNECTION_REGISTRY[provider].requiredScopes.filter(
|
||||
(scope) => !granted.has(scope)
|
||||
);
|
||||
if (missing.length > 0) {
|
||||
throw new AdminConnectionContractError("missing_required_scopes", {
|
||||
provider,
|
||||
missingScopes: missing,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
export class AdminConnectionContractError extends Error {
|
||||
readonly code: "invalid_credential_bundle" | "missing_required_scopes";
|
||||
readonly details: Readonly<Record<string, unknown>>;
|
||||
|
||||
constructor(
|
||||
code: "invalid_credential_bundle" | "missing_required_scopes",
|
||||
details: Readonly<Record<string, unknown>> = {}
|
||||
) {
|
||||
super(code);
|
||||
this.name = "AdminConnectionContractError";
|
||||
this.code = code;
|
||||
this.details = details;
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeSecret(value: string, field: string): string {
|
||||
const normalized = value.trim();
|
||||
if (normalized.length === 0 || normalized.length > 16_384) {
|
||||
throw new AdminConnectionContractError("invalid_credential_bundle", {
|
||||
field,
|
||||
});
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeExpiry(value: string): string {
|
||||
const timestamp = Date.parse(value);
|
||||
if (!Number.isFinite(timestamp)) {
|
||||
throw new AdminConnectionContractError("invalid_credential_bundle", {
|
||||
field: "expiresAt",
|
||||
});
|
||||
}
|
||||
return new Date(timestamp).toISOString();
|
||||
}
|
||||
|
||||
function normalizeScopes(scopes: readonly string[]): readonly string[] {
|
||||
const normalized = [
|
||||
...new Set(
|
||||
scopes.map((scope) => scope.trim()).filter((scope) => scope.length > 0)
|
||||
),
|
||||
].sort();
|
||||
if (normalized.length === 0 || normalized.some((scope) => scope.length > 512)) {
|
||||
throw new AdminConnectionContractError("invalid_credential_bundle", {
|
||||
field: "scopes",
|
||||
});
|
||||
}
|
||||
return Object.freeze(normalized);
|
||||
}
|
||||
+217
@@ -0,0 +1,217 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { MappedEmailMessage } from "./email-message-mapping.js";
|
||||
import {
|
||||
createAdminEmailAttachmentProcessor,
|
||||
} from "./admin-email-attachments.server.js";
|
||||
|
||||
function message(
|
||||
attachments: MappedEmailMessage["attachments"]
|
||||
): MappedEmailMessage {
|
||||
return {
|
||||
providerMessageId: "provider-message-1",
|
||||
providerThreadId: "thread-1",
|
||||
internetMessageId: "rfc-1",
|
||||
direction: "inbound",
|
||||
from: { address: "buyer@example.com" },
|
||||
to: [{ address: "sales@hivegrid.de" }],
|
||||
cc: [],
|
||||
bcc: [],
|
||||
subject: "Angebot",
|
||||
snippet: null,
|
||||
bodyHtml: null,
|
||||
bodyText: null,
|
||||
sentAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
receivedAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
isRead: false,
|
||||
hasAttachments: attachments.length > 0,
|
||||
isNewsletter: false,
|
||||
providerLabels: ["INBOX"],
|
||||
attachments,
|
||||
};
|
||||
}
|
||||
|
||||
function request(
|
||||
attachments: MappedEmailMessage["attachments"]
|
||||
) {
|
||||
return {
|
||||
adminUserId: "admin-1",
|
||||
mailboxId: "mailbox-1",
|
||||
provider: "google_mail" as const,
|
||||
accessToken: "provider-access",
|
||||
message: message(attachments),
|
||||
now: new Date("2026-07-24T10:00:01.000Z"),
|
||||
};
|
||||
}
|
||||
|
||||
describe("admin email attachment pipeline", () => {
|
||||
it("stores only a clean, size-consistent payload under a PII-free key", async () => {
|
||||
const bytes = Buffer.from("clean-pdf");
|
||||
const scanner = {
|
||||
scanBuffer: vi.fn(async () => ({
|
||||
verdict: "clean" as const,
|
||||
engine: "clamav",
|
||||
})),
|
||||
};
|
||||
const storage = {
|
||||
putObject: vi.fn(async ({ key }: { key: string }) => ({
|
||||
bucket: "hivegrid-files",
|
||||
key,
|
||||
})),
|
||||
deleteObject: vi.fn(),
|
||||
};
|
||||
const processor = createAdminEmailAttachmentProcessor({
|
||||
scanner,
|
||||
storage,
|
||||
download: vi.fn(async () => bytes),
|
||||
});
|
||||
|
||||
await expect(
|
||||
processor.prepare(
|
||||
request([
|
||||
{
|
||||
attachmentId: "attachment-1",
|
||||
filename: "../Vertrag.pdf",
|
||||
mimeType: "application/pdf",
|
||||
sizeBytes: bytes.byteLength,
|
||||
},
|
||||
])
|
||||
)
|
||||
).resolves.toEqual([
|
||||
expect.objectContaining({
|
||||
providerAttachmentId: "attachment-1",
|
||||
filename: ".._Vertrag.pdf",
|
||||
sizeBytes: bytes.byteLength,
|
||||
storageBucket: "hivegrid-files",
|
||||
storageKey: expect.stringMatching(
|
||||
/^admin-email\/admin-1\/mailbox-1\/provider-message-1\/attachment-1-[a-f0-9]{64}$/u
|
||||
),
|
||||
checksumSha256: expect.stringMatching(/^[a-f0-9]{64}$/u),
|
||||
}),
|
||||
]);
|
||||
expect(scanner.scanBuffer).toHaveBeenCalledWith(bytes);
|
||||
expect(storage.putObject).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
body: bytes,
|
||||
contentType: "application/pdf",
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects declared oversize before download or scan", async () => {
|
||||
const download = vi.fn();
|
||||
const scanner = { scanBuffer: vi.fn() };
|
||||
const storage = {
|
||||
putObject: vi.fn(),
|
||||
deleteObject: vi.fn(),
|
||||
};
|
||||
const processor = createAdminEmailAttachmentProcessor({
|
||||
scanner,
|
||||
storage,
|
||||
download,
|
||||
maxBytes: 8,
|
||||
});
|
||||
|
||||
await expect(
|
||||
processor.prepare(
|
||||
request([
|
||||
{
|
||||
attachmentId: "too-large",
|
||||
filename: "large.bin",
|
||||
mimeType: null,
|
||||
sizeBytes: 9,
|
||||
},
|
||||
])
|
||||
)
|
||||
).rejects.toMatchObject({ code: "attachment_too_large" });
|
||||
expect(download).not.toHaveBeenCalled();
|
||||
expect(scanner.scanBuffer).not.toHaveBeenCalled();
|
||||
expect(storage.putObject).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
name: "infected verdict",
|
||||
scanner: async () => ({
|
||||
verdict: "infected" as const,
|
||||
signature: "EICAR",
|
||||
}),
|
||||
code: "attachment_infected",
|
||||
},
|
||||
{
|
||||
name: "scanner outage",
|
||||
scanner: async () => {
|
||||
throw new Error("clamd unavailable");
|
||||
},
|
||||
code: "attachment_scan_unavailable",
|
||||
},
|
||||
])("fails closed for $name", async ({ scanner, code }) => {
|
||||
const storage = {
|
||||
putObject: vi.fn(),
|
||||
deleteObject: vi.fn(),
|
||||
};
|
||||
const processor = createAdminEmailAttachmentProcessor({
|
||||
scanner: { scanBuffer: vi.fn(scanner) },
|
||||
storage,
|
||||
download: vi.fn(async () => Buffer.from("x")),
|
||||
});
|
||||
|
||||
await expect(
|
||||
processor.prepare(
|
||||
request([
|
||||
{
|
||||
attachmentId: "unsafe",
|
||||
filename: "unsafe.bin",
|
||||
mimeType: null,
|
||||
sizeBytes: 1,
|
||||
},
|
||||
])
|
||||
)
|
||||
).rejects.toMatchObject({ code });
|
||||
expect(storage.putObject).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("rolls back an earlier object if a later attachment fails", async () => {
|
||||
const storage = {
|
||||
putObject: vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce({
|
||||
bucket: "hivegrid-files",
|
||||
key: "admin-email/first",
|
||||
})
|
||||
.mockRejectedValueOnce(new Error("storage unavailable")),
|
||||
deleteObject: vi.fn(async () => undefined),
|
||||
};
|
||||
const processor = createAdminEmailAttachmentProcessor({
|
||||
scanner: {
|
||||
scanBuffer: vi.fn(async () => ({ verdict: "clean" as const })),
|
||||
},
|
||||
storage,
|
||||
download: vi.fn(async ({ attachment }) =>
|
||||
Buffer.from(attachment.attachmentId)
|
||||
),
|
||||
});
|
||||
|
||||
await expect(
|
||||
processor.prepare(
|
||||
request([
|
||||
{
|
||||
attachmentId: "a",
|
||||
filename: "a.txt",
|
||||
mimeType: "text/plain",
|
||||
sizeBytes: 1,
|
||||
},
|
||||
{
|
||||
attachmentId: "b",
|
||||
filename: "b.txt",
|
||||
mimeType: "text/plain",
|
||||
sizeBytes: 1,
|
||||
},
|
||||
])
|
||||
)
|
||||
).rejects.toMatchObject({ code: "attachment_storage_failed" });
|
||||
expect(storage.deleteObject).toHaveBeenCalledWith({
|
||||
bucket: "hivegrid-files",
|
||||
key: "admin-email/first",
|
||||
});
|
||||
});
|
||||
});
|
||||
+293
@@ -0,0 +1,293 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import {
|
||||
getAttachment as getGmailAttachment,
|
||||
} from "./google/gmailApi.js";
|
||||
import {
|
||||
getGraphAttachmentBytes,
|
||||
} from "./microsoft/graphMailApi.js";
|
||||
import type {
|
||||
MappedEmailAttachment,
|
||||
MappedEmailMessage,
|
||||
} from "./email-message-mapping.js";
|
||||
import type { AdminPreparedEmailAttachment } from "./admin-email-sync.server.js";
|
||||
|
||||
export const ADMIN_EMAIL_ATTACHMENT_MAX_BYTES = 100 * 1024 * 1024;
|
||||
|
||||
export type AdminEmailAttachmentErrorCode =
|
||||
| "attachment_too_large"
|
||||
| "attachment_size_invalid"
|
||||
| "attachment_payload_invalid"
|
||||
| "attachment_infected"
|
||||
| "attachment_scan_unavailable"
|
||||
| "attachment_storage_failed";
|
||||
|
||||
export class AdminEmailAttachmentError extends Error {
|
||||
readonly code: AdminEmailAttachmentErrorCode;
|
||||
readonly attachmentId: string;
|
||||
|
||||
constructor(
|
||||
code: AdminEmailAttachmentErrorCode,
|
||||
attachmentId: string,
|
||||
options: { cause?: unknown } = {}
|
||||
) {
|
||||
super(code, options);
|
||||
this.name = "AdminEmailAttachmentError";
|
||||
this.code = code;
|
||||
this.attachmentId = attachmentId;
|
||||
}
|
||||
}
|
||||
|
||||
export type AdminEmailAttachmentScanner = {
|
||||
scanBuffer(bytes: Buffer): Promise<
|
||||
| { readonly verdict: "clean"; readonly engine?: string }
|
||||
| {
|
||||
readonly verdict: "infected";
|
||||
readonly signature: string;
|
||||
readonly engine?: string;
|
||||
}
|
||||
>;
|
||||
};
|
||||
|
||||
export type AdminEmailAttachmentStorage = {
|
||||
putObject(input: {
|
||||
readonly key: string;
|
||||
readonly body: Uint8Array;
|
||||
readonly contentType?: string;
|
||||
readonly metadata?: Record<string, string>;
|
||||
}): Promise<{ readonly bucket: string; readonly key: string }>;
|
||||
deleteObject(input: {
|
||||
readonly bucket?: string;
|
||||
readonly key: string;
|
||||
}): Promise<unknown>;
|
||||
};
|
||||
|
||||
type DownloadAttachment = (input: {
|
||||
readonly provider: "google_mail" | "microsoft_mail";
|
||||
readonly accessToken: string;
|
||||
readonly providerMessageId: string;
|
||||
readonly attachment: MappedEmailAttachment;
|
||||
}) => Promise<Uint8Array>;
|
||||
|
||||
export type AdminEmailAttachmentProcessor = {
|
||||
prepare(input: {
|
||||
readonly adminUserId: string;
|
||||
readonly mailboxId: string;
|
||||
readonly provider: "google_mail" | "microsoft_mail";
|
||||
readonly accessToken: string;
|
||||
readonly message: MappedEmailMessage;
|
||||
readonly now: Date;
|
||||
}): Promise<readonly AdminPreparedEmailAttachment[]>;
|
||||
rollback(
|
||||
attachments: readonly AdminPreparedEmailAttachment[]
|
||||
): Promise<void>;
|
||||
};
|
||||
|
||||
export function createAdminEmailAttachmentProcessor(input: {
|
||||
readonly scanner?: AdminEmailAttachmentScanner;
|
||||
readonly storage?: AdminEmailAttachmentStorage;
|
||||
readonly download?: DownloadAttachment;
|
||||
readonly maxBytes?: number;
|
||||
}): AdminEmailAttachmentProcessor {
|
||||
const maxBytes = input.maxBytes ?? ADMIN_EMAIL_ATTACHMENT_MAX_BYTES;
|
||||
if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
|
||||
throw new Error("Admin email attachment limit must be a positive integer");
|
||||
}
|
||||
|
||||
return {
|
||||
async prepare(request) {
|
||||
if (request.message.attachments.length === 0) return [];
|
||||
if (!input.scanner) {
|
||||
throw attachmentError(
|
||||
"attachment_scan_unavailable",
|
||||
request.message.attachments[0]!.attachmentId
|
||||
);
|
||||
}
|
||||
if (!input.storage) {
|
||||
throw attachmentError(
|
||||
"attachment_storage_failed",
|
||||
request.message.attachments[0]!.attachmentId
|
||||
);
|
||||
}
|
||||
|
||||
const prepared: AdminPreparedEmailAttachment[] = [];
|
||||
try {
|
||||
for (const attachment of request.message.attachments) {
|
||||
validateDeclaredSize(attachment, maxBytes);
|
||||
const bytes = await (input.download ?? downloadProviderAttachment)({
|
||||
provider: request.provider,
|
||||
accessToken: request.accessToken,
|
||||
providerMessageId: request.message.providerMessageId,
|
||||
attachment,
|
||||
});
|
||||
validateDownloadedSize(attachment, bytes, maxBytes);
|
||||
let scan;
|
||||
try {
|
||||
scan = await input.scanner.scanBuffer(Buffer.from(bytes));
|
||||
} catch (cause) {
|
||||
throw attachmentError(
|
||||
"attachment_scan_unavailable",
|
||||
attachment.attachmentId,
|
||||
cause
|
||||
);
|
||||
}
|
||||
if (scan.verdict !== "clean") {
|
||||
throw attachmentError(
|
||||
"attachment_infected",
|
||||
attachment.attachmentId
|
||||
);
|
||||
}
|
||||
|
||||
const checksumSha256 = createHash("sha256")
|
||||
.update(bytes)
|
||||
.digest("hex");
|
||||
const storageKey = [
|
||||
"admin-email",
|
||||
safeKeyPart(request.adminUserId),
|
||||
safeKeyPart(request.mailboxId),
|
||||
safeKeyPart(request.message.providerMessageId),
|
||||
`${safeKeyPart(attachment.attachmentId)}-${checksumSha256}`,
|
||||
].join("/");
|
||||
let stored;
|
||||
try {
|
||||
stored = await input.storage.putObject({
|
||||
key: storageKey,
|
||||
body: bytes,
|
||||
...(attachment.mimeType
|
||||
? { contentType: attachment.mimeType }
|
||||
: {}),
|
||||
metadata: {
|
||||
checksumSha256,
|
||||
source: "admin-email",
|
||||
},
|
||||
});
|
||||
} catch (cause) {
|
||||
throw attachmentError(
|
||||
"attachment_storage_failed",
|
||||
attachment.attachmentId,
|
||||
cause
|
||||
);
|
||||
}
|
||||
prepared.push({
|
||||
providerAttachmentId: attachment.attachmentId,
|
||||
filename: safeFilename(attachment.filename),
|
||||
mimeType: attachment.mimeType,
|
||||
sizeBytes: bytes.byteLength,
|
||||
storageBucket: stored.bucket,
|
||||
storageKey: stored.key,
|
||||
checksumSha256,
|
||||
scannedAt: request.now,
|
||||
});
|
||||
}
|
||||
return prepared;
|
||||
} catch (error) {
|
||||
await rollbackStored(input.storage, prepared);
|
||||
throw error;
|
||||
}
|
||||
},
|
||||
rollback: (attachments) =>
|
||||
input.storage
|
||||
? rollbackStored(input.storage, attachments)
|
||||
: Promise.resolve(),
|
||||
};
|
||||
}
|
||||
|
||||
async function downloadProviderAttachment(
|
||||
input: Parameters<DownloadAttachment>[0]
|
||||
): Promise<Uint8Array> {
|
||||
if (input.provider === "google_mail") {
|
||||
const result = await getGmailAttachment(
|
||||
input.accessToken,
|
||||
input.providerMessageId,
|
||||
input.attachment.attachmentId
|
||||
);
|
||||
return decodeBase64Url(result.data, input.attachment.attachmentId);
|
||||
}
|
||||
return getGraphAttachmentBytes(
|
||||
input.accessToken,
|
||||
input.providerMessageId,
|
||||
input.attachment.attachmentId,
|
||||
ADMIN_EMAIL_ATTACHMENT_MAX_BYTES
|
||||
);
|
||||
}
|
||||
|
||||
function validateDeclaredSize(
|
||||
attachment: MappedEmailAttachment,
|
||||
maxBytes: number
|
||||
): void {
|
||||
if (
|
||||
!Number.isSafeInteger(attachment.sizeBytes) ||
|
||||
attachment.sizeBytes < 0
|
||||
) {
|
||||
throw attachmentError(
|
||||
"attachment_size_invalid",
|
||||
attachment.attachmentId
|
||||
);
|
||||
}
|
||||
if (attachment.sizeBytes > maxBytes) {
|
||||
throw attachmentError("attachment_too_large", attachment.attachmentId);
|
||||
}
|
||||
}
|
||||
|
||||
function validateDownloadedSize(
|
||||
attachment: MappedEmailAttachment,
|
||||
bytes: Uint8Array,
|
||||
maxBytes: number
|
||||
): void {
|
||||
if (bytes.byteLength > maxBytes) {
|
||||
throw attachmentError("attachment_too_large", attachment.attachmentId);
|
||||
}
|
||||
if (
|
||||
attachment.sizeBytes > 0 &&
|
||||
bytes.byteLength !== attachment.sizeBytes
|
||||
) {
|
||||
throw attachmentError(
|
||||
"attachment_size_invalid",
|
||||
attachment.attachmentId
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function decodeBase64Url(value: string, attachmentId: string): Uint8Array {
|
||||
if (!/^[A-Za-z0-9_-]*={0,2}$/u.test(value)) {
|
||||
throw attachmentError("attachment_payload_invalid", attachmentId);
|
||||
}
|
||||
const normalized = value.replace(/-/gu, "+").replace(/_/gu, "/");
|
||||
if (normalized.replace(/=+$/u, "").length % 4 === 1) {
|
||||
throw attachmentError("attachment_payload_invalid", attachmentId);
|
||||
}
|
||||
return Buffer.from(normalized, "base64");
|
||||
}
|
||||
|
||||
function safeFilename(value: string): string {
|
||||
const normalized = value
|
||||
.normalize("NFKC")
|
||||
.replace(/[\u0000-\u001f\u007f/\\]/gu, "_")
|
||||
.trim();
|
||||
return normalized.slice(0, 255) || "attachment";
|
||||
}
|
||||
|
||||
function safeKeyPart(value: string): string {
|
||||
return encodeURIComponent(value.trim()).replace(/%/gu, "_");
|
||||
}
|
||||
|
||||
async function rollbackStored(
|
||||
storage: AdminEmailAttachmentStorage,
|
||||
attachments: readonly AdminPreparedEmailAttachment[]
|
||||
): Promise<void> {
|
||||
await Promise.allSettled(
|
||||
attachments.map((attachment) =>
|
||||
storage.deleteObject({
|
||||
bucket: attachment.storageBucket,
|
||||
key: attachment.storageKey,
|
||||
})
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function attachmentError(
|
||||
code: AdminEmailAttachmentErrorCode,
|
||||
attachmentId: string,
|
||||
cause?: unknown
|
||||
): AdminEmailAttachmentError {
|
||||
return new AdminEmailAttachmentError(code, attachmentId, { cause });
|
||||
}
|
||||
+78
@@ -0,0 +1,78 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
appendAdminEmailSignature,
|
||||
assertOutboundPolicyReady,
|
||||
renderAdminEmailTemplate,
|
||||
} from "./admin-email-compose.js";
|
||||
|
||||
describe("admin email composer", () => {
|
||||
it("renders only explicitly allowed placeholders", () => {
|
||||
expect(
|
||||
renderAdminEmailTemplate(
|
||||
{
|
||||
subjectTemplate: "Demo für {{ contact.company }}",
|
||||
htmlTemplate: "<p>Hallo {{contact.firstName}}</p>",
|
||||
textTemplate: "Hallo {{contact.firstName}}",
|
||||
allowedPlaceholders: [
|
||||
"contact.company",
|
||||
"contact.firstName",
|
||||
],
|
||||
},
|
||||
{
|
||||
contact: {
|
||||
firstName: "Mara",
|
||||
lastName: "Muster",
|
||||
company: "Muster GmbH",
|
||||
},
|
||||
admin: { firstName: "Raffael", lastName: "Sheikh" },
|
||||
}
|
||||
)
|
||||
).toEqual({
|
||||
subject: "Demo für Muster GmbH",
|
||||
html: "<p>Hallo Mara</p>",
|
||||
text: "Hallo Mara",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects unknown or undeclared placeholders", () => {
|
||||
expect(() =>
|
||||
renderAdminEmailTemplate(
|
||||
{
|
||||
subjectTemplate: "{{contact.email}}",
|
||||
htmlTemplate: "<p>Hallo</p>",
|
||||
allowedPlaceholders: [],
|
||||
},
|
||||
{
|
||||
contact: { firstName: "", lastName: "", company: "" },
|
||||
admin: { firstName: "", lastName: "" },
|
||||
}
|
||||
)
|
||||
).toThrowError(expect.objectContaining({ code: "unknown_placeholder" }));
|
||||
});
|
||||
|
||||
it("adds the personal signature and blocks incomplete outbound policy", () => {
|
||||
expect(
|
||||
appendAdminEmailSignature({
|
||||
bodyHtml: "<p>Viele Grüße</p>",
|
||||
bodyText: "Viele Grüße",
|
||||
signatureHtml: "<strong>Raffael</strong>",
|
||||
signatureText: "Raffael",
|
||||
})
|
||||
).toEqual({
|
||||
html: "<p>Viele Grüße</p><br><br><strong>Raffael</strong>",
|
||||
text: "Viele Grüße\n\nRaffael",
|
||||
});
|
||||
expect(() =>
|
||||
assertOutboundPolicyReady({
|
||||
configuredAt: null,
|
||||
consentRulesConfigured: false,
|
||||
dailySendLimit: 0,
|
||||
allowedWeekDays: [],
|
||||
workdayStartMinutes: 540,
|
||||
workdayEndMinutes: 1020,
|
||||
})
|
||||
).toThrowError(
|
||||
expect.objectContaining({ code: "outbound_policy_incomplete" })
|
||||
);
|
||||
});
|
||||
});
|
||||
+128
@@ -0,0 +1,128 @@
|
||||
export const ADMIN_EMAIL_PLACEHOLDERS = [
|
||||
"contact.firstName",
|
||||
"contact.lastName",
|
||||
"contact.company",
|
||||
"admin.firstName",
|
||||
"admin.lastName",
|
||||
] as const;
|
||||
|
||||
export type AdminEmailPlaceholder =
|
||||
(typeof ADMIN_EMAIL_PLACEHOLDERS)[number];
|
||||
|
||||
export type AdminEmailTemplateSource = {
|
||||
readonly subjectTemplate: string;
|
||||
readonly htmlTemplate: string;
|
||||
readonly textTemplate?: string | null;
|
||||
readonly allowedPlaceholders: readonly string[];
|
||||
};
|
||||
|
||||
export type AdminEmailRenderContext = {
|
||||
readonly contact: {
|
||||
readonly firstName: string;
|
||||
readonly lastName: string;
|
||||
readonly company: string;
|
||||
};
|
||||
readonly admin: {
|
||||
readonly firstName: string;
|
||||
readonly lastName: string;
|
||||
};
|
||||
};
|
||||
|
||||
const PLACEHOLDER = /\{\{\s*([a-zA-Z][\w.]+)\s*\}\}/g;
|
||||
|
||||
export function renderAdminEmailTemplate(
|
||||
source: AdminEmailTemplateSource,
|
||||
context: AdminEmailRenderContext
|
||||
) {
|
||||
const allowed = new Set(
|
||||
source.allowedPlaceholders.map(assertAllowedPlaceholder)
|
||||
);
|
||||
const render = (value: string) =>
|
||||
value.replace(PLACEHOLDER, (_match, rawKey: string) => {
|
||||
const key = assertAllowedPlaceholder(rawKey);
|
||||
if (!allowed.has(key)) {
|
||||
throw new AdminEmailComposeError("placeholder_not_allowed", key);
|
||||
}
|
||||
return placeholderValue(key, context);
|
||||
});
|
||||
return Object.freeze({
|
||||
subject: render(source.subjectTemplate).trim(),
|
||||
html: render(source.htmlTemplate),
|
||||
text: source.textTemplate ? render(source.textTemplate) : null,
|
||||
});
|
||||
}
|
||||
|
||||
export function appendAdminEmailSignature(input: {
|
||||
readonly bodyHtml: string;
|
||||
readonly bodyText?: string | null;
|
||||
readonly signatureHtml?: string | null;
|
||||
readonly signatureText?: string | null;
|
||||
}) {
|
||||
return Object.freeze({
|
||||
html: input.signatureHtml
|
||||
? `${input.bodyHtml}<br><br>${input.signatureHtml}`
|
||||
: input.bodyHtml,
|
||||
text: input.bodyText
|
||||
? input.signatureText
|
||||
? `${input.bodyText}\n\n${input.signatureText}`
|
||||
: input.bodyText
|
||||
: null,
|
||||
});
|
||||
}
|
||||
|
||||
export function assertOutboundPolicyReady(policy: {
|
||||
readonly configuredAt: Date | null;
|
||||
readonly consentRulesConfigured: boolean;
|
||||
readonly dailySendLimit: number;
|
||||
readonly allowedWeekDays: readonly number[];
|
||||
readonly workdayStartMinutes: number;
|
||||
readonly workdayEndMinutes: number;
|
||||
}) {
|
||||
if (
|
||||
!policy.configuredAt ||
|
||||
!policy.consentRulesConfigured ||
|
||||
policy.dailySendLimit < 1 ||
|
||||
policy.allowedWeekDays.length === 0 ||
|
||||
policy.workdayStartMinutes < 0 ||
|
||||
policy.workdayEndMinutes > 24 * 60 ||
|
||||
policy.workdayStartMinutes >= policy.workdayEndMinutes
|
||||
) {
|
||||
throw new AdminEmailComposeError("outbound_policy_incomplete");
|
||||
}
|
||||
}
|
||||
|
||||
function assertAllowedPlaceholder(value: string): AdminEmailPlaceholder {
|
||||
if (
|
||||
!ADMIN_EMAIL_PLACEHOLDERS.includes(value as AdminEmailPlaceholder)
|
||||
) {
|
||||
throw new AdminEmailComposeError("unknown_placeholder", value);
|
||||
}
|
||||
return value as AdminEmailPlaceholder;
|
||||
}
|
||||
|
||||
function placeholderValue(
|
||||
key: AdminEmailPlaceholder,
|
||||
context: AdminEmailRenderContext
|
||||
): string {
|
||||
const [group, field] = key.split(".") as [
|
||||
keyof AdminEmailRenderContext,
|
||||
string,
|
||||
];
|
||||
const value = context[group][field as keyof (typeof context)[typeof group]];
|
||||
return typeof value === "string" ? value : "";
|
||||
}
|
||||
|
||||
export class AdminEmailComposeError extends Error {
|
||||
readonly code:
|
||||
| "unknown_placeholder"
|
||||
| "placeholder_not_allowed"
|
||||
| "outbound_policy_incomplete";
|
||||
readonly field?: string;
|
||||
|
||||
constructor(code: AdminEmailComposeError["code"], field?: string) {
|
||||
super(code);
|
||||
this.name = "AdminEmailComposeError";
|
||||
this.code = code;
|
||||
this.field = field;
|
||||
}
|
||||
}
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { checkAdminSendingDomains } from "./admin-email-domain-worker.server.js";
|
||||
|
||||
describe("admin sending-domain worker", () => {
|
||||
it("checks a bounded due batch and persists exact verification state", async () => {
|
||||
const findMany = vi.fn().mockResolvedValue([
|
||||
{
|
||||
id: "domain-1",
|
||||
spfRecordName: "hivegrid.de",
|
||||
spfExpectedValue: "v=spf1 include:spf.mailjet.com ~all",
|
||||
dkimRecordName: "mailjet._domainkey.hivegrid.de",
|
||||
dkimExpectedValue: "k=rsa; p=key",
|
||||
},
|
||||
]);
|
||||
const update = vi.fn().mockResolvedValue({});
|
||||
const resolveTxt = vi.fn(async (name: string) =>
|
||||
name.startsWith("mailjet.")
|
||||
? [["k=rsa; p=key"]]
|
||||
: [["v=spf1 include:spf.mailjet.com ~all"]]
|
||||
);
|
||||
|
||||
await expect(
|
||||
checkAdminSendingDomains(
|
||||
{ adminSendingDomain: { findMany, update } },
|
||||
{
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
take: 500,
|
||||
resolveTxt,
|
||||
}
|
||||
)
|
||||
).resolves.toEqual({
|
||||
inspected: 1,
|
||||
verified: 1,
|
||||
degraded: 0,
|
||||
failed: [],
|
||||
});
|
||||
expect(findMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ take: 200 })
|
||||
);
|
||||
expect(update).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
status: "verified",
|
||||
spfStatus: "verified",
|
||||
dkimStatus: "verified",
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("records resolver failures without leaking diagnostics", async () => {
|
||||
const update = vi.fn().mockResolvedValue({});
|
||||
const client = {
|
||||
adminSendingDomain: {
|
||||
findMany: vi.fn().mockResolvedValue([
|
||||
{
|
||||
id: "domain-secret-free-id",
|
||||
spfRecordName: "hivegrid.de",
|
||||
spfExpectedValue: "spf",
|
||||
dkimRecordName: "mailjet._domainkey.hivegrid.de",
|
||||
dkimExpectedValue: "dkim",
|
||||
},
|
||||
]),
|
||||
update,
|
||||
},
|
||||
};
|
||||
await expect(
|
||||
checkAdminSendingDomains(client, {
|
||||
resolveTxt: vi.fn(async () => {
|
||||
throw new Error("resolver credentials must not escape");
|
||||
}),
|
||||
})
|
||||
).resolves.toEqual({
|
||||
inspected: 1,
|
||||
verified: 0,
|
||||
degraded: 1,
|
||||
failed: [],
|
||||
});
|
||||
expect(JSON.stringify(update.mock.calls)).not.toContain(
|
||||
"resolver credentials"
|
||||
);
|
||||
});
|
||||
});
|
||||
+98
@@ -0,0 +1,98 @@
|
||||
import { resolveTxt as nodeResolveTxt } from "node:dns/promises";
|
||||
import { applyAdminSendingDomainCheck } from "@hivegrid/db/admin-email-domain.server";
|
||||
import { verifyAdminSendingDomainDns } from "./admin-email-domain.js";
|
||||
|
||||
const DEFAULT_STALE_MS = 6 * 60 * 60 * 1_000;
|
||||
|
||||
type DomainRow = {
|
||||
readonly id: string;
|
||||
readonly spfRecordName: string;
|
||||
readonly spfExpectedValue: string;
|
||||
readonly dkimRecordName: string;
|
||||
readonly dkimExpectedValue: string;
|
||||
};
|
||||
|
||||
export type AdminSendingDomainWorkerClient = {
|
||||
readonly adminSendingDomain: {
|
||||
findMany(input: Record<string, unknown>): Promise<readonly DomainRow[]>;
|
||||
update(input: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
};
|
||||
|
||||
export async function checkAdminSendingDomains(
|
||||
client: AdminSendingDomainWorkerClient,
|
||||
input: {
|
||||
readonly now?: Date;
|
||||
readonly take?: number;
|
||||
readonly staleMs?: number;
|
||||
readonly resolveTxt?: (
|
||||
hostname: string
|
||||
) => Promise<readonly (readonly string[])[]>;
|
||||
} = {}
|
||||
): Promise<{
|
||||
readonly inspected: number;
|
||||
readonly verified: number;
|
||||
readonly degraded: number;
|
||||
readonly failed: readonly string[];
|
||||
}> {
|
||||
const now = input.now ?? new Date();
|
||||
const take = Math.max(1, Math.min(Math.trunc(input.take ?? 50), 200));
|
||||
const rows = await client.adminSendingDomain.findMany({
|
||||
where: {
|
||||
archivedAt: null,
|
||||
status: { in: ["pending", "verified", "degraded"] },
|
||||
OR: [
|
||||
{ lastCheckedAt: null },
|
||||
{
|
||||
lastCheckedAt: {
|
||||
lte: new Date(now.getTime() - (input.staleMs ?? DEFAULT_STALE_MS)),
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
orderBy: [{ lastCheckedAt: "asc" }, { id: "asc" }],
|
||||
take,
|
||||
select: {
|
||||
id: true,
|
||||
spfRecordName: true,
|
||||
spfExpectedValue: true,
|
||||
dkimRecordName: true,
|
||||
dkimExpectedValue: true,
|
||||
},
|
||||
});
|
||||
let verified = 0;
|
||||
let degraded = 0;
|
||||
const failed: string[] = [];
|
||||
for (const row of rows) {
|
||||
try {
|
||||
const check = await verifyAdminSendingDomainDns({
|
||||
...row,
|
||||
resolveTxt: input.resolveTxt ?? nodeResolveTxt,
|
||||
});
|
||||
await applyAdminSendingDomainCheck(client as never, {
|
||||
domainId: row.id,
|
||||
check,
|
||||
checkedAt: now,
|
||||
});
|
||||
if (check.status === "verified") verified += 1;
|
||||
else degraded += 1;
|
||||
} catch {
|
||||
failed.push(row.id);
|
||||
await applyAdminSendingDomainCheck(client as never, {
|
||||
domainId: row.id,
|
||||
check: {
|
||||
status: "degraded",
|
||||
spfStatus: "error",
|
||||
dkimStatus: "error",
|
||||
},
|
||||
checkedAt: now,
|
||||
});
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
inspected: rows.length,
|
||||
verified,
|
||||
degraded,
|
||||
failed: Object.freeze(failed),
|
||||
});
|
||||
}
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
createAdminBccCapability,
|
||||
verifyAdminBccCapability,
|
||||
verifyAdminSendingDomainDns,
|
||||
} from "./admin-email-domain.js";
|
||||
|
||||
const secret = "admin-bcc-secret".padEnd(40, "x");
|
||||
|
||||
describe("admin BCC capability", () => {
|
||||
it("creates a bounded signed address and verifies it without a database scan", () => {
|
||||
const capability = createAdminBccCapability({
|
||||
adminUserId: "admin_user_123",
|
||||
inboundDomain: "bcc.hivegrid.de",
|
||||
secret,
|
||||
randomBytes: () => new Uint8Array(8).fill(7),
|
||||
});
|
||||
|
||||
expect(capability.normalizedAddress).toMatch(
|
||||
/^b1\.admin_user_123\.[A-Za-z0-9_-]{11}\.[A-Za-z0-9_-]{22}@bcc\.hivegrid\.de$/u
|
||||
);
|
||||
expect(capability.normalizedAddress.split("@")[0]?.length).toBeLessThanOrEqual(
|
||||
64
|
||||
);
|
||||
expect(
|
||||
verifyAdminBccCapability({
|
||||
address: capability.normalizedAddress.replace(
|
||||
"@bcc.hivegrid.de",
|
||||
"@BCC.HIVEGRID.DE"
|
||||
),
|
||||
inboundDomain: "BCC.HIVEGRID.DE.",
|
||||
secret,
|
||||
})
|
||||
).toEqual(capability);
|
||||
});
|
||||
|
||||
it("rejects tampering, wrong domains and weak secrets", () => {
|
||||
const capability = createAdminBccCapability({
|
||||
adminUserId: "admin_user_123",
|
||||
inboundDomain: "bcc.hivegrid.de",
|
||||
secret,
|
||||
randomBytes: () => new Uint8Array(8).fill(9),
|
||||
});
|
||||
|
||||
expect(
|
||||
verifyAdminBccCapability({
|
||||
address: capability.normalizedAddress.replace("admin_user_123", "admin_user_124"),
|
||||
inboundDomain: "bcc.hivegrid.de",
|
||||
secret,
|
||||
})
|
||||
).toBeNull();
|
||||
expect(
|
||||
verifyAdminBccCapability({
|
||||
address: capability.normalizedAddress,
|
||||
inboundDomain: "other.hivegrid.de",
|
||||
secret,
|
||||
})
|
||||
).toBeNull();
|
||||
expect(
|
||||
verifyAdminBccCapability({
|
||||
address: capability.normalizedAddress,
|
||||
inboundDomain: "bcc.hivegrid.de",
|
||||
secret: "weak",
|
||||
})
|
||||
).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("admin sending-domain DNS verification", () => {
|
||||
it("requires exact SPF and DKIM records while joining split TXT chunks", async () => {
|
||||
const resolveTxt = vi.fn(async (hostname: string) => {
|
||||
if (hostname === "hivegrid.de") {
|
||||
return [["v=spf1 include:spf.mailjet.com ~all"]];
|
||||
}
|
||||
return [
|
||||
["k=rsa; p=MIIB", "IjANBgkqh"],
|
||||
["unrelated"],
|
||||
];
|
||||
});
|
||||
|
||||
await expect(
|
||||
verifyAdminSendingDomainDns({
|
||||
spfRecordName: "HiveGrid.de.",
|
||||
spfExpectedValue: "v=spf1 include:spf.mailjet.com ~all",
|
||||
dkimRecordName: "mailjet._domainkey.hivegrid.de",
|
||||
dkimExpectedValue: "k=rsa; p=MIIBIjANBgkqh",
|
||||
resolveTxt,
|
||||
})
|
||||
).resolves.toEqual({
|
||||
spfStatus: "verified",
|
||||
dkimStatus: "verified",
|
||||
status: "verified",
|
||||
});
|
||||
});
|
||||
|
||||
it("distinguishes missing, mismatched and resolver errors", async () => {
|
||||
const missing = Object.assign(new Error("not found"), { code: "ENOTFOUND" });
|
||||
const resolveTxt = vi.fn(async (hostname: string) => {
|
||||
if (hostname === "missing.example") throw missing;
|
||||
return [["different"]];
|
||||
});
|
||||
|
||||
await expect(
|
||||
verifyAdminSendingDomainDns({
|
||||
spfRecordName: "missing.example",
|
||||
spfExpectedValue: "spf",
|
||||
dkimRecordName: "dkim.example",
|
||||
dkimExpectedValue: "dkim",
|
||||
resolveTxt,
|
||||
})
|
||||
).resolves.toEqual({
|
||||
spfStatus: "missing",
|
||||
dkimStatus: "mismatch",
|
||||
status: "degraded",
|
||||
});
|
||||
});
|
||||
});
|
||||
+226
@@ -0,0 +1,226 @@
|
||||
import {
|
||||
createHash,
|
||||
createHmac,
|
||||
randomBytes as nodeRandomBytes,
|
||||
timingSafeEqual,
|
||||
} from "node:crypto";
|
||||
|
||||
const BCC_VERSION = "b1";
|
||||
const BCC_NONCE_BYTES = 8;
|
||||
const BCC_SIGNATURE_BYTES = 16;
|
||||
const MIN_SECRET_LENGTH = 32;
|
||||
const ADMIN_ID_PATTERN = /^[A-Za-z0-9_-]{8,40}$/u;
|
||||
const DOMAIN_PATTERN =
|
||||
/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/u;
|
||||
|
||||
export type AdminBccCapability = {
|
||||
readonly adminUserId: string;
|
||||
readonly localPartHash: string;
|
||||
readonly normalizedAddress: string;
|
||||
};
|
||||
|
||||
export type AdminSendingDomainDnsResult = {
|
||||
readonly spfStatus: "verified" | "missing" | "mismatch" | "error";
|
||||
readonly dkimStatus: "verified" | "missing" | "mismatch" | "error";
|
||||
readonly status: "verified" | "degraded";
|
||||
};
|
||||
|
||||
export function createAdminBccCapability(input: {
|
||||
readonly adminUserId: string;
|
||||
readonly inboundDomain: string;
|
||||
readonly secret: string;
|
||||
readonly randomBytes?: (size: number) => Uint8Array;
|
||||
}): AdminBccCapability {
|
||||
const adminUserId = normalizeAdminId(input.adminUserId);
|
||||
const inboundDomain = normalizeDomain(input.inboundDomain);
|
||||
validateSecret(input.secret);
|
||||
const nonce = Buffer.from(
|
||||
(input.randomBytes ?? nodeRandomBytes)(BCC_NONCE_BYTES)
|
||||
).toString("base64url");
|
||||
const payload = `${BCC_VERSION}.${adminUserId}.${nonce}`;
|
||||
const signature = signBccPayload(payload, input.secret);
|
||||
const localPart = `${payload}.${signature}`;
|
||||
if (Buffer.byteLength(localPart, "ascii") > 64) {
|
||||
throw new AdminEmailDomainError("bcc_local_part_too_long");
|
||||
}
|
||||
const normalizedAddress = `${localPart}@${inboundDomain}`;
|
||||
return Object.freeze({
|
||||
adminUserId,
|
||||
localPartHash: hashAdminBccLocalPart(localPart),
|
||||
normalizedAddress,
|
||||
});
|
||||
}
|
||||
|
||||
export function verifyAdminBccCapability(input: {
|
||||
readonly address: string;
|
||||
readonly inboundDomain: string;
|
||||
readonly secret: string;
|
||||
}): AdminBccCapability | null {
|
||||
try {
|
||||
validateSecret(input.secret);
|
||||
const normalizedAddress = normalizeAddress(input.address);
|
||||
const expectedDomain = normalizeDomain(input.inboundDomain);
|
||||
const separator = normalizedAddress.lastIndexOf("@");
|
||||
if (separator <= 0 || normalizedAddress.slice(separator + 1) !== expectedDomain) {
|
||||
return null;
|
||||
}
|
||||
const localPart = normalizedAddress.slice(0, separator);
|
||||
const parts = localPart.split(".");
|
||||
if (parts.length !== 4 || parts[0] !== BCC_VERSION) return null;
|
||||
const adminUserId = normalizeAdminId(parts[1] ?? "");
|
||||
const nonce = parts[2] ?? "";
|
||||
const signature = parts[3] ?? "";
|
||||
if (!/^[A-Za-z0-9_-]{11}$/u.test(nonce)) return null;
|
||||
const payload = `${BCC_VERSION}.${adminUserId}.${nonce}`;
|
||||
const expected = Buffer.from(signBccPayload(payload, input.secret));
|
||||
const actual = Buffer.from(signature);
|
||||
if (
|
||||
expected.byteLength !== actual.byteLength ||
|
||||
!timingSafeEqual(expected, actual)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
return Object.freeze({
|
||||
adminUserId,
|
||||
localPartHash: hashAdminBccLocalPart(localPart),
|
||||
normalizedAddress,
|
||||
});
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function hashAdminBccLocalPart(localPart: string): string {
|
||||
return createHash("sha256")
|
||||
.update(localPart.trim().toLowerCase())
|
||||
.digest("hex");
|
||||
}
|
||||
|
||||
export async function verifyAdminSendingDomainDns(input: {
|
||||
readonly spfRecordName: string;
|
||||
readonly spfExpectedValue: string;
|
||||
readonly dkimRecordName: string;
|
||||
readonly dkimExpectedValue: string;
|
||||
readonly resolveTxt: (
|
||||
hostname: string
|
||||
) => Promise<readonly (readonly string[])[]>;
|
||||
}): Promise<AdminSendingDomainDnsResult> {
|
||||
const [spfStatus, dkimStatus] = await Promise.all([
|
||||
verifyTxtRecord(
|
||||
normalizeDnsName(input.spfRecordName),
|
||||
normalizeTxtValue(input.spfExpectedValue),
|
||||
input.resolveTxt
|
||||
),
|
||||
verifyTxtRecord(
|
||||
normalizeDnsName(input.dkimRecordName),
|
||||
normalizeTxtValue(input.dkimExpectedValue),
|
||||
input.resolveTxt
|
||||
),
|
||||
]);
|
||||
return Object.freeze({
|
||||
spfStatus,
|
||||
dkimStatus,
|
||||
status:
|
||||
spfStatus === "verified" && dkimStatus === "verified"
|
||||
? "verified"
|
||||
: "degraded",
|
||||
});
|
||||
}
|
||||
|
||||
async function verifyTxtRecord(
|
||||
name: string,
|
||||
expected: string,
|
||||
resolveTxt: (
|
||||
hostname: string
|
||||
) => Promise<readonly (readonly string[])[]>
|
||||
): Promise<AdminSendingDomainDnsResult["spfStatus"]> {
|
||||
try {
|
||||
const answers = await resolveTxt(name);
|
||||
if (answers.length === 0) return "missing";
|
||||
const normalized = answers.map((chunks) =>
|
||||
normalizeTxtValue(chunks.join(""))
|
||||
);
|
||||
return normalized.includes(expected) ? "verified" : "mismatch";
|
||||
} catch (error) {
|
||||
return isDnsNotFound(error) ? "missing" : "error";
|
||||
}
|
||||
}
|
||||
|
||||
function signBccPayload(payload: string, secret: string): string {
|
||||
return createHmac("sha256", secret)
|
||||
.update(payload)
|
||||
.digest()
|
||||
.subarray(0, BCC_SIGNATURE_BYTES)
|
||||
.toString("base64url");
|
||||
}
|
||||
|
||||
function normalizeAdminId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!ADMIN_ID_PATTERN.test(normalized)) {
|
||||
throw new AdminEmailDomainError("invalid_admin_user_id");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeDomain(value: string): string {
|
||||
const normalized = value.trim().toLowerCase().replace(/\.$/u, "");
|
||||
if (!DOMAIN_PATTERN.test(normalized)) {
|
||||
throw new AdminEmailDomainError("invalid_domain");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeDnsName(value: string): string {
|
||||
const normalized = value.trim().toLowerCase().replace(/\.$/u, "");
|
||||
if (
|
||||
normalized.length > 253 ||
|
||||
!/^(?:[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?\.)+[a-z0-9_][a-z0-9_-]{0,62}$/u.test(
|
||||
normalized
|
||||
)
|
||||
) {
|
||||
throw new AdminEmailDomainError("invalid_domain");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeAddress(value: string): string {
|
||||
const trimmed = value.trim();
|
||||
if (
|
||||
trimmed.length > 320 ||
|
||||
/[\u0000-\u001f\u007f\s]/u.test(trimmed)
|
||||
) {
|
||||
throw new AdminEmailDomainError("invalid_bcc_address");
|
||||
}
|
||||
const separator = trimmed.lastIndexOf("@");
|
||||
if (separator <= 0) throw new AdminEmailDomainError("invalid_bcc_address");
|
||||
return `${trimmed.slice(0, separator)}@${trimmed
|
||||
.slice(separator + 1)
|
||||
.toLowerCase()}`;
|
||||
}
|
||||
|
||||
function normalizeTxtValue(value: string): string {
|
||||
const normalized = value.trim().replace(/^"(.*)"$/u, "$1");
|
||||
if (!normalized || normalized.length > 4_096) {
|
||||
throw new AdminEmailDomainError("invalid_dns_record");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function validateSecret(secret: string): void {
|
||||
if (Buffer.byteLength(secret, "utf8") < MIN_SECRET_LENGTH) {
|
||||
throw new AdminEmailDomainError("bcc_secret_not_configured");
|
||||
}
|
||||
}
|
||||
|
||||
function isDnsNotFound(error: unknown): boolean {
|
||||
if (!error || typeof error !== "object") return false;
|
||||
const code = "code" in error ? String(error.code) : "";
|
||||
return ["ENODATA", "ENOTFOUND", "ENODOMAIN", "NXDOMAIN"].includes(code);
|
||||
}
|
||||
|
||||
export class AdminEmailDomainError extends Error {
|
||||
constructor(readonly code: string) {
|
||||
super(code);
|
||||
this.name = "AdminEmailDomainError";
|
||||
}
|
||||
}
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
signAdminEmailProviderEvent,
|
||||
verifyAdminEmailProviderEvent,
|
||||
} from "./admin-email-provider-events.js";
|
||||
|
||||
const secret = "provider-event-secret-".padEnd(40, "x");
|
||||
const now = new Date("2026-07-24T12:00:00.000Z");
|
||||
const timestamp = String(now.getTime());
|
||||
const body = JSON.stringify({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
type: "delivered",
|
||||
eventId: "provider-event-1",
|
||||
occurredAt: now.toISOString(),
|
||||
recipient: "Buyer@Example.com",
|
||||
metadata: { responseCode: 250 },
|
||||
});
|
||||
|
||||
describe("admin email provider events", () => {
|
||||
it("authenticates and parses a normalized delivery event", () => {
|
||||
const signature = signAdminEmailProviderEvent({
|
||||
body,
|
||||
timestamp,
|
||||
secret,
|
||||
});
|
||||
expect(
|
||||
verifyAdminEmailProviderEvent({
|
||||
body,
|
||||
timestamp,
|
||||
signature,
|
||||
secret,
|
||||
now,
|
||||
})
|
||||
).toEqual({
|
||||
ok: true,
|
||||
event: {
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
type: "delivered",
|
||||
eventId: "provider-event-1",
|
||||
occurredAt: now,
|
||||
recipient: "buyer@example.com",
|
||||
metadata: { responseCode: 250 },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects replay windows, payload tampering, and missing configuration", () => {
|
||||
const signature = signAdminEmailProviderEvent({
|
||||
body,
|
||||
timestamp,
|
||||
secret,
|
||||
});
|
||||
expect(
|
||||
verifyAdminEmailProviderEvent({
|
||||
body,
|
||||
timestamp,
|
||||
signature,
|
||||
secret,
|
||||
now: new Date(now.getTime() + 5 * 60 * 1_000 + 1),
|
||||
})
|
||||
).toEqual({ ok: false, reason: "expired" });
|
||||
expect(
|
||||
verifyAdminEmailProviderEvent({
|
||||
body: body.replace("delivered", "bounced"),
|
||||
timestamp,
|
||||
signature,
|
||||
secret,
|
||||
now,
|
||||
})
|
||||
).toEqual({ ok: false, reason: "invalid_signature" });
|
||||
expect(
|
||||
verifyAdminEmailProviderEvent({
|
||||
body,
|
||||
timestamp,
|
||||
signature,
|
||||
secret: "",
|
||||
now,
|
||||
})
|
||||
).toEqual({ ok: false, reason: "not_configured" });
|
||||
});
|
||||
|
||||
it("rejects signed payload extensions and malformed owner identifiers", () => {
|
||||
for (const invalidBody of [
|
||||
JSON.stringify({
|
||||
...JSON.parse(body),
|
||||
rawProviderPayload: "must-not-cross-the-boundary",
|
||||
}),
|
||||
JSON.stringify({
|
||||
...JSON.parse(body),
|
||||
adminUserId: "../admin-1",
|
||||
}),
|
||||
]) {
|
||||
expect(
|
||||
verifyAdminEmailProviderEvent({
|
||||
body: invalidBody,
|
||||
timestamp,
|
||||
signature: signAdminEmailProviderEvent({
|
||||
body: invalidBody,
|
||||
timestamp,
|
||||
secret,
|
||||
}),
|
||||
secret,
|
||||
now,
|
||||
})
|
||||
).toEqual({ ok: false, reason: "invalid_payload" });
|
||||
}
|
||||
});
|
||||
});
|
||||
+172
@@ -0,0 +1,172 @@
|
||||
import { createHmac, timingSafeEqual } from "node:crypto";
|
||||
|
||||
const MAX_CLOCK_SKEW_MS = 5 * 60 * 1_000;
|
||||
const MIN_SECRET_LENGTH = 32;
|
||||
const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u;
|
||||
const ALLOWED_EVENT_KEYS = new Set([
|
||||
"adminUserId",
|
||||
"scheduledEmailId",
|
||||
"type",
|
||||
"eventId",
|
||||
"occurredAt",
|
||||
"recipient",
|
||||
"metadata",
|
||||
]);
|
||||
|
||||
export type AdminEmailProviderEvent = {
|
||||
readonly adminUserId: string;
|
||||
readonly scheduledEmailId: string;
|
||||
readonly type: "delivered" | "bounced";
|
||||
readonly eventId: string;
|
||||
readonly occurredAt: Date;
|
||||
readonly recipient: string | null;
|
||||
readonly metadata: Record<string, string | number | boolean | null> | null;
|
||||
};
|
||||
|
||||
export function signAdminEmailProviderEvent(input: {
|
||||
readonly body: string;
|
||||
readonly timestamp: string;
|
||||
readonly secret: string;
|
||||
}): string {
|
||||
validateSecret(input.secret);
|
||||
return `sha256=${createHmac("sha256", input.secret)
|
||||
.update(`${input.timestamp}.${input.body}`)
|
||||
.digest("hex")}`;
|
||||
}
|
||||
|
||||
export function verifyAdminEmailProviderEvent(input: {
|
||||
readonly body: string;
|
||||
readonly timestamp: string | null | undefined;
|
||||
readonly signature: string | null | undefined;
|
||||
readonly secret: string;
|
||||
readonly now?: Date;
|
||||
}):
|
||||
| { readonly ok: true; readonly event: AdminEmailProviderEvent }
|
||||
| {
|
||||
readonly ok: false;
|
||||
readonly reason:
|
||||
| "not_configured"
|
||||
| "invalid_signature"
|
||||
| "expired"
|
||||
| "invalid_payload";
|
||||
} {
|
||||
try {
|
||||
validateSecret(input.secret);
|
||||
} catch {
|
||||
return { ok: false, reason: "not_configured" };
|
||||
}
|
||||
const timestampMs = Number(input.timestamp);
|
||||
if (
|
||||
!Number.isSafeInteger(timestampMs) ||
|
||||
Math.abs((input.now ?? new Date()).getTime() - timestampMs) >
|
||||
MAX_CLOCK_SKEW_MS
|
||||
) {
|
||||
return { ok: false, reason: "expired" };
|
||||
}
|
||||
const expected = Buffer.from(
|
||||
signAdminEmailProviderEvent({
|
||||
body: input.body,
|
||||
timestamp: String(input.timestamp),
|
||||
secret: input.secret,
|
||||
})
|
||||
);
|
||||
const actual = Buffer.from(input.signature ?? "");
|
||||
if (
|
||||
expected.byteLength !== actual.byteLength ||
|
||||
!timingSafeEqual(expected, actual)
|
||||
) {
|
||||
return { ok: false, reason: "invalid_signature" };
|
||||
}
|
||||
try {
|
||||
const raw = JSON.parse(input.body) as Record<string, unknown>;
|
||||
const type =
|
||||
raw.type === "delivered" || raw.type === "bounced" ? raw.type : null;
|
||||
const occurredAt = new Date(
|
||||
typeof raw.occurredAt === "string" ? raw.occurredAt : ""
|
||||
);
|
||||
const metadata = normalizeMetadata(raw.metadata);
|
||||
const adminUserId = normalizeIdentifier(raw.adminUserId);
|
||||
const scheduledEmailId = normalizeIdentifier(raw.scheduledEmailId);
|
||||
const eventId =
|
||||
typeof raw.eventId === "string" &&
|
||||
raw.eventId.trim().length > 0 &&
|
||||
raw.eventId.trim().length <= 500 &&
|
||||
!/[\u0000-\u001f\u007f]/u.test(raw.eventId)
|
||||
? raw.eventId.trim()
|
||||
: null;
|
||||
const recipientIsValid =
|
||||
raw.recipient === undefined ||
|
||||
raw.recipient === null ||
|
||||
typeof raw.recipient === "string";
|
||||
if (
|
||||
Object.keys(raw).some((key) => !ALLOWED_EVENT_KEYS.has(key)) ||
|
||||
!adminUserId ||
|
||||
!scheduledEmailId ||
|
||||
!eventId ||
|
||||
!type ||
|
||||
Number.isNaN(occurredAt.getTime()) ||
|
||||
!recipientIsValid ||
|
||||
metadata === undefined
|
||||
) {
|
||||
return { ok: false, reason: "invalid_payload" };
|
||||
}
|
||||
return {
|
||||
ok: true,
|
||||
event: {
|
||||
adminUserId,
|
||||
scheduledEmailId,
|
||||
type,
|
||||
eventId,
|
||||
occurredAt,
|
||||
recipient:
|
||||
typeof raw.recipient === "string"
|
||||
? raw.recipient.trim().toLowerCase().slice(0, 320) || null
|
||||
: null,
|
||||
metadata,
|
||||
},
|
||||
};
|
||||
} catch {
|
||||
return { ok: false, reason: "invalid_payload" };
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeIdentifier(value: unknown): string | null {
|
||||
const normalized = typeof value === "string" ? value.trim() : "";
|
||||
return IDENTIFIER_PATTERN.test(normalized) ? normalized : null;
|
||||
}
|
||||
|
||||
function normalizeMetadata(
|
||||
value: unknown
|
||||
): Record<string, string | number | boolean | null> | null | undefined {
|
||||
if (value === null || value === undefined) return null;
|
||||
if (typeof value !== "object" || Array.isArray(value)) return undefined;
|
||||
const entries = Object.entries(value as Record<string, unknown>);
|
||||
if (
|
||||
entries.length > 20 ||
|
||||
entries.some(
|
||||
([key, entry]) =>
|
||||
key.length > 80 ||
|
||||
!/^[a-zA-Z0-9_.-]+$/u.test(key) ||
|
||||
!(
|
||||
entry === null ||
|
||||
typeof entry === "string" ||
|
||||
typeof entry === "number" ||
|
||||
typeof entry === "boolean"
|
||||
)
|
||||
)
|
||||
) {
|
||||
return undefined;
|
||||
}
|
||||
return Object.fromEntries(
|
||||
entries.map(([key, entry]) => [
|
||||
key,
|
||||
typeof entry === "string" ? entry.slice(0, 500) : entry,
|
||||
])
|
||||
) as Record<string, string | number | boolean | null>;
|
||||
}
|
||||
|
||||
function validateSecret(secret: string): void {
|
||||
if (Buffer.byteLength(secret, "utf8") < MIN_SECRET_LENGTH) {
|
||||
throw new Error("admin_email_event_webhook_secret_too_short");
|
||||
}
|
||||
}
|
||||
+186
@@ -0,0 +1,186 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import type { MappedEmailMessage } from "./email-message-mapping.js";
|
||||
import {
|
||||
advanceAdminMailboxCursor,
|
||||
createAdminEmailSyncService,
|
||||
decideAdminEmailMatch,
|
||||
providerMessageKey,
|
||||
} from "./admin-email-sync.server.js";
|
||||
|
||||
const message = (overrides: Partial<MappedEmailMessage> = {}): MappedEmailMessage => ({
|
||||
providerMessageId: "provider-1",
|
||||
providerThreadId: "thread-1",
|
||||
internetMessageId: "rfc-1",
|
||||
direction: "inbound",
|
||||
from: { address: "buyer@example.com" },
|
||||
to: [{ address: "sales@hivegrid.de" }],
|
||||
cc: [],
|
||||
bcc: [],
|
||||
subject: "Demo",
|
||||
snippet: "Hallo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
bodyText: "Hallo",
|
||||
sentAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
receivedAt: new Date("2026-07-24T10:00:01.000Z"),
|
||||
isRead: false,
|
||||
hasAttachments: false,
|
||||
isNewsletter: false,
|
||||
providerLabels: ["INBOX"],
|
||||
attachments: [],
|
||||
...overrides,
|
||||
});
|
||||
|
||||
describe("admin email matching", () => {
|
||||
it("matches one exact contact and its only open deal deterministically", () => {
|
||||
expect(
|
||||
decideAdminEmailMatch({
|
||||
message: message(),
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
candidates: [
|
||||
{
|
||||
id: "contact-1",
|
||||
kind: "contact",
|
||||
openDealIds: ["deal-1"],
|
||||
},
|
||||
],
|
||||
})
|
||||
).toMatchObject({
|
||||
status: "matched",
|
||||
contactId: "contact-1",
|
||||
dealId: "deal-1",
|
||||
reason: "single_open_deal",
|
||||
});
|
||||
});
|
||||
|
||||
it("puts duplicate identities and multiple deals into the visible ambiguity path", () => {
|
||||
expect(
|
||||
decideAdminEmailMatch({
|
||||
message: message(),
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
candidates: [
|
||||
{ id: "contact-b", kind: "contact" },
|
||||
{ id: "contact-a", kind: "contact" },
|
||||
],
|
||||
})
|
||||
).toMatchObject({
|
||||
status: "ambiguous",
|
||||
reason: "ambiguous_identity",
|
||||
contactId: null,
|
||||
});
|
||||
|
||||
expect(
|
||||
decideAdminEmailMatch({
|
||||
message: message(),
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
candidates: [
|
||||
{
|
||||
id: "contact-1",
|
||||
kind: "contact",
|
||||
openDealIds: ["deal-b", "deal-a"],
|
||||
},
|
||||
],
|
||||
})
|
||||
).toMatchObject({
|
||||
status: "ambiguous",
|
||||
reason: "ambiguous_deal",
|
||||
dealId: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("does not auto-match newsletters and validates explicit deal references", () => {
|
||||
expect(
|
||||
decideAdminEmailMatch({
|
||||
message: message({ isNewsletter: true }),
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
candidates: [{ id: "contact-1", kind: "contact" }],
|
||||
})
|
||||
).toMatchObject({ status: "unmatched", reason: "newsletter" });
|
||||
|
||||
expect(
|
||||
decideAdminEmailMatch({
|
||||
message: message({ subject: "Re: [Deal #deal-2] Angebot" }),
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
candidates: [
|
||||
{
|
||||
id: "contact-1",
|
||||
kind: "contact",
|
||||
openDealIds: ["deal-1"],
|
||||
},
|
||||
],
|
||||
})
|
||||
).toMatchObject({ status: "ambiguous", reason: "ambiguous_deal" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("admin email sync contract", () => {
|
||||
it("uses stable provider keys and recovers an expired cursor without advancing it", () => {
|
||||
expect(
|
||||
providerMessageKey({
|
||||
mailboxId: "mailbox-1",
|
||||
providerMessageId: "provider-1",
|
||||
})
|
||||
).toBe("mailbox-1:provider-1");
|
||||
expect(
|
||||
advanceAdminMailboxCursor({
|
||||
current: {
|
||||
cursorToken: "old",
|
||||
status: "running",
|
||||
recoveryGeneration: 2,
|
||||
lastErrorMessageKey: null,
|
||||
},
|
||||
nextCursor: null,
|
||||
outcome: "cursor_expired",
|
||||
})
|
||||
).toEqual({
|
||||
cursorToken: null,
|
||||
status: "pending",
|
||||
recoveryGeneration: 3,
|
||||
lastErrorMessageKey: "admin.sales.email.sync.cursorExpired",
|
||||
});
|
||||
});
|
||||
|
||||
it("maps a provider batch once and delegates an atomic cursor/message write", async () => {
|
||||
const persistBatch = vi.fn().mockResolvedValue({
|
||||
upserted: 1,
|
||||
replayed: 0,
|
||||
});
|
||||
const service = createAdminEmailSyncService({ persistBatch });
|
||||
const candidatesFor = vi.fn().mockResolvedValue([
|
||||
{
|
||||
id: "contact-1",
|
||||
kind: "contact",
|
||||
openDealIds: ["deal-1"],
|
||||
},
|
||||
]);
|
||||
|
||||
await expect(
|
||||
service.persistProviderBatch({
|
||||
adminUserId: "admin-1",
|
||||
mailboxId: "mailbox-1",
|
||||
mailboxAddresses: ["sales@hivegrid.de"],
|
||||
externalFolderId: "inbox",
|
||||
expectedCursor: "cursor-1",
|
||||
nextCursor: "cursor-2",
|
||||
messages: [message()],
|
||||
candidatesFor,
|
||||
})
|
||||
).resolves.toEqual({ upserted: 1, replayed: 0 });
|
||||
|
||||
expect(candidatesFor).toHaveBeenCalledWith("buyer@example.com");
|
||||
expect(persistBatch).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
expectedCursor: "cursor-1",
|
||||
nextCursor: "cursor-2",
|
||||
messages: [
|
||||
expect.objectContaining({
|
||||
key: "mailbox-1:provider-1",
|
||||
match: expect.objectContaining({
|
||||
contactId: "contact-1",
|
||||
dealId: "deal-1",
|
||||
}),
|
||||
}),
|
||||
],
|
||||
})
|
||||
);
|
||||
});
|
||||
});
|
||||
+291
@@ -0,0 +1,291 @@
|
||||
import type { MappedEmailMessage } from "./email-message-mapping.js";
|
||||
|
||||
export type AdminEmailMatchCandidate = {
|
||||
readonly id: string;
|
||||
readonly kind: "contact" | "lead";
|
||||
readonly primary?: boolean;
|
||||
readonly openDealIds?: readonly string[];
|
||||
};
|
||||
|
||||
export type AdminEmailMatchDecision = {
|
||||
readonly status: "matched" | "ambiguous" | "unmatched";
|
||||
readonly contactId: string | null;
|
||||
readonly leadId: string | null;
|
||||
readonly dealId: string | null;
|
||||
readonly reason:
|
||||
| "exact_contact"
|
||||
| "exact_lead"
|
||||
| "subject_deal"
|
||||
| "single_open_deal"
|
||||
| "ambiguous_identity"
|
||||
| "ambiguous_deal"
|
||||
| "newsletter"
|
||||
| "no_candidate";
|
||||
readonly candidates: readonly AdminEmailMatchCandidate[];
|
||||
};
|
||||
|
||||
export type AdminMailboxCursorState = {
|
||||
readonly cursorToken: string | null;
|
||||
readonly status: "pending" | "running" | "complete" | "failed";
|
||||
readonly recoveryGeneration: number;
|
||||
readonly lastErrorMessageKey: string | null;
|
||||
};
|
||||
|
||||
const DEAL_REFERENCE = /\[\s*Deal\s*#\s*([\w-]+)\s*\]/i;
|
||||
|
||||
export function decideAdminEmailMatch(input: {
|
||||
readonly message: Pick<
|
||||
MappedEmailMessage,
|
||||
"direction" | "from" | "to" | "subject" | "isNewsletter"
|
||||
>;
|
||||
readonly mailboxAddresses: readonly string[];
|
||||
readonly candidates: readonly AdminEmailMatchCandidate[];
|
||||
}): AdminEmailMatchDecision {
|
||||
if (input.message.isNewsletter) {
|
||||
return decision("unmatched", "newsletter", input.candidates);
|
||||
}
|
||||
|
||||
const counterpart = adminEmailCounterpartAddress(
|
||||
input.message,
|
||||
input.mailboxAddresses
|
||||
);
|
||||
const candidates = counterpart
|
||||
? [...input.candidates].sort((left, right) => left.id.localeCompare(right.id))
|
||||
: [];
|
||||
const contacts = candidates.filter((candidate) => candidate.kind === "contact");
|
||||
const leads = candidates.filter((candidate) => candidate.kind === "lead");
|
||||
const contact = selectSingleIdentity(contacts);
|
||||
|
||||
if (contacts.length > 0 && !contact) {
|
||||
return decision("ambiguous", "ambiguous_identity", candidates);
|
||||
}
|
||||
if (!contact && leads.length > 1) {
|
||||
return decision("ambiguous", "ambiguous_identity", candidates);
|
||||
}
|
||||
|
||||
const identity = contact ?? leads[0] ?? null;
|
||||
if (!identity) {
|
||||
return decision("unmatched", "no_candidate", candidates);
|
||||
}
|
||||
|
||||
const subjectDealId = input.message.subject?.match(DEAL_REFERENCE)?.[1] ?? null;
|
||||
const openDealIds = [...new Set(identity.openDealIds ?? [])].sort();
|
||||
if (subjectDealId) {
|
||||
if (!openDealIds.includes(subjectDealId)) {
|
||||
return decision("ambiguous", "ambiguous_deal", candidates, identity);
|
||||
}
|
||||
return decision("matched", "subject_deal", candidates, identity, subjectDealId);
|
||||
}
|
||||
if (openDealIds.length > 1) {
|
||||
return decision("ambiguous", "ambiguous_deal", candidates, identity);
|
||||
}
|
||||
|
||||
return decision(
|
||||
"matched",
|
||||
openDealIds.length === 1
|
||||
? "single_open_deal"
|
||||
: identity.kind === "contact"
|
||||
? "exact_contact"
|
||||
: "exact_lead",
|
||||
candidates,
|
||||
identity,
|
||||
openDealIds[0] ?? null
|
||||
);
|
||||
}
|
||||
|
||||
export function adminEmailCounterpartAddress(
|
||||
message: Pick<MappedEmailMessage, "direction" | "from" | "to">,
|
||||
mailboxAddresses: readonly string[]
|
||||
): string | null {
|
||||
const own = new Set(mailboxAddresses.map(normalizeEmail));
|
||||
if (message.direction === "inbound") {
|
||||
const address = normalizeEmail(message.from.address);
|
||||
return address && !own.has(address) ? address : null;
|
||||
}
|
||||
return (
|
||||
message.to
|
||||
.map((recipient) => normalizeEmail(recipient.address))
|
||||
.find((address) => address.length > 0 && !own.has(address)) ?? null
|
||||
);
|
||||
}
|
||||
|
||||
export function providerMessageKey(input: {
|
||||
readonly mailboxId: string;
|
||||
readonly providerMessageId: string;
|
||||
}): string {
|
||||
const mailboxId = requiredToken(input.mailboxId, "mailboxId");
|
||||
const providerMessageId = requiredToken(
|
||||
input.providerMessageId,
|
||||
"providerMessageId"
|
||||
);
|
||||
return `${mailboxId}:${providerMessageId}`;
|
||||
}
|
||||
|
||||
export function advanceAdminMailboxCursor(input: {
|
||||
readonly current: AdminMailboxCursorState;
|
||||
readonly nextCursor: string | null;
|
||||
readonly outcome: "success" | "retryable_failure" | "cursor_expired";
|
||||
readonly errorMessageKey?: string | null;
|
||||
}): AdminMailboxCursorState {
|
||||
if (input.outcome === "cursor_expired") {
|
||||
return Object.freeze({
|
||||
cursorToken: null,
|
||||
status: "pending",
|
||||
recoveryGeneration: input.current.recoveryGeneration + 1,
|
||||
lastErrorMessageKey: "admin.sales.email.sync.cursorExpired",
|
||||
});
|
||||
}
|
||||
if (input.outcome === "retryable_failure") {
|
||||
return Object.freeze({
|
||||
...input.current,
|
||||
status: "failed",
|
||||
lastErrorMessageKey:
|
||||
input.errorMessageKey ?? "admin.sales.email.sync.retryableFailure",
|
||||
});
|
||||
}
|
||||
const nextCursor = requiredToken(input.nextCursor ?? "", "nextCursor");
|
||||
return Object.freeze({
|
||||
cursorToken: nextCursor,
|
||||
status: "complete",
|
||||
recoveryGeneration: input.current.recoveryGeneration,
|
||||
lastErrorMessageKey: null,
|
||||
});
|
||||
}
|
||||
|
||||
export type AdminEmailSyncRepository = {
|
||||
persistBatch(input: {
|
||||
readonly adminUserId: string;
|
||||
readonly mailboxId: string;
|
||||
readonly externalFolderId: string;
|
||||
readonly expectedCursor: string | null;
|
||||
readonly nextCursor: string;
|
||||
readonly messages: ReadonlyArray<{
|
||||
readonly key: string;
|
||||
readonly message: MappedEmailMessage;
|
||||
readonly match: AdminEmailMatchDecision;
|
||||
readonly attachments: readonly AdminPreparedEmailAttachment[];
|
||||
}>;
|
||||
}): Promise<{
|
||||
readonly upserted: number;
|
||||
readonly replayed: number;
|
||||
readonly messages?: readonly {
|
||||
readonly providerMessageId: string;
|
||||
readonly messageId: string;
|
||||
readonly dealId: string | null;
|
||||
}[];
|
||||
}>;
|
||||
};
|
||||
|
||||
export type AdminPreparedEmailAttachment = {
|
||||
readonly providerAttachmentId: string;
|
||||
readonly filename: string;
|
||||
readonly mimeType: string | null;
|
||||
readonly sizeBytes: number;
|
||||
readonly storageBucket: string;
|
||||
readonly storageKey: string;
|
||||
readonly checksumSha256: string;
|
||||
readonly scannedAt: Date;
|
||||
};
|
||||
|
||||
export function createAdminEmailSyncService(repository: AdminEmailSyncRepository) {
|
||||
return {
|
||||
async persistProviderBatch(input: {
|
||||
readonly adminUserId: string;
|
||||
readonly mailboxId: string;
|
||||
readonly mailboxAddresses: readonly string[];
|
||||
readonly externalFolderId: string;
|
||||
readonly expectedCursor: string | null;
|
||||
readonly nextCursor: string;
|
||||
readonly messages: readonly MappedEmailMessage[];
|
||||
readonly candidatesFor: (
|
||||
counterpartAddress: string | null
|
||||
) => Promise<readonly AdminEmailMatchCandidate[]>;
|
||||
readonly attachmentsFor?: (
|
||||
message: MappedEmailMessage
|
||||
) => Promise<readonly AdminPreparedEmailAttachment[]>;
|
||||
}) {
|
||||
const messages = [];
|
||||
for (const message of input.messages) {
|
||||
const counterpart = adminEmailCounterpartAddress(
|
||||
message,
|
||||
input.mailboxAddresses
|
||||
);
|
||||
const candidates = await input.candidatesFor(counterpart);
|
||||
messages.push({
|
||||
key: providerMessageKey({
|
||||
mailboxId: input.mailboxId,
|
||||
providerMessageId: message.providerMessageId,
|
||||
}),
|
||||
message,
|
||||
match: decideAdminEmailMatch({
|
||||
message,
|
||||
mailboxAddresses: input.mailboxAddresses,
|
||||
candidates,
|
||||
}),
|
||||
attachments: input.attachmentsFor
|
||||
? await input.attachmentsFor(message)
|
||||
: [],
|
||||
});
|
||||
}
|
||||
return repository.persistBatch({
|
||||
adminUserId: requiredToken(input.adminUserId, "adminUserId"),
|
||||
mailboxId: requiredToken(input.mailboxId, "mailboxId"),
|
||||
externalFolderId: requiredToken(
|
||||
input.externalFolderId,
|
||||
"externalFolderId"
|
||||
),
|
||||
expectedCursor: input.expectedCursor,
|
||||
nextCursor: requiredToken(input.nextCursor, "nextCursor"),
|
||||
messages,
|
||||
});
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function selectSingleIdentity(
|
||||
candidates: readonly AdminEmailMatchCandidate[]
|
||||
): AdminEmailMatchCandidate | null {
|
||||
if (candidates.length === 1) return candidates[0] ?? null;
|
||||
const primaries = candidates.filter((candidate) => candidate.primary);
|
||||
return primaries.length === 1 ? primaries[0] ?? null : null;
|
||||
}
|
||||
|
||||
function decision(
|
||||
status: AdminEmailMatchDecision["status"],
|
||||
reason: AdminEmailMatchDecision["reason"],
|
||||
candidates: readonly AdminEmailMatchCandidate[],
|
||||
identity: AdminEmailMatchCandidate | null = null,
|
||||
dealId: string | null = null
|
||||
): AdminEmailMatchDecision {
|
||||
return Object.freeze({
|
||||
status,
|
||||
contactId: identity?.kind === "contact" ? identity.id : null,
|
||||
leadId: identity?.kind === "lead" ? identity.id : null,
|
||||
dealId,
|
||||
reason,
|
||||
candidates: Object.freeze([...candidates]),
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeEmail(value: string): string {
|
||||
return value.trim().toLowerCase();
|
||||
}
|
||||
|
||||
function requiredToken(value: string, field: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!normalized || normalized.length > 1_024) {
|
||||
throw new AdminEmailSyncError("invalid_sync_input", field);
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
export class AdminEmailSyncError extends Error {
|
||||
readonly code = "invalid_sync_input";
|
||||
readonly field: string;
|
||||
|
||||
constructor(code: "invalid_sync_input", field: string) {
|
||||
super(code);
|
||||
this.name = "AdminEmailSyncError";
|
||||
this.field = field;
|
||||
}
|
||||
}
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
adminEmailTrackingBaseUrl,
|
||||
createAdminEmailTrackingToken,
|
||||
hashAdminEmailTrackingToken,
|
||||
prepareAdminEmailTracking,
|
||||
verifyAdminEmailTrackingToken,
|
||||
} from "./admin-email-tracking.js";
|
||||
|
||||
const secret = "a".repeat(32);
|
||||
const expiresAt = new Date("2027-01-01T00:00:00.000Z");
|
||||
|
||||
describe("admin email tracking", () => {
|
||||
it("rewrites only safe absolute links and appends a signed open pixel", () => {
|
||||
const result = prepareAdminEmailTracking({
|
||||
html: '<p><a href="https://example.com/a?x=1&y=2">A</a><a href=\'mailto:a@example.com\'>M</a><a href="/local">L</a></p>',
|
||||
scheduledEmailId: "scheduled-1",
|
||||
adminUserId: "admin-1",
|
||||
baseUrl: "https://admin.hivegrid.de",
|
||||
secret,
|
||||
expiresAt,
|
||||
});
|
||||
|
||||
expect(result.links).toHaveLength(1);
|
||||
expect(result.links[0]?.destinationUrl).toBe(
|
||||
"https://example.com/a?x=1&y=2"
|
||||
);
|
||||
expect(result.links[0]?.trackingTokenHash).toMatch(/^[a-f0-9]{64}$/u);
|
||||
expect(result.bodyHtml).toContain(
|
||||
"https://admin.hivegrid.de/e/admin/c/scheduled-1?t="
|
||||
);
|
||||
expect(result.bodyHtml).toContain("mailto:a@example.com");
|
||||
expect(result.bodyHtml).toContain('href="/local"');
|
||||
expect(result.bodyHtml).toContain(
|
||||
"https://admin.hivegrid.de/e/admin/o/scheduled-1.gif?t="
|
||||
);
|
||||
});
|
||||
|
||||
it("binds token kind, scheduled email, expiry, owner and click target", () => {
|
||||
const token = createAdminEmailTrackingToken({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
destinationUrl: "https://example.com/path",
|
||||
expiresAtMs: expiresAt.getTime(),
|
||||
secret,
|
||||
});
|
||||
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token,
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
secret,
|
||||
now: new Date("2026-12-31T00:00:00.000Z"),
|
||||
})
|
||||
).toEqual({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
destinationUrl: "https://example.com/path",
|
||||
expiresAtMs: expiresAt.getTime(),
|
||||
});
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token,
|
||||
scheduledEmailId: "scheduled-2",
|
||||
kind: "click",
|
||||
secret,
|
||||
})
|
||||
).toBeNull();
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token,
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "open",
|
||||
secret,
|
||||
})
|
||||
).toBeNull();
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token,
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
secret,
|
||||
now: expiresAt,
|
||||
})
|
||||
).not.toBeNull();
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token,
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
secret,
|
||||
now: new Date(expiresAt.getTime() + 1),
|
||||
})
|
||||
).toBeNull();
|
||||
expect(hashAdminEmailTrackingToken(token)).toMatch(/^[a-f0-9]{64}$/u);
|
||||
});
|
||||
|
||||
it("rejects tampering, unsafe targets, short secrets and invalid origins", () => {
|
||||
const token = createAdminEmailTrackingToken({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "open",
|
||||
expiresAtMs: expiresAt.getTime(),
|
||||
secret,
|
||||
});
|
||||
expect(
|
||||
verifyAdminEmailTrackingToken({
|
||||
token: `${token}x`,
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "open",
|
||||
secret,
|
||||
})
|
||||
).toBeNull();
|
||||
expect(() =>
|
||||
createAdminEmailTrackingToken({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "click",
|
||||
destinationUrl: "javascript:alert(1)",
|
||||
expiresAtMs: expiresAt.getTime(),
|
||||
secret,
|
||||
})
|
||||
).toThrow("invalid_admin_email_tracking_claims");
|
||||
expect(() =>
|
||||
createAdminEmailTrackingToken({
|
||||
adminUserId: "admin-1",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
kind: "open",
|
||||
expiresAtMs: expiresAt.getTime(),
|
||||
secret: "short",
|
||||
})
|
||||
).toThrow("admin_email_tracking_secret_too_short");
|
||||
expect(() =>
|
||||
prepareAdminEmailTracking({
|
||||
html: "<p>Text</p>",
|
||||
scheduledEmailId: "scheduled-1",
|
||||
adminUserId: "admin-1",
|
||||
baseUrl: "https://user:pass@example.com",
|
||||
secret,
|
||||
expiresAt,
|
||||
})
|
||||
).toThrow("invalid_admin_email_tracking_base_url");
|
||||
});
|
||||
|
||||
it("uses HTTP only for local admin hosts", () => {
|
||||
expect(adminEmailTrackingBaseUrl("admin.localhost:3000")).toBe(
|
||||
"http://admin.localhost:3000"
|
||||
);
|
||||
expect(adminEmailTrackingBaseUrl("admin.hivegrid.de")).toBe(
|
||||
"https://admin.hivegrid.de"
|
||||
);
|
||||
});
|
||||
});
|
||||
+209
@@ -0,0 +1,209 @@
|
||||
import { createHash, createHmac, timingSafeEqual } from "node:crypto";
|
||||
|
||||
const TOKEN_VERSION = "a1";
|
||||
const MIN_SECRET_LENGTH = 32;
|
||||
|
||||
export type AdminEmailTrackingKind = "open" | "click";
|
||||
|
||||
export type AdminEmailTrackingClaims = {
|
||||
readonly adminUserId: string;
|
||||
readonly scheduledEmailId: string;
|
||||
readonly kind: AdminEmailTrackingKind;
|
||||
readonly expiresAtMs: number;
|
||||
readonly destinationUrl?: string;
|
||||
};
|
||||
|
||||
export type AdminEmailTrackingLink = {
|
||||
readonly destinationUrl: string;
|
||||
readonly trackingTokenHash: string;
|
||||
};
|
||||
|
||||
export type PreparedAdminEmailTracking = {
|
||||
readonly bodyHtml: string;
|
||||
readonly links: readonly AdminEmailTrackingLink[];
|
||||
};
|
||||
|
||||
export function prepareAdminEmailTracking(input: {
|
||||
readonly html: string;
|
||||
readonly scheduledEmailId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly baseUrl: string;
|
||||
readonly secret: string;
|
||||
readonly expiresAt: Date;
|
||||
}): PreparedAdminEmailTracking {
|
||||
const baseUrl = normalizeBaseUrl(input.baseUrl);
|
||||
const links: AdminEmailTrackingLink[] = [];
|
||||
const bodyHtml = input.html.replace(
|
||||
/(<a\b[^>]*\bhref\s*=\s*)(["'])([^"']+)\2/giu,
|
||||
(match, prefix: string, quote: string, rawTarget: string) => {
|
||||
const destinationUrl = safeHttpUrl(decodeHtmlAmpersands(rawTarget));
|
||||
if (!destinationUrl) return match;
|
||||
const token = createAdminEmailTrackingToken({
|
||||
adminUserId: input.adminUserId,
|
||||
scheduledEmailId: input.scheduledEmailId,
|
||||
kind: "click",
|
||||
destinationUrl,
|
||||
expiresAtMs: input.expiresAt.getTime(),
|
||||
secret: input.secret,
|
||||
});
|
||||
links.push({
|
||||
destinationUrl,
|
||||
trackingTokenHash: hashAdminEmailTrackingToken(token),
|
||||
});
|
||||
const tracked = `${baseUrl}/e/admin/c/${encodeURIComponent(input.scheduledEmailId)}?t=${encodeURIComponent(token)}`;
|
||||
return `${prefix}${quote}${escapeHtmlAttribute(tracked)}${quote}`;
|
||||
}
|
||||
);
|
||||
const openToken = createAdminEmailTrackingToken({
|
||||
adminUserId: input.adminUserId,
|
||||
scheduledEmailId: input.scheduledEmailId,
|
||||
kind: "open",
|
||||
expiresAtMs: input.expiresAt.getTime(),
|
||||
secret: input.secret,
|
||||
});
|
||||
const pixelUrl = `${baseUrl}/e/admin/o/${encodeURIComponent(input.scheduledEmailId)}.gif?t=${encodeURIComponent(openToken)}`;
|
||||
return {
|
||||
bodyHtml: `${bodyHtml}<img src="${escapeHtmlAttribute(pixelUrl)}" width="1" height="1" alt="" aria-hidden="true" style="display:none;width:1px;height:1px" />`,
|
||||
links,
|
||||
};
|
||||
}
|
||||
|
||||
export function createAdminEmailTrackingToken(
|
||||
input: AdminEmailTrackingClaims & { readonly secret: string }
|
||||
): string {
|
||||
validateSecret(input.secret);
|
||||
if (
|
||||
!input.adminUserId.trim() ||
|
||||
!input.scheduledEmailId.trim() ||
|
||||
!Number.isSafeInteger(input.expiresAtMs) ||
|
||||
input.expiresAtMs <= 0 ||
|
||||
(input.kind === "click" && !safeHttpUrl(input.destinationUrl ?? "")) ||
|
||||
(input.kind === "open" && input.destinationUrl !== undefined)
|
||||
) {
|
||||
throw new Error("invalid_admin_email_tracking_claims");
|
||||
}
|
||||
const payload = Buffer.from(
|
||||
JSON.stringify({
|
||||
a: input.adminUserId,
|
||||
s: input.scheduledEmailId,
|
||||
k: input.kind,
|
||||
e: input.expiresAtMs,
|
||||
...(input.destinationUrl ? { u: input.destinationUrl } : {}),
|
||||
}),
|
||||
"utf8"
|
||||
).toString("base64url");
|
||||
const value = `${TOKEN_VERSION}.${payload}`;
|
||||
return `${value}.${sign(value, input.secret)}`;
|
||||
}
|
||||
|
||||
export function verifyAdminEmailTrackingToken(input: {
|
||||
readonly token: string | null | undefined;
|
||||
readonly scheduledEmailId: string;
|
||||
readonly kind: AdminEmailTrackingKind;
|
||||
readonly secret: string;
|
||||
readonly now?: Date;
|
||||
}): AdminEmailTrackingClaims | null {
|
||||
try {
|
||||
validateSecret(input.secret);
|
||||
const parts = input.token?.split(".");
|
||||
if (!parts || parts.length !== 3 || parts[0] !== TOKEN_VERSION) return null;
|
||||
const value = `${parts[0]}.${parts[1]}`;
|
||||
const expected = Buffer.from(sign(value, input.secret), "base64url");
|
||||
const actual = Buffer.from(parts[2] ?? "", "base64url");
|
||||
if (
|
||||
expected.byteLength !== actual.byteLength ||
|
||||
!timingSafeEqual(expected, actual)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
const parsed = JSON.parse(
|
||||
Buffer.from(parts[1] ?? "", "base64url").toString("utf8")
|
||||
) as Record<string, unknown>;
|
||||
const claims: AdminEmailTrackingClaims = {
|
||||
adminUserId: typeof parsed.a === "string" ? parsed.a : "",
|
||||
scheduledEmailId: typeof parsed.s === "string" ? parsed.s : "",
|
||||
kind: parsed.k === "open" ? "open" : "click",
|
||||
expiresAtMs: typeof parsed.e === "number" ? parsed.e : 0,
|
||||
...(typeof parsed.u === "string" ? { destinationUrl: parsed.u } : {}),
|
||||
};
|
||||
if (
|
||||
!claims.adminUserId ||
|
||||
claims.scheduledEmailId !== input.scheduledEmailId ||
|
||||
claims.kind !== input.kind ||
|
||||
!Number.isSafeInteger(claims.expiresAtMs) ||
|
||||
claims.expiresAtMs < (input.now ?? new Date()).getTime() ||
|
||||
(claims.kind === "click" &&
|
||||
!safeHttpUrl(claims.destinationUrl ?? "")) ||
|
||||
(claims.kind === "open" && claims.destinationUrl !== undefined)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
return claims;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function hashAdminEmailTrackingToken(token: string): string {
|
||||
return createHash("sha256").update(token).digest("hex");
|
||||
}
|
||||
|
||||
export function adminEmailTrackingBaseUrl(host: string): string {
|
||||
const normalized = host.trim().replace(/\/+$/u, "");
|
||||
if (/^https?:\/\//iu.test(normalized)) return normalizeBaseUrl(normalized);
|
||||
const isLocal =
|
||||
normalized === "localhost" ||
|
||||
normalized.startsWith("localhost:") ||
|
||||
normalized.endsWith(".localhost") ||
|
||||
normalized.includes(".localhost:");
|
||||
return normalizeBaseUrl(`${isLocal ? "http" : "https"}://${normalized}`);
|
||||
}
|
||||
|
||||
function sign(value: string, secret: string): string {
|
||||
return createHmac("sha256", secret).update(value).digest("base64url");
|
||||
}
|
||||
|
||||
function validateSecret(secret: string): void {
|
||||
if (Buffer.byteLength(secret, "utf8") < MIN_SECRET_LENGTH) {
|
||||
throw new Error("admin_email_tracking_secret_too_short");
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeBaseUrl(value: string): string {
|
||||
const parsed = new URL(value);
|
||||
if (
|
||||
!["http:", "https:"].includes(parsed.protocol) ||
|
||||
parsed.username ||
|
||||
parsed.password ||
|
||||
parsed.pathname !== "/" ||
|
||||
parsed.search ||
|
||||
parsed.hash
|
||||
) {
|
||||
throw new Error("invalid_admin_email_tracking_base_url");
|
||||
}
|
||||
return parsed.origin;
|
||||
}
|
||||
|
||||
function safeHttpUrl(value: string): string | null {
|
||||
try {
|
||||
const parsed = new URL(value);
|
||||
if (
|
||||
!["http:", "https:"].includes(parsed.protocol) ||
|
||||
parsed.username ||
|
||||
parsed.password
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
return parsed.toString();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function decodeHtmlAmpersands(value: string): string {
|
||||
return value.replace(/&/giu, "&");
|
||||
}
|
||||
|
||||
function escapeHtmlAttribute(value: string): string {
|
||||
return value.replace(/&/gu, "&").replace(/"/gu, """);
|
||||
}
|
||||
+506
@@ -0,0 +1,506 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
deliverDueAdminEmails,
|
||||
pollStaleAdminMailboxes,
|
||||
refreshDueAdminMailConnections,
|
||||
syncClaimedAdminMailboxes,
|
||||
} from "./admin-email-worker-tasks.server.js";
|
||||
|
||||
describe("admin email worker tasks", () => {
|
||||
it("polls stale mailboxes independently and reports retry candidates", async () => {
|
||||
const client = {
|
||||
adminMailbox: {
|
||||
findMany: vi.fn().mockResolvedValue([
|
||||
{
|
||||
id: "mailbox-1",
|
||||
adminUserId: "admin-1",
|
||||
connectionId: "connection-1",
|
||||
lastSyncAt: null,
|
||||
},
|
||||
{
|
||||
id: "mailbox-2",
|
||||
adminUserId: "admin-2",
|
||||
connectionId: "connection-2",
|
||||
lastSyncAt: new Date("2026-07-24T01:00:00.000Z"),
|
||||
},
|
||||
]),
|
||||
},
|
||||
};
|
||||
const syncMailbox = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(undefined)
|
||||
.mockRejectedValueOnce(new Error("provider unavailable"));
|
||||
|
||||
await expect(
|
||||
pollStaleAdminMailboxes(client as never, {
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
syncMailbox,
|
||||
})
|
||||
).resolves.toEqual({
|
||||
inspected: 2,
|
||||
polled: 1,
|
||||
failed: ["mailbox-2"],
|
||||
});
|
||||
});
|
||||
|
||||
it("returns an empty refresh result without opening credentials", async () => {
|
||||
const client = {
|
||||
adminDataConnection: { findMany: vi.fn().mockResolvedValue([]) },
|
||||
};
|
||||
await expect(
|
||||
refreshDueAdminMailConnections(client as never, {
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
})
|
||||
).resolves.toEqual({ inspected: 0, refreshed: 0, failed: [] });
|
||||
});
|
||||
|
||||
it("delivers each atomic claim once and completes the local thread projection", async () => {
|
||||
const email = {
|
||||
id: "scheduled-1",
|
||||
adminUserId: "admin-1",
|
||||
connectionId: "connection-1",
|
||||
provider: "google_mail" as const,
|
||||
mailboxId: "mailbox-1",
|
||||
fromAddress: "sales@hivegrid.de",
|
||||
fromName: "Sales",
|
||||
contactId: "contact-1",
|
||||
leadId: null,
|
||||
dealId: "deal-1",
|
||||
threadId: null,
|
||||
bulkRunId: null,
|
||||
providerThreadId: null,
|
||||
toAddresses: ["buyer@example.com"],
|
||||
ccAddresses: [],
|
||||
bccAddresses: [],
|
||||
subject: "Demo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
bodyText: "Hallo",
|
||||
idempotencyKey: "send-1",
|
||||
noReplyAfterDays: null,
|
||||
trackingEnabled: false,
|
||||
liveOpenEnabled: false,
|
||||
trackingRetentionDays: 180,
|
||||
};
|
||||
const complete = vi.fn(async () => ({ messageId: "message-1" }));
|
||||
const fail = vi.fn(async () => true);
|
||||
const gateway = {
|
||||
send: vi.fn(async () => ({
|
||||
providerMessageId: "gmail-message-1",
|
||||
providerThreadId: "gmail-thread-1",
|
||||
})),
|
||||
};
|
||||
|
||||
await expect(
|
||||
deliverDueAdminEmails({} as never, {
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
claim: vi.fn(async () => ({
|
||||
inspected: 1,
|
||||
claimed: [email],
|
||||
blocked: 0,
|
||||
deferred: 0,
|
||||
recoveredUnknown: 0,
|
||||
})),
|
||||
complete,
|
||||
fail,
|
||||
fireNoReplyReminders: vi
|
||||
.fn()
|
||||
.mockResolvedValue({ scanned: 2, created: 1 }),
|
||||
gateway: gateway as never,
|
||||
withCredentials: async (_connectionId, _adminUserId, task) =>
|
||||
task({
|
||||
accessToken: "access-token",
|
||||
refreshToken: "refresh-token",
|
||||
expiresAt: "2026-07-24T11:00:00.000Z",
|
||||
scopes: ["mail.send"],
|
||||
}),
|
||||
})
|
||||
).resolves.toEqual({
|
||||
inspected: 1,
|
||||
claimed: 1,
|
||||
sent: 1,
|
||||
failed: [],
|
||||
blocked: 0,
|
||||
deferred: 0,
|
||||
recoveredUnknown: 0,
|
||||
noReplyReminders: { scanned: 2, created: 1 },
|
||||
});
|
||||
expect(gateway.send).toHaveBeenCalledOnce();
|
||||
expect(complete).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
expect.objectContaining({
|
||||
email,
|
||||
providerMessageId: "gmail-message-1",
|
||||
providerThreadId: "gmail-thread-1",
|
||||
})
|
||||
);
|
||||
expect(fail).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does not retry an accepted provider outcome when local finalization fails", async () => {
|
||||
const fail = vi.fn(async () => true);
|
||||
const email = {
|
||||
id: "scheduled-1",
|
||||
adminUserId: "admin-1",
|
||||
connectionId: "connection-1",
|
||||
provider: "microsoft_mail" as const,
|
||||
mailboxId: "mailbox-1",
|
||||
fromAddress: "sales@hivegrid.de",
|
||||
fromName: null,
|
||||
contactId: null,
|
||||
leadId: null,
|
||||
dealId: null,
|
||||
threadId: null,
|
||||
bulkRunId: null,
|
||||
providerThreadId: null,
|
||||
toAddresses: ["buyer@example.com"],
|
||||
ccAddresses: [],
|
||||
bccAddresses: [],
|
||||
subject: "Demo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
bodyText: null,
|
||||
idempotencyKey: "send-1",
|
||||
noReplyAfterDays: null,
|
||||
trackingEnabled: false,
|
||||
liveOpenEnabled: false,
|
||||
trackingRetentionDays: 180,
|
||||
};
|
||||
await deliverDueAdminEmails({} as never, {
|
||||
claim: vi.fn(async () => ({
|
||||
inspected: 1,
|
||||
claimed: [email],
|
||||
blocked: 0,
|
||||
deferred: 0,
|
||||
recoveredUnknown: 0,
|
||||
})),
|
||||
complete: vi.fn(async () => {
|
||||
throw new Error("database unavailable");
|
||||
}),
|
||||
fail,
|
||||
fireNoReplyReminders: vi
|
||||
.fn()
|
||||
.mockResolvedValue({ scanned: 0, created: 0 }),
|
||||
gateway: {
|
||||
send: vi.fn(async () => ({
|
||||
providerMessageId: null,
|
||||
providerThreadId: null,
|
||||
})),
|
||||
} as never,
|
||||
withCredentials: async (_connectionId, _adminUserId, task) =>
|
||||
task({
|
||||
accessToken: "access-token",
|
||||
refreshToken: "refresh-token",
|
||||
expiresAt: "2026-07-24T11:00:00.000Z",
|
||||
scopes: ["Mail.Send"],
|
||||
}),
|
||||
});
|
||||
|
||||
expect(fail).toHaveBeenCalledWith(expect.anything(), {
|
||||
id: "scheduled-1",
|
||||
errorMessageKey: "admin.sales.email.delivery.errors.providerOutcomeUnknown",
|
||||
});
|
||||
});
|
||||
|
||||
it("rewrites opted-in links before provider delivery and persists their hashes", async () => {
|
||||
const email = {
|
||||
id: "scheduled-tracked",
|
||||
adminUserId: "admin-1",
|
||||
connectionId: "connection-1",
|
||||
provider: "google_mail" as const,
|
||||
mailboxId: "mailbox-1",
|
||||
fromAddress: "sales@hivegrid.de",
|
||||
fromName: "Sales",
|
||||
contactId: "contact-1",
|
||||
leadId: null,
|
||||
dealId: "deal-1",
|
||||
threadId: null,
|
||||
bulkRunId: null,
|
||||
providerThreadId: null,
|
||||
toAddresses: ["buyer@example.com"],
|
||||
ccAddresses: [],
|
||||
bccAddresses: [],
|
||||
subject: "Demo",
|
||||
bodyHtml: '<p><a href="https://example.com/demo">Demo</a></p>',
|
||||
bodyText: "Demo",
|
||||
idempotencyKey: "send-tracked",
|
||||
noReplyAfterDays: null,
|
||||
trackingEnabled: true,
|
||||
liveOpenEnabled: true,
|
||||
trackingRetentionDays: 180,
|
||||
};
|
||||
const complete = vi.fn(async () => ({ messageId: "message-1" }));
|
||||
const gateway = {
|
||||
send: vi.fn(async () => ({
|
||||
providerMessageId: "gmail-message-1",
|
||||
providerThreadId: "gmail-thread-1",
|
||||
})),
|
||||
};
|
||||
await deliverDueAdminEmails({} as never, {
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
claim: vi.fn(async () => ({
|
||||
inspected: 1,
|
||||
claimed: [email],
|
||||
blocked: 0,
|
||||
deferred: 0,
|
||||
recoveredUnknown: 0,
|
||||
})),
|
||||
complete,
|
||||
fail: vi.fn(async () => true),
|
||||
fireNoReplyReminders: vi
|
||||
.fn()
|
||||
.mockResolvedValue({ scanned: 0, created: 0 }),
|
||||
gateway: gateway as never,
|
||||
tracking: {
|
||||
host: "admin.hivegrid.de",
|
||||
secret: "tracking-secret".padEnd(40, "x"),
|
||||
},
|
||||
withCredentials: async (_connectionId, _adminUserId, task) =>
|
||||
task({
|
||||
accessToken: "access-token",
|
||||
refreshToken: "refresh-token",
|
||||
expiresAt: "2026-07-24T11:00:00.000Z",
|
||||
scopes: ["mail.send"],
|
||||
}),
|
||||
});
|
||||
|
||||
expect(gateway.send).toHaveBeenCalledWith(
|
||||
"google_mail",
|
||||
expect.anything(),
|
||||
expect.objectContaining({
|
||||
bodyHtml: expect.stringContaining(
|
||||
"https://admin.hivegrid.de/e/admin/c/scheduled-tracked?t="
|
||||
),
|
||||
})
|
||||
);
|
||||
expect(complete).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
expect.objectContaining({
|
||||
deliveredBodyHtml: expect.stringContaining(
|
||||
"/e/admin/o/scheduled-tracked.gif?t="
|
||||
),
|
||||
trackingLinks: [
|
||||
expect.objectContaining({
|
||||
destinationUrl: "https://example.com/demo",
|
||||
trackingTokenHash: expect.stringMatching(/^[a-f0-9]{64}$/u),
|
||||
}),
|
||||
],
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("hydrates and persists a claimed provider cursor through deterministic matching", async () => {
|
||||
const persistBatch = vi.fn(async () => ({
|
||||
upserted: 1,
|
||||
replayed: 0,
|
||||
messages: [],
|
||||
}));
|
||||
const candidates = vi.fn(async () => [
|
||||
{
|
||||
id: "contact-1",
|
||||
kind: "contact" as const,
|
||||
primary: true,
|
||||
openDealIds: ["deal-1"],
|
||||
},
|
||||
]);
|
||||
const message = {
|
||||
providerMessageId: "provider-1",
|
||||
providerThreadId: "thread-1",
|
||||
internetMessageId: "internet-1",
|
||||
direction: "inbound" as const,
|
||||
from: { address: "buyer@example.com" },
|
||||
to: [{ address: "sales@hivegrid.de" }],
|
||||
cc: [],
|
||||
bcc: [],
|
||||
subject: "Demo",
|
||||
snippet: "Hallo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
bodyText: "Hallo",
|
||||
sentAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
receivedAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
isRead: false,
|
||||
hasAttachments: true,
|
||||
isNewsletter: false,
|
||||
providerLabels: ["INBOX"],
|
||||
attachments: [
|
||||
{
|
||||
attachmentId: "attachment-1",
|
||||
filename: "angebot.pdf",
|
||||
mimeType: "application/pdf",
|
||||
sizeBytes: 128,
|
||||
},
|
||||
],
|
||||
};
|
||||
const preparedAttachment = {
|
||||
providerAttachmentId: "attachment-1",
|
||||
filename: "angebot.pdf",
|
||||
mimeType: "application/pdf",
|
||||
sizeBytes: 128,
|
||||
storageBucket: "hivegrid-files",
|
||||
storageKey: "admin-email/attachment-1",
|
||||
checksumSha256: "a".repeat(64),
|
||||
scannedAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
};
|
||||
const attachmentProcessor = {
|
||||
prepare: vi.fn(async () => [preparedAttachment]),
|
||||
rollback: vi.fn(async () => undefined),
|
||||
};
|
||||
const result = await syncClaimedAdminMailboxes({} as never, {
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
claim: vi.fn(async () => [
|
||||
{
|
||||
cursorId: "cursor-1",
|
||||
adminUserId: "admin-1",
|
||||
mailboxId: "mailbox-1",
|
||||
mailboxAddress: "sales@hivegrid.de",
|
||||
connectionId: "connection-1",
|
||||
provider: "google_mail" as const,
|
||||
externalFolderId: "*",
|
||||
cursorToken: "history-1",
|
||||
},
|
||||
]),
|
||||
provider: {
|
||||
fetchBatch: vi.fn(async () => ({
|
||||
messages: [message],
|
||||
nextCursor: "history-2",
|
||||
})),
|
||||
},
|
||||
candidates,
|
||||
persistRepository: { persistBatch },
|
||||
attachmentProcessor,
|
||||
fail: vi.fn(),
|
||||
withCredentials: async (_connectionId, _adminUserId, task) =>
|
||||
task({
|
||||
accessToken: "access-token",
|
||||
refreshToken: "refresh-token",
|
||||
expiresAt: "2026-07-24T11:00:00.000Z",
|
||||
scopes: ["mail.read"],
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result).toEqual({
|
||||
inspected: 1,
|
||||
synced: 1,
|
||||
upserted: 1,
|
||||
replayed: 0,
|
||||
failed: [],
|
||||
});
|
||||
expect(candidates).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
"buyer@example.com"
|
||||
);
|
||||
expect(persistBatch).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
expectedCursor: "history-1",
|
||||
nextCursor: "history-2",
|
||||
messages: [
|
||||
expect.objectContaining({
|
||||
match: expect.objectContaining({
|
||||
contactId: "contact-1",
|
||||
dealId: "deal-1",
|
||||
}),
|
||||
attachments: [preparedAttachment],
|
||||
}),
|
||||
],
|
||||
})
|
||||
);
|
||||
expect(attachmentProcessor.rollback).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("removes prepared objects and leaves the cursor retryable if persistence fails", async () => {
|
||||
const preparedAttachment = {
|
||||
providerAttachmentId: "attachment-1",
|
||||
filename: "angebot.pdf",
|
||||
mimeType: "application/pdf",
|
||||
sizeBytes: 1,
|
||||
storageBucket: "hivegrid-files",
|
||||
storageKey: "admin-email/attachment-1",
|
||||
checksumSha256: "b".repeat(64),
|
||||
scannedAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
};
|
||||
const attachmentProcessor = {
|
||||
prepare: vi.fn(async () => [preparedAttachment]),
|
||||
rollback: vi.fn(async () => undefined),
|
||||
};
|
||||
const fail = vi.fn(async () => undefined);
|
||||
|
||||
await expect(
|
||||
syncClaimedAdminMailboxes({} as never, {
|
||||
claim: vi.fn(async () => [
|
||||
{
|
||||
cursorId: "cursor-1",
|
||||
adminUserId: "admin-1",
|
||||
mailboxId: "mailbox-1",
|
||||
mailboxAddress: "sales@hivegrid.de",
|
||||
connectionId: "connection-1",
|
||||
provider: "google_mail" as const,
|
||||
externalFolderId: "*",
|
||||
cursorToken: "history-1",
|
||||
},
|
||||
]),
|
||||
provider: {
|
||||
fetchBatch: vi.fn(async () => ({
|
||||
messages: [
|
||||
{
|
||||
providerMessageId: "provider-1",
|
||||
providerThreadId: "thread-1",
|
||||
internetMessageId: null,
|
||||
direction: "inbound" as const,
|
||||
from: { address: "buyer@example.com" },
|
||||
to: [{ address: "sales@hivegrid.de" }],
|
||||
cc: [],
|
||||
bcc: [],
|
||||
subject: "Angebot",
|
||||
snippet: null,
|
||||
bodyHtml: null,
|
||||
bodyText: null,
|
||||
sentAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
receivedAt: new Date("2026-07-24T10:00:00.000Z"),
|
||||
isRead: false,
|
||||
hasAttachments: true,
|
||||
isNewsletter: false,
|
||||
providerLabels: ["INBOX"],
|
||||
attachments: [
|
||||
{
|
||||
attachmentId: "attachment-1",
|
||||
filename: "angebot.pdf",
|
||||
mimeType: "application/pdf",
|
||||
sizeBytes: 1,
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
nextCursor: "history-2",
|
||||
})),
|
||||
},
|
||||
candidates: vi.fn(async () => []),
|
||||
persistRepository: {
|
||||
persistBatch: vi.fn(async () => {
|
||||
throw new Error("database unavailable");
|
||||
}),
|
||||
},
|
||||
attachmentProcessor,
|
||||
fail,
|
||||
withCredentials: async (_connectionId, _adminUserId, task) =>
|
||||
task({
|
||||
accessToken: "access-token",
|
||||
refreshToken: "refresh-token",
|
||||
expiresAt: "2026-07-24T11:00:00.000Z",
|
||||
scopes: ["mail.read"],
|
||||
}),
|
||||
})
|
||||
).resolves.toEqual({
|
||||
inspected: 1,
|
||||
synced: 0,
|
||||
upserted: 0,
|
||||
replayed: 0,
|
||||
failed: ["cursor-1"],
|
||||
});
|
||||
expect(attachmentProcessor.rollback).toHaveBeenCalledWith([
|
||||
preparedAttachment,
|
||||
]);
|
||||
expect(fail).toHaveBeenCalledWith(expect.anything(), {
|
||||
cursorId: "cursor-1",
|
||||
fullResyncRequired: false,
|
||||
errorMessageKey: "admin.sales.email.sync.retryableFailure",
|
||||
});
|
||||
});
|
||||
});
|
||||
+494
@@ -0,0 +1,494 @@
|
||||
import {
|
||||
createAdminConnectionsService,
|
||||
createPrismaAdminConnectionsRepository,
|
||||
} from "@hivegrid/db/admin-connections.server";
|
||||
import {
|
||||
claimDueAdminEmails,
|
||||
completeAdminEmailDelivery,
|
||||
failAdminEmailDelivery,
|
||||
fireDueAdminNoReplyReminders,
|
||||
type ClaimedAdminEmail,
|
||||
} from "@hivegrid/db/admin-email-delivery.server";
|
||||
import {
|
||||
claimAdminEmailSyncTargets,
|
||||
createPrismaAdminEmailSyncRepository,
|
||||
failAdminEmailSyncTarget,
|
||||
findAdminEmailMatchCandidates,
|
||||
} from "@hivegrid/db/admin-email-sync.server";
|
||||
import type { AdminMailConnectionProvider } from "./admin-connections.js";
|
||||
import { createAdminMailProviderGateway } from "./admin-mail-provider.server.js";
|
||||
import { createAdminMailSyncProvider } from "./admin-mail-sync-provider.server.js";
|
||||
import {
|
||||
createAdminEmailAttachmentProcessor,
|
||||
type AdminEmailAttachmentProcessor,
|
||||
} from "./admin-email-attachments.server.js";
|
||||
import {
|
||||
createAdminEmailSyncService,
|
||||
type AdminEmailSyncRepository,
|
||||
type AdminPreparedEmailAttachment,
|
||||
} from "./admin-email-sync.server.js";
|
||||
import {
|
||||
adminEmailTrackingBaseUrl,
|
||||
prepareAdminEmailTracking,
|
||||
type PreparedAdminEmailTracking,
|
||||
} from "./admin-email-tracking.js";
|
||||
|
||||
const DEFAULT_REFRESH_WINDOW_MS = 5 * 60 * 1_000;
|
||||
const DEFAULT_STALE_AFTER_MS = 4 * 60 * 60 * 1_000;
|
||||
|
||||
type DueConnection = {
|
||||
readonly id: string;
|
||||
readonly adminUserId: string;
|
||||
readonly provider: AdminMailConnectionProvider;
|
||||
};
|
||||
|
||||
type StaleMailbox = {
|
||||
readonly id: string;
|
||||
readonly adminUserId: string;
|
||||
readonly connectionId: string;
|
||||
readonly lastSyncAt: Date | null;
|
||||
};
|
||||
|
||||
export type AdminEmailWorkerClient = {
|
||||
readonly $transaction: (
|
||||
callback: (tx: unknown) => Promise<unknown>
|
||||
) => Promise<unknown>;
|
||||
readonly adminDataConnection: {
|
||||
findMany(input: Record<string, unknown>): Promise<DueConnection[]>;
|
||||
};
|
||||
readonly adminMailbox: {
|
||||
findMany(input: Record<string, unknown>): Promise<StaleMailbox[]>;
|
||||
};
|
||||
};
|
||||
|
||||
export type AdminEmailCredentialRunner = <T>(
|
||||
connectionId: string,
|
||||
adminUserId: string,
|
||||
task: (credentials: Readonly<Record<string, unknown>>) => Promise<T>
|
||||
) => Promise<T>;
|
||||
|
||||
export async function refreshDueAdminMailConnections(
|
||||
client: AdminEmailWorkerClient,
|
||||
options: {
|
||||
readonly now?: Date;
|
||||
readonly windowMs?: number;
|
||||
readonly take?: number;
|
||||
readonly gateway?: ReturnType<typeof createAdminMailProviderGateway>;
|
||||
} = {}
|
||||
) {
|
||||
const now = options.now ?? new Date();
|
||||
const gateway = options.gateway ?? createAdminMailProviderGateway();
|
||||
const rows = await client.adminDataConnection.findMany({
|
||||
where: {
|
||||
capability: "email",
|
||||
provider: { in: ["google_mail", "microsoft_mail"] },
|
||||
status: "active",
|
||||
archivedAt: null,
|
||||
tokenExpiresAt: {
|
||||
lte: new Date(
|
||||
now.getTime() + (options.windowMs ?? DEFAULT_REFRESH_WINDOW_MS)
|
||||
),
|
||||
},
|
||||
},
|
||||
orderBy: [{ tokenExpiresAt: "asc" }, { id: "asc" }],
|
||||
take: options.take ?? 50,
|
||||
select: { id: true, adminUserId: true, provider: true },
|
||||
});
|
||||
const service = createAdminConnectionsService({
|
||||
repository: createPrismaAdminConnectionsRepository(client as never),
|
||||
authorize: () => undefined,
|
||||
});
|
||||
let refreshed = 0;
|
||||
const failed: string[] = [];
|
||||
for (const row of rows) {
|
||||
try {
|
||||
await service.withCredentials(
|
||||
row.id,
|
||||
row.adminUserId,
|
||||
async (raw) => {
|
||||
const current = workerCredentialBundle(raw);
|
||||
const next = await gateway.refresh(row.provider, current);
|
||||
await service.refresh({
|
||||
connectionId: row.id,
|
||||
adminUserId: row.adminUserId,
|
||||
credentials: next,
|
||||
scopes: next.scopes,
|
||||
tokenExpiresAt: new Date(next.expiresAt),
|
||||
actor: {
|
||||
adminUserId: row.adminUserId,
|
||||
email: "system@worker.invalid",
|
||||
reason: "Automatische OAuth-Token-Erneuerung",
|
||||
},
|
||||
});
|
||||
}
|
||||
);
|
||||
refreshed += 1;
|
||||
} catch {
|
||||
failed.push(row.id);
|
||||
}
|
||||
}
|
||||
return { inspected: rows.length, refreshed, failed };
|
||||
}
|
||||
|
||||
export async function pollStaleAdminMailboxes(
|
||||
client: AdminEmailWorkerClient,
|
||||
input: {
|
||||
readonly syncMailbox: (mailbox: StaleMailbox) => Promise<void>;
|
||||
readonly now?: Date;
|
||||
readonly staleAfterMs?: number;
|
||||
readonly take?: number;
|
||||
}
|
||||
) {
|
||||
const now = input.now ?? new Date();
|
||||
const rows = await client.adminMailbox.findMany({
|
||||
where: {
|
||||
status: { in: ["active", "degraded"] },
|
||||
archivedAt: null,
|
||||
OR: [
|
||||
{ lastSyncAt: null },
|
||||
{
|
||||
lastSyncAt: {
|
||||
lte: new Date(
|
||||
now.getTime() -
|
||||
(input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS)
|
||||
),
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
orderBy: [{ lastSyncAt: "asc" }, { id: "asc" }],
|
||||
take: input.take ?? 25,
|
||||
select: {
|
||||
id: true,
|
||||
adminUserId: true,
|
||||
connectionId: true,
|
||||
lastSyncAt: true,
|
||||
},
|
||||
});
|
||||
const failed: string[] = [];
|
||||
let polled = 0;
|
||||
for (const row of rows) {
|
||||
try {
|
||||
await input.syncMailbox(row);
|
||||
polled += 1;
|
||||
} catch {
|
||||
failed.push(row.id);
|
||||
}
|
||||
}
|
||||
return { inspected: rows.length, polled, failed };
|
||||
}
|
||||
|
||||
export async function syncClaimedAdminMailboxes(
|
||||
client: AdminEmailWorkerClient,
|
||||
options: {
|
||||
readonly now?: Date;
|
||||
readonly take?: number;
|
||||
readonly claim?: typeof claimAdminEmailSyncTargets;
|
||||
readonly provider?: ReturnType<typeof createAdminMailSyncProvider>;
|
||||
readonly candidates?: typeof findAdminEmailMatchCandidates;
|
||||
readonly fail?: typeof failAdminEmailSyncTarget;
|
||||
readonly persistRepository?: ReturnType<
|
||||
typeof createPrismaAdminEmailSyncRepository
|
||||
>;
|
||||
readonly withCredentials?: AdminEmailCredentialRunner;
|
||||
readonly attachmentProcessor?: AdminEmailAttachmentProcessor;
|
||||
} = {}
|
||||
) {
|
||||
const now = options.now ?? new Date();
|
||||
const targets = await (options.claim ?? claimAdminEmailSyncTargets)(
|
||||
client as never,
|
||||
{ now, take: options.take }
|
||||
);
|
||||
const provider = options.provider ?? createAdminMailSyncProvider();
|
||||
const candidates = options.candidates ?? findAdminEmailMatchCandidates;
|
||||
const fail = options.fail ?? failAdminEmailSyncTarget;
|
||||
const repository =
|
||||
options.persistRepository ??
|
||||
createPrismaAdminEmailSyncRepository(client as never);
|
||||
const service = createAdminEmailSyncService(
|
||||
toAdminEmailSyncRepository(repository)
|
||||
);
|
||||
const connections = createAdminConnectionsService({
|
||||
repository: createPrismaAdminConnectionsRepository(client as never),
|
||||
authorize: () => undefined,
|
||||
});
|
||||
const withCredentials: AdminEmailCredentialRunner =
|
||||
options.withCredentials ??
|
||||
((connectionId, adminUserId, task) =>
|
||||
connections.withCredentials(connectionId, adminUserId, task));
|
||||
const attachmentProcessor =
|
||||
options.attachmentProcessor ??
|
||||
createAdminEmailAttachmentProcessor({});
|
||||
let synced = 0;
|
||||
let upserted = 0;
|
||||
let replayed = 0;
|
||||
const failed: string[] = [];
|
||||
|
||||
for (const target of targets) {
|
||||
try {
|
||||
const result = await withCredentials(
|
||||
target.connectionId,
|
||||
target.adminUserId,
|
||||
async (raw) => {
|
||||
const accessToken = workerCredentialBundle(raw).accessToken;
|
||||
const batch = await provider.fetchBatch({
|
||||
provider: target.provider,
|
||||
accessToken,
|
||||
externalFolderId: target.externalFolderId,
|
||||
cursorToken: target.cursorToken,
|
||||
now,
|
||||
});
|
||||
const prepared: AdminPreparedEmailAttachment[] = [];
|
||||
try {
|
||||
return await service.persistProviderBatch({
|
||||
adminUserId: target.adminUserId,
|
||||
mailboxId: target.mailboxId,
|
||||
mailboxAddresses: [target.mailboxAddress],
|
||||
externalFolderId: target.externalFolderId,
|
||||
expectedCursor: target.cursorToken,
|
||||
nextCursor: batch.nextCursor,
|
||||
messages: batch.messages,
|
||||
candidatesFor: (address) =>
|
||||
candidates(client as never, address),
|
||||
attachmentsFor: async (message) => {
|
||||
const attachments = await attachmentProcessor.prepare({
|
||||
adminUserId: target.adminUserId,
|
||||
mailboxId: target.mailboxId,
|
||||
provider: target.provider,
|
||||
accessToken,
|
||||
message,
|
||||
now,
|
||||
});
|
||||
prepared.push(...attachments);
|
||||
return attachments;
|
||||
},
|
||||
});
|
||||
} catch (error) {
|
||||
await attachmentProcessor.rollback(prepared);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
);
|
||||
synced += 1;
|
||||
upserted += result.upserted;
|
||||
replayed += result.replayed;
|
||||
} catch (error) {
|
||||
failed.push(target.cursorId);
|
||||
await fail(client as never, {
|
||||
cursorId: target.cursorId,
|
||||
fullResyncRequired: isFullResyncError(error),
|
||||
errorMessageKey: isFullResyncError(error)
|
||||
? "admin.sales.email.sync.cursorExpired"
|
||||
: "admin.sales.email.sync.retryableFailure",
|
||||
});
|
||||
}
|
||||
}
|
||||
return {
|
||||
inspected: targets.length,
|
||||
synced,
|
||||
upserted,
|
||||
replayed,
|
||||
failed,
|
||||
};
|
||||
}
|
||||
|
||||
function toAdminEmailSyncRepository(
|
||||
repository: ReturnType<typeof createPrismaAdminEmailSyncRepository>
|
||||
): AdminEmailSyncRepository {
|
||||
return {
|
||||
persistBatch: (input) =>
|
||||
repository.persistBatch({
|
||||
adminUserId: input.adminUserId,
|
||||
mailboxId: input.mailboxId,
|
||||
externalFolderId: input.externalFolderId,
|
||||
expectedCursor: input.expectedCursor,
|
||||
nextCursor: input.nextCursor,
|
||||
messages: input.messages.map(({ message, match, attachments }) => ({
|
||||
providerMessageId: message.providerMessageId,
|
||||
providerThreadId: message.providerThreadId,
|
||||
internetMessageId: message.internetMessageId,
|
||||
direction: message.direction,
|
||||
from: message.from,
|
||||
to: message.to,
|
||||
cc: message.cc,
|
||||
bcc: message.bcc,
|
||||
subject: message.subject,
|
||||
snippet: message.snippet,
|
||||
bodyHtml: message.bodyHtml,
|
||||
bodyText: message.bodyText,
|
||||
sentAt: message.sentAt,
|
||||
receivedAt: message.receivedAt,
|
||||
isRead: message.isRead,
|
||||
isNewsletter: message.isNewsletter,
|
||||
providerLabels: message.providerLabels,
|
||||
attachments,
|
||||
match,
|
||||
})),
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
export async function deliverDueAdminEmails(
|
||||
client: AdminEmailWorkerClient,
|
||||
options: {
|
||||
readonly now?: Date;
|
||||
readonly take?: number;
|
||||
readonly gateway?: ReturnType<typeof createAdminMailProviderGateway>;
|
||||
readonly claim?: typeof claimDueAdminEmails;
|
||||
readonly complete?: typeof completeAdminEmailDelivery;
|
||||
readonly fail?: typeof failAdminEmailDelivery;
|
||||
readonly fireNoReplyReminders?: typeof fireDueAdminNoReplyReminders;
|
||||
readonly withCredentials?: AdminEmailCredentialRunner;
|
||||
readonly tracking?: {
|
||||
readonly host: string;
|
||||
readonly secret: string;
|
||||
} | null;
|
||||
} = {}
|
||||
) {
|
||||
const now = options.now ?? new Date();
|
||||
const gateway = options.gateway ?? createAdminMailProviderGateway();
|
||||
const claim = options.claim ?? claimDueAdminEmails;
|
||||
const complete = options.complete ?? completeAdminEmailDelivery;
|
||||
const fail = options.fail ?? failAdminEmailDelivery;
|
||||
const fireNoReplyReminders =
|
||||
options.fireNoReplyReminders ?? fireDueAdminNoReplyReminders;
|
||||
const batch = await claim(client as never, {
|
||||
now,
|
||||
take: options.take,
|
||||
});
|
||||
const connections = createAdminConnectionsService({
|
||||
repository: createPrismaAdminConnectionsRepository(client as never),
|
||||
authorize: () => undefined,
|
||||
});
|
||||
const withCredentials: AdminEmailCredentialRunner =
|
||||
options.withCredentials ??
|
||||
((connectionId, adminUserId, task) =>
|
||||
connections.withCredentials(connectionId, adminUserId, task));
|
||||
let sent = 0;
|
||||
const failed: string[] = [];
|
||||
|
||||
for (const email of batch.claimed) {
|
||||
let providerAccepted = false;
|
||||
try {
|
||||
const tracking = prepareTracking(email, options.tracking, now);
|
||||
const providerResult = await withCredentials(
|
||||
email.connectionId,
|
||||
email.adminUserId,
|
||||
async (raw) => {
|
||||
const result = await gateway.send(
|
||||
email.provider,
|
||||
workerCredentialBundle(raw),
|
||||
providerMessage(email, tracking?.bodyHtml)
|
||||
);
|
||||
providerAccepted = true;
|
||||
return result;
|
||||
}
|
||||
);
|
||||
await complete(client as never, {
|
||||
email,
|
||||
providerMessageId: providerResult.providerMessageId,
|
||||
providerThreadId: providerResult.providerThreadId,
|
||||
sentAt: now,
|
||||
...(tracking
|
||||
? {
|
||||
deliveredBodyHtml: tracking.bodyHtml,
|
||||
trackingLinks: tracking.links,
|
||||
}
|
||||
: {}),
|
||||
});
|
||||
sent += 1;
|
||||
} catch {
|
||||
failed.push(email.id);
|
||||
await fail(client as never, {
|
||||
id: email.id,
|
||||
errorMessageKey: providerAccepted
|
||||
? "admin.sales.email.delivery.errors.providerOutcomeUnknown"
|
||||
: "admin.sales.email.delivery.errors.providerSendFailed",
|
||||
});
|
||||
}
|
||||
}
|
||||
const noReplyReminders = await fireNoReplyReminders(client as never, {
|
||||
now,
|
||||
take: options.take,
|
||||
});
|
||||
return {
|
||||
inspected: batch.inspected,
|
||||
claimed: batch.claimed.length,
|
||||
sent,
|
||||
failed,
|
||||
blocked: batch.blocked,
|
||||
deferred: batch.deferred,
|
||||
recoveredUnknown: batch.recoveredUnknown,
|
||||
noReplyReminders,
|
||||
};
|
||||
}
|
||||
|
||||
function providerMessage(email: ClaimedAdminEmail, bodyHtml?: string) {
|
||||
return {
|
||||
fromAddress: email.fromAddress,
|
||||
fromName: email.fromName,
|
||||
to: email.toAddresses.map((address) => ({ address })),
|
||||
cc: email.ccAddresses.map((address) => ({ address })),
|
||||
bcc: email.bccAddresses.map((address) => ({ address })),
|
||||
subject: email.subject,
|
||||
bodyHtml: bodyHtml ?? email.bodyHtml,
|
||||
providerThreadId: email.providerThreadId,
|
||||
};
|
||||
}
|
||||
|
||||
function prepareTracking(
|
||||
email: ClaimedAdminEmail,
|
||||
config:
|
||||
| {
|
||||
readonly host: string;
|
||||
readonly secret: string;
|
||||
}
|
||||
| null
|
||||
| undefined,
|
||||
sentAt: Date
|
||||
): PreparedAdminEmailTracking | null {
|
||||
if (!email.trackingEnabled) return null;
|
||||
if (!config?.host || !config.secret) {
|
||||
throw new Error("admin_email_tracking_not_configured");
|
||||
}
|
||||
const expiresAt = new Date(
|
||||
sentAt.getTime() + email.trackingRetentionDays * 24 * 60 * 60 * 1_000
|
||||
);
|
||||
return prepareAdminEmailTracking({
|
||||
html: email.bodyHtml,
|
||||
scheduledEmailId: email.id,
|
||||
adminUserId: email.adminUserId,
|
||||
baseUrl: adminEmailTrackingBaseUrl(config.host),
|
||||
secret: config.secret,
|
||||
expiresAt,
|
||||
});
|
||||
}
|
||||
|
||||
function workerCredentialBundle(raw: Readonly<Record<string, unknown>>) {
|
||||
if (
|
||||
typeof raw.accessToken !== "string" ||
|
||||
typeof raw.refreshToken !== "string" ||
|
||||
typeof raw.expiresAt !== "string" ||
|
||||
!Array.isArray(raw.scopes) ||
|
||||
raw.scopes.some((scope) => typeof scope !== "string")
|
||||
) {
|
||||
throw new Error("invalid_admin_email_worker_credential");
|
||||
}
|
||||
return {
|
||||
accessToken: raw.accessToken,
|
||||
refreshToken: raw.refreshToken,
|
||||
expiresAt: raw.expiresAt,
|
||||
scopes: raw.scopes as string[],
|
||||
};
|
||||
}
|
||||
|
||||
function isFullResyncError(
|
||||
error: unknown
|
||||
): error is { readonly fullResyncRequired: true } {
|
||||
return (
|
||||
typeof error === "object" &&
|
||||
error !== null &&
|
||||
"fullResyncRequired" in error &&
|
||||
error.fullResyncRequired === true
|
||||
);
|
||||
}
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
createAdminMailProviderGateway,
|
||||
type AdminMailProviderPorts,
|
||||
} from "./admin-mail-provider.server.js";
|
||||
import {
|
||||
GMAIL_SCOPES,
|
||||
} from "./google/gmailApi.js";
|
||||
import {
|
||||
MICROSOFT_MAIL_SCOPES,
|
||||
} from "./microsoft/graphMailApi.js";
|
||||
|
||||
function ports(): AdminMailProviderPorts {
|
||||
return {
|
||||
gmail: {
|
||||
configured: () => true,
|
||||
authorizationUrl: (state) => `https://google.test?state=${state}`,
|
||||
exchange: vi.fn().mockResolvedValue({
|
||||
accessToken: "google-access",
|
||||
refreshToken: "google-refresh",
|
||||
expiresAt: new Date("2026-07-24T12:00:00.000Z"),
|
||||
scopes: GMAIL_SCOPES,
|
||||
}),
|
||||
profile: vi.fn().mockResolvedValue({
|
||||
externalAccountId: "google-account",
|
||||
email: "SALES@HIVEGRID.DE",
|
||||
name: "Sales",
|
||||
}),
|
||||
refresh: vi.fn().mockResolvedValue({
|
||||
accessToken: "google-next",
|
||||
expiresAt: new Date("2026-07-24T13:00:00.000Z"),
|
||||
scopes: GMAIL_SCOPES,
|
||||
}),
|
||||
revoke: vi.fn().mockResolvedValue(undefined),
|
||||
send: vi.fn().mockResolvedValue({
|
||||
id: "google-message-1",
|
||||
threadId: "google-thread-1",
|
||||
}),
|
||||
},
|
||||
microsoft: {
|
||||
configured: () => true,
|
||||
authorizationUrl: (state) => `https://microsoft.test?state=${state}`,
|
||||
exchange: vi.fn().mockResolvedValue({
|
||||
accessToken: "microsoft-access",
|
||||
refreshToken: "microsoft-refresh",
|
||||
expiresAt: new Date("2026-07-24T12:00:00.000Z"),
|
||||
scopes: MICROSOFT_MAIL_SCOPES,
|
||||
}),
|
||||
profile: vi.fn().mockResolvedValue({
|
||||
externalAccountId: "microsoft-account",
|
||||
email: "sales@hivegrid.de",
|
||||
displayName: "Sales",
|
||||
}),
|
||||
refresh: vi.fn().mockResolvedValue({
|
||||
accessToken: "microsoft-next",
|
||||
refreshToken: "microsoft-next-refresh",
|
||||
expiresAt: new Date("2026-07-24T13:00:00.000Z"),
|
||||
scopes: MICROSOFT_MAIL_SCOPES,
|
||||
}),
|
||||
send: vi.fn().mockResolvedValue(undefined),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("admin mail provider gateway", () => {
|
||||
it.each([
|
||||
["google_mail", "google-account"],
|
||||
["microsoft_mail", "microsoft-account"],
|
||||
] as const)("exchanges %s grants into one normalized contract", async (provider, accountId) => {
|
||||
const gateway = createAdminMailProviderGateway(ports());
|
||||
await expect(gateway.exchange(provider, "oauth-code")).resolves.toMatchObject({
|
||||
account: {
|
||||
externalAccountId: accountId,
|
||||
emailAddress: "sales@hivegrid.de",
|
||||
},
|
||||
credentials: {
|
||||
expiresAt: "2026-07-24T12:00:00.000Z",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("preserves a Google refresh token when refresh rotates only access", async () => {
|
||||
const gateway = createAdminMailProviderGateway(ports());
|
||||
await expect(
|
||||
gateway.refresh("google_mail", {
|
||||
accessToken: "google-access",
|
||||
refreshToken: "google-refresh",
|
||||
expiresAt: "2026-07-24T12:00:00.000Z",
|
||||
scopes: GMAIL_SCOPES,
|
||||
})
|
||||
).resolves.toMatchObject({
|
||||
accessToken: "google-next",
|
||||
refreshToken: "google-refresh",
|
||||
});
|
||||
});
|
||||
|
||||
it("revokes Google at the provider and shreds Microsoft only locally", async () => {
|
||||
const providerPorts = ports();
|
||||
const gateway = createAdminMailProviderGateway(providerPorts);
|
||||
const googleCredentials = {
|
||||
accessToken: "google-access",
|
||||
refreshToken: "google-refresh",
|
||||
expiresAt: "2026-07-24T12:00:00.000Z",
|
||||
scopes: GMAIL_SCOPES,
|
||||
};
|
||||
|
||||
await gateway.revoke("google_mail", googleCredentials);
|
||||
expect(providerPorts.gmail.revoke).toHaveBeenCalledWith("google-refresh");
|
||||
await expect(
|
||||
gateway.revoke("microsoft_mail", {
|
||||
...googleCredentials,
|
||||
scopes: MICROSOFT_MAIL_SCOPES,
|
||||
})
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it("sends a threaded RFC-2822 message through Gmail", async () => {
|
||||
const providerPorts = ports();
|
||||
const gateway = createAdminMailProviderGateway(providerPorts);
|
||||
|
||||
await expect(
|
||||
gateway.send(
|
||||
"google_mail",
|
||||
{
|
||||
accessToken: "google-access",
|
||||
refreshToken: "google-refresh",
|
||||
expiresAt: "2026-07-24T12:00:00.000Z",
|
||||
scopes: GMAIL_SCOPES,
|
||||
},
|
||||
{
|
||||
fromAddress: "sales@hivegrid.de",
|
||||
fromName: "Sales Team",
|
||||
to: [{ address: "lead@example.com", name: "Lead" }],
|
||||
subject: "Demo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
providerThreadId: "google-thread-1",
|
||||
inReplyToInternetMessageId: "previous@example.com",
|
||||
}
|
||||
)
|
||||
).resolves.toEqual({
|
||||
providerMessageId: "google-message-1",
|
||||
providerThreadId: "google-thread-1",
|
||||
});
|
||||
|
||||
expect(providerPorts.gmail.send).toHaveBeenCalledWith(
|
||||
"google-access",
|
||||
expect.any(String),
|
||||
"google-thread-1"
|
||||
);
|
||||
const raw = Buffer.from(
|
||||
vi.mocked(providerPorts.gmail.send).mock.calls[0]![1],
|
||||
"base64url"
|
||||
).toString("utf8");
|
||||
expect(raw).toContain("Subject: Demo");
|
||||
expect(raw).toContain("In-Reply-To: <previous@example.com>");
|
||||
});
|
||||
|
||||
it("sends the neutral message contract through Microsoft", async () => {
|
||||
const providerPorts = ports();
|
||||
const gateway = createAdminMailProviderGateway(providerPorts);
|
||||
|
||||
await expect(
|
||||
gateway.send(
|
||||
"microsoft_mail",
|
||||
{
|
||||
accessToken: "microsoft-access",
|
||||
refreshToken: "microsoft-refresh",
|
||||
expiresAt: "2026-07-24T12:00:00.000Z",
|
||||
scopes: MICROSOFT_MAIL_SCOPES,
|
||||
},
|
||||
{
|
||||
fromAddress: "sales@hivegrid.de",
|
||||
to: [{ address: "lead@example.com" }],
|
||||
subject: "Demo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
}
|
||||
)
|
||||
).resolves.toEqual({
|
||||
providerMessageId: null,
|
||||
providerThreadId: null,
|
||||
});
|
||||
|
||||
expect(providerPorts.microsoft.send).toHaveBeenCalledWith(
|
||||
"microsoft-access",
|
||||
{
|
||||
subject: "Demo",
|
||||
bodyHtml: "<p>Hallo</p>",
|
||||
to: [{ address: "lead@example.com" }],
|
||||
cc: undefined,
|
||||
bcc: undefined,
|
||||
}
|
||||
);
|
||||
});
|
||||
});
|
||||
+373
@@ -0,0 +1,373 @@
|
||||
import {
|
||||
buildGmailAuthorizationUrl,
|
||||
exchangeGmailCodeForTokens,
|
||||
fetchGmailUserInfo,
|
||||
refreshGmailAccessToken,
|
||||
resolveGmailOAuthConfig,
|
||||
revokeGmailToken,
|
||||
sendRawMessage,
|
||||
} from "./google/gmailApi.js";
|
||||
import {
|
||||
buildMicrosoftAuthorizationUrl,
|
||||
exchangeMicrosoftCodeForTokens,
|
||||
fetchGraphUserProfile,
|
||||
refreshMicrosoftAccessToken,
|
||||
resolveMicrosoftMailOAuthConfig,
|
||||
sendGraphMail,
|
||||
} from "./microsoft/graphMailApi.js";
|
||||
import type {
|
||||
AdminMailConnectionProvider,
|
||||
AdminOAuthCredentialBundle,
|
||||
} from "./admin-connections.js";
|
||||
import { normalizeAdminOAuthCredentialBundle } from "./admin-connections.js";
|
||||
import {
|
||||
buildRfc2822Message,
|
||||
type MappedEmailAddress,
|
||||
} from "./email-message-mapping.js";
|
||||
|
||||
export type AdminMailAccount = {
|
||||
readonly externalAccountId: string;
|
||||
readonly emailAddress: string;
|
||||
readonly displayName: string | null;
|
||||
};
|
||||
|
||||
export type AdminMailOAuthGrant = {
|
||||
readonly credentials: AdminOAuthCredentialBundle;
|
||||
readonly account: AdminMailAccount;
|
||||
};
|
||||
|
||||
export type AdminMailProviderPorts = {
|
||||
readonly gmail: {
|
||||
readonly configured: () => boolean;
|
||||
readonly authorizationUrl: (state: string) => string;
|
||||
readonly exchange: (code: string) => Promise<{
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}>;
|
||||
readonly profile: (accessToken: string) => Promise<{
|
||||
readonly externalAccountId: string;
|
||||
readonly email: string;
|
||||
readonly name?: string;
|
||||
}>;
|
||||
readonly refresh: (refreshToken: string) => Promise<{
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}>;
|
||||
readonly revoke: (token: string) => Promise<void>;
|
||||
readonly send: (
|
||||
accessToken: string,
|
||||
rawBase64Url: string,
|
||||
threadId?: string
|
||||
) => Promise<{ readonly id: string; readonly threadId?: string }>;
|
||||
};
|
||||
readonly microsoft: {
|
||||
readonly configured: () => boolean;
|
||||
readonly authorizationUrl: (state: string) => string;
|
||||
readonly exchange: (code: string) => Promise<{
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}>;
|
||||
readonly profile: (accessToken: string) => Promise<{
|
||||
readonly externalAccountId: string;
|
||||
readonly email: string;
|
||||
readonly displayName?: string;
|
||||
}>;
|
||||
readonly refresh: (refreshToken: string) => Promise<{
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken?: string;
|
||||
readonly expiresAt: Date;
|
||||
readonly scopes: readonly string[];
|
||||
}>;
|
||||
readonly send: (
|
||||
accessToken: string,
|
||||
input: {
|
||||
readonly subject: string;
|
||||
readonly bodyHtml: string;
|
||||
readonly to: readonly MappedEmailAddress[];
|
||||
readonly cc?: readonly MappedEmailAddress[];
|
||||
readonly bcc?: readonly MappedEmailAddress[];
|
||||
}
|
||||
) => Promise<void>;
|
||||
};
|
||||
};
|
||||
|
||||
export function createAdminMailProviderGateway(
|
||||
ports: AdminMailProviderPorts = defaultPorts()
|
||||
) {
|
||||
return {
|
||||
configured(provider: AdminMailConnectionProvider): boolean {
|
||||
return provider === "google_mail"
|
||||
? ports.gmail.configured()
|
||||
: ports.microsoft.configured();
|
||||
},
|
||||
|
||||
authorizationUrl(
|
||||
provider: AdminMailConnectionProvider,
|
||||
state: string
|
||||
): string {
|
||||
if (!this.configured(provider)) {
|
||||
throw new AdminMailProviderError("provider_not_configured");
|
||||
}
|
||||
return provider === "google_mail"
|
||||
? ports.gmail.authorizationUrl(state)
|
||||
: ports.microsoft.authorizationUrl(state);
|
||||
},
|
||||
|
||||
async exchange(
|
||||
provider: AdminMailConnectionProvider,
|
||||
code: string
|
||||
): Promise<AdminMailOAuthGrant> {
|
||||
if (!this.configured(provider)) {
|
||||
throw new AdminMailProviderError("provider_not_configured");
|
||||
}
|
||||
const grant =
|
||||
provider === "google_mail"
|
||||
? await exchangeGoogle(ports, code)
|
||||
: await exchangeMicrosoft(ports, code);
|
||||
return Object.freeze(grant);
|
||||
},
|
||||
|
||||
async refresh(
|
||||
provider: AdminMailConnectionProvider,
|
||||
credentials: AdminOAuthCredentialBundle
|
||||
): Promise<AdminOAuthCredentialBundle> {
|
||||
const current = normalizeAdminOAuthCredentialBundle(
|
||||
provider,
|
||||
credentials
|
||||
);
|
||||
const next =
|
||||
provider === "google_mail"
|
||||
? await ports.gmail.refresh(current.refreshToken)
|
||||
: await ports.microsoft.refresh(current.refreshToken);
|
||||
return normalizeAdminOAuthCredentialBundle(provider, {
|
||||
accessToken: next.accessToken,
|
||||
refreshToken: next.refreshToken ?? current.refreshToken,
|
||||
expiresAt: next.expiresAt.toISOString(),
|
||||
scopes: next.scopes.length > 0 ? next.scopes : current.scopes,
|
||||
});
|
||||
},
|
||||
|
||||
async revoke(
|
||||
provider: AdminMailConnectionProvider,
|
||||
credentials: AdminOAuthCredentialBundle
|
||||
): Promise<void> {
|
||||
const normalized = normalizeAdminOAuthCredentialBundle(
|
||||
provider,
|
||||
credentials
|
||||
);
|
||||
if (provider === "google_mail") {
|
||||
await ports.gmail.revoke(normalized.refreshToken);
|
||||
}
|
||||
// Microsoft delegated tokens have no app-side revoke endpoint. Removing
|
||||
// the encrypted refresh token is the reviewed disconnect boundary.
|
||||
},
|
||||
|
||||
async send(
|
||||
provider: AdminMailConnectionProvider,
|
||||
credentials: AdminOAuthCredentialBundle,
|
||||
message: {
|
||||
readonly fromAddress: string;
|
||||
readonly fromName?: string | null;
|
||||
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 providerThreadId?: string | null;
|
||||
}
|
||||
): Promise<{
|
||||
readonly providerMessageId: string | null;
|
||||
readonly providerThreadId: string | null;
|
||||
}> {
|
||||
const normalized = normalizeAdminOAuthCredentialBundle(
|
||||
provider,
|
||||
credentials
|
||||
);
|
||||
if (provider === "google_mail") {
|
||||
const raw = buildRfc2822Message({
|
||||
fromAddress: message.fromAddress,
|
||||
fromName: message.fromName ?? undefined,
|
||||
to: message.to,
|
||||
cc: message.cc,
|
||||
bcc: message.bcc,
|
||||
subject: message.subject,
|
||||
bodyHtml: message.bodyHtml,
|
||||
inReplyToInternetMessageId:
|
||||
message.inReplyToInternetMessageId,
|
||||
referencesInternetMessageIds:
|
||||
message.referencesInternetMessageIds,
|
||||
});
|
||||
const result = await ports.gmail.send(
|
||||
normalized.accessToken,
|
||||
Buffer.from(raw, "utf8").toString("base64url"),
|
||||
message.providerThreadId ?? undefined
|
||||
);
|
||||
return {
|
||||
providerMessageId: result.id,
|
||||
providerThreadId: result.threadId ?? null,
|
||||
};
|
||||
}
|
||||
await ports.microsoft.send(normalized.accessToken, {
|
||||
subject: message.subject,
|
||||
bodyHtml: message.bodyHtml,
|
||||
to: message.to,
|
||||
cc: message.cc,
|
||||
bcc: message.bcc,
|
||||
});
|
||||
return { providerMessageId: null, providerThreadId: null };
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function exchangeGoogle(
|
||||
ports: AdminMailProviderPorts,
|
||||
code: string
|
||||
): Promise<AdminMailOAuthGrant> {
|
||||
const token = await ports.gmail.exchange(requiredCode(code));
|
||||
if (!token.refreshToken) {
|
||||
throw new AdminMailProviderError("refresh_token_missing");
|
||||
}
|
||||
const profile = await ports.gmail.profile(token.accessToken);
|
||||
return {
|
||||
credentials: normalizeAdminOAuthCredentialBundle("google_mail", {
|
||||
accessToken: token.accessToken,
|
||||
refreshToken: token.refreshToken,
|
||||
expiresAt: token.expiresAt.toISOString(),
|
||||
scopes: token.scopes,
|
||||
}),
|
||||
account: normalizeAccount({
|
||||
externalAccountId: profile.externalAccountId,
|
||||
emailAddress: profile.email,
|
||||
displayName: profile.name ?? null,
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
async function exchangeMicrosoft(
|
||||
ports: AdminMailProviderPorts,
|
||||
code: string
|
||||
): Promise<AdminMailOAuthGrant> {
|
||||
const token = await ports.microsoft.exchange(requiredCode(code));
|
||||
if (!token.refreshToken) {
|
||||
throw new AdminMailProviderError("refresh_token_missing");
|
||||
}
|
||||
const profile = await ports.microsoft.profile(token.accessToken);
|
||||
return {
|
||||
credentials: normalizeAdminOAuthCredentialBundle("microsoft_mail", {
|
||||
accessToken: token.accessToken,
|
||||
refreshToken: token.refreshToken,
|
||||
expiresAt: token.expiresAt.toISOString(),
|
||||
scopes: token.scopes,
|
||||
}),
|
||||
account: normalizeAccount({
|
||||
externalAccountId: profile.externalAccountId,
|
||||
emailAddress: profile.email,
|
||||
displayName: profile.displayName ?? null,
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
function defaultPorts(): AdminMailProviderPorts {
|
||||
return {
|
||||
gmail: {
|
||||
configured: () => resolveGmailOAuthConfig() !== null,
|
||||
authorizationUrl: (state) => {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return buildGmailAuthorizationUrl(config, state);
|
||||
},
|
||||
exchange: (code) => {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return exchangeGmailCodeForTokens(config, code);
|
||||
},
|
||||
profile: async (accessToken) => {
|
||||
const profile = await fetchGmailUserInfo(accessToken);
|
||||
return {
|
||||
externalAccountId: profile.sub,
|
||||
email: profile.email,
|
||||
};
|
||||
},
|
||||
refresh: (refreshToken) => {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return refreshGmailAccessToken(config, refreshToken);
|
||||
},
|
||||
revoke: revokeGmailToken,
|
||||
send: sendRawMessage,
|
||||
},
|
||||
microsoft: {
|
||||
configured: () => resolveMicrosoftMailOAuthConfig() !== null,
|
||||
authorizationUrl: (state) => {
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return buildMicrosoftAuthorizationUrl(config, state);
|
||||
},
|
||||
exchange: (code) => {
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return exchangeMicrosoftCodeForTokens(config, code);
|
||||
},
|
||||
profile: async (accessToken) => {
|
||||
const profile = await fetchGraphUserProfile(accessToken);
|
||||
return {
|
||||
externalAccountId: profile.id,
|
||||
email: profile.email,
|
||||
displayName: profile.displayName,
|
||||
};
|
||||
},
|
||||
refresh: (refreshToken) => {
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) throw new AdminMailProviderError("provider_not_configured");
|
||||
return refreshMicrosoftAccessToken(config, refreshToken);
|
||||
},
|
||||
send: sendGraphMail,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function normalizeAccount(account: AdminMailAccount): AdminMailAccount {
|
||||
const emailAddress = account.emailAddress.trim().toLowerCase();
|
||||
const externalAccountId = account.externalAccountId.trim();
|
||||
if (
|
||||
!externalAccountId ||
|
||||
!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(emailAddress)
|
||||
) {
|
||||
throw new AdminMailProviderError("invalid_provider_account");
|
||||
}
|
||||
return Object.freeze({
|
||||
externalAccountId,
|
||||
emailAddress,
|
||||
displayName: account.displayName?.trim() || null,
|
||||
});
|
||||
}
|
||||
|
||||
function requiredCode(code: string): string {
|
||||
const normalized = code.trim();
|
||||
if (!normalized || normalized.length > 8_192) {
|
||||
throw new AdminMailProviderError("invalid_oauth_code");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
export class AdminMailProviderError extends Error {
|
||||
readonly code:
|
||||
| "provider_not_configured"
|
||||
| "invalid_oauth_code"
|
||||
| "refresh_token_missing"
|
||||
| "invalid_provider_account";
|
||||
|
||||
constructor(code: AdminMailProviderError["code"]) {
|
||||
super(code);
|
||||
this.name = "AdminMailProviderError";
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
createAdminMailSyncProvider,
|
||||
type AdminMailSyncProviderPorts,
|
||||
} from "./admin-mail-sync-provider.server.js";
|
||||
|
||||
function ports(): AdminMailSyncProviderPorts {
|
||||
return {
|
||||
gmail: {
|
||||
listHistory: vi.fn(),
|
||||
listMessageIds: vi.fn(),
|
||||
currentCursor: vi.fn(),
|
||||
getMessage: vi.fn(),
|
||||
},
|
||||
microsoft: {
|
||||
initialDeltaUrl: vi.fn(
|
||||
() =>
|
||||
"https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages/delta"
|
||||
),
|
||||
deltaPage: vi.fn(),
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("admin mail sync provider", () => {
|
||||
it("runs a bounded Gmail initial sync and stores the current history cursor", async () => {
|
||||
const providerPorts = ports();
|
||||
vi.mocked(providerPorts.gmail.listMessageIds).mockResolvedValue({
|
||||
messageIds: ["message-1"],
|
||||
});
|
||||
vi.mocked(providerPorts.gmail.currentCursor).mockResolvedValue("history-9");
|
||||
vi.mocked(providerPorts.gmail.getMessage).mockResolvedValue({
|
||||
id: "message-1",
|
||||
threadId: "thread-1",
|
||||
labelIds: ["INBOX"],
|
||||
internalDate: "1784887200000",
|
||||
payload: {
|
||||
headers: [
|
||||
{ name: "From", value: "buyer@example.com" },
|
||||
{ name: "To", value: "sales@hivegrid.de" },
|
||||
{ name: "Subject", value: "Demo" },
|
||||
],
|
||||
},
|
||||
});
|
||||
|
||||
await expect(
|
||||
createAdminMailSyncProvider(providerPorts).fetchBatch({
|
||||
provider: "google_mail",
|
||||
accessToken: "access",
|
||||
externalFolderId: "*",
|
||||
cursorToken: null,
|
||||
})
|
||||
).resolves.toMatchObject({
|
||||
nextCursor: "history-9",
|
||||
messages: [
|
||||
{
|
||||
providerMessageId: "message-1",
|
||||
direction: "inbound",
|
||||
subject: "Demo",
|
||||
},
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it("deduplicates Gmail history ids across pages before hydrating messages", async () => {
|
||||
const providerPorts = ports();
|
||||
vi.mocked(providerPorts.gmail.listHistory)
|
||||
.mockResolvedValueOnce({
|
||||
addedMessageIds: ["message-1"],
|
||||
nextPageToken: "page-2",
|
||||
historyId: "history-2",
|
||||
})
|
||||
.mockResolvedValueOnce({
|
||||
addedMessageIds: ["message-1", "message-2"],
|
||||
historyId: "history-3",
|
||||
});
|
||||
vi.mocked(providerPorts.gmail.getMessage).mockImplementation(
|
||||
async (_token, id) => ({
|
||||
id,
|
||||
labelIds: ["SENT"],
|
||||
internalDate: "1784887200000",
|
||||
payload: {
|
||||
headers: [
|
||||
{ name: "From", value: "sales@hivegrid.de" },
|
||||
{ name: "To", value: "buyer@example.com" },
|
||||
],
|
||||
},
|
||||
})
|
||||
);
|
||||
const result = await createAdminMailSyncProvider(
|
||||
providerPorts
|
||||
).fetchBatch({
|
||||
provider: "google_mail",
|
||||
accessToken: "access",
|
||||
externalFolderId: "*",
|
||||
cursorToken: "history-1",
|
||||
});
|
||||
|
||||
expect(result.nextCursor).toBe("history-3");
|
||||
expect(result.messages).toHaveLength(2);
|
||||
expect(providerPorts.gmail.getMessage).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it("follows Microsoft next links verbatim until the delta cursor", async () => {
|
||||
const providerPorts = ports();
|
||||
vi.mocked(providerPorts.microsoft.deltaPage)
|
||||
.mockResolvedValueOnce({
|
||||
messages: [],
|
||||
nextLink:
|
||||
"https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages/delta?page=2",
|
||||
})
|
||||
.mockResolvedValueOnce({
|
||||
messages: [
|
||||
{
|
||||
id: "message-1",
|
||||
subject: "Demo",
|
||||
from: { emailAddress: { address: "buyer@example.com" } },
|
||||
toRecipients: [
|
||||
{ emailAddress: { address: "sales@hivegrid.de" } },
|
||||
],
|
||||
sentDateTime: "2026-07-24T10:00:00.000Z",
|
||||
},
|
||||
],
|
||||
deltaLink:
|
||||
"https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages/delta?$deltatoken=next",
|
||||
} as never);
|
||||
|
||||
const result = await createAdminMailSyncProvider(
|
||||
providerPorts
|
||||
).fetchBatch({
|
||||
provider: "microsoft_mail",
|
||||
accessToken: "access",
|
||||
externalFolderId: "inbox",
|
||||
cursorToken: null,
|
||||
now: new Date("2026-07-24T10:00:00.000Z"),
|
||||
});
|
||||
|
||||
expect(result.nextCursor).toContain("$deltatoken=next");
|
||||
expect(result.messages[0]).toMatchObject({
|
||||
providerMessageId: "message-1",
|
||||
direction: "inbound",
|
||||
});
|
||||
expect(providerPorts.microsoft.deltaPage).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
});
|
||||
+194
@@ -0,0 +1,194 @@
|
||||
import {
|
||||
fetchGmailHistoryCursor,
|
||||
getMessage,
|
||||
listHistory,
|
||||
listMessageIds,
|
||||
type GmailHistoryPage,
|
||||
type GmailMessage,
|
||||
type GmailMessageIdPage,
|
||||
} from "./google/gmailApi.js";
|
||||
import {
|
||||
buildInitialDeltaUrl,
|
||||
fetchDeltaPage,
|
||||
type GraphDeltaPage,
|
||||
} from "./microsoft/graphMailApi.js";
|
||||
import {
|
||||
mapGmailMessage,
|
||||
mapGraphMessage,
|
||||
type MappedEmailMessage,
|
||||
} from "./email-message-mapping.js";
|
||||
|
||||
const MAX_PAGES = 5;
|
||||
const INITIAL_LOOKBACK_DAYS = 90;
|
||||
|
||||
export type AdminMailSyncProviderPorts = {
|
||||
readonly gmail: {
|
||||
readonly listHistory: typeof listHistory;
|
||||
readonly listMessageIds: typeof listMessageIds;
|
||||
readonly getMessage: typeof getMessage;
|
||||
readonly currentCursor: typeof fetchGmailHistoryCursor;
|
||||
};
|
||||
readonly microsoft: {
|
||||
readonly initialDeltaUrl: typeof buildInitialDeltaUrl;
|
||||
readonly deltaPage: typeof fetchDeltaPage;
|
||||
};
|
||||
};
|
||||
|
||||
export type AdminMailSyncBatch = {
|
||||
readonly messages: readonly MappedEmailMessage[];
|
||||
readonly nextCursor: string;
|
||||
};
|
||||
|
||||
export function createAdminMailSyncProvider(
|
||||
ports: AdminMailSyncProviderPorts = defaultPorts()
|
||||
) {
|
||||
return {
|
||||
async fetchBatch(input: {
|
||||
readonly provider: "google_mail" | "microsoft_mail";
|
||||
readonly accessToken: string;
|
||||
readonly externalFolderId: string;
|
||||
readonly cursorToken: string | null;
|
||||
readonly now?: Date;
|
||||
}): Promise<AdminMailSyncBatch> {
|
||||
return input.provider === "google_mail"
|
||||
? fetchGmailBatch(ports, input)
|
||||
: fetchMicrosoftBatch(ports, input);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function fetchGmailBatch(
|
||||
ports: AdminMailSyncProviderPorts,
|
||||
input: {
|
||||
readonly accessToken: string;
|
||||
readonly cursorToken: string | null;
|
||||
}
|
||||
): Promise<AdminMailSyncBatch> {
|
||||
const ids = new Set<string>();
|
||||
if (input.cursorToken) {
|
||||
let pageToken: string | undefined;
|
||||
let nextCursor = input.cursorToken;
|
||||
for (let page = 0; page < MAX_PAGES; page += 1) {
|
||||
const result: GmailHistoryPage = await ports.gmail.listHistory(
|
||||
input.accessToken,
|
||||
input.cursorToken,
|
||||
pageToken
|
||||
);
|
||||
result.addedMessageIds.forEach((id) => ids.add(id));
|
||||
nextCursor = result.historyId ?? nextCursor;
|
||||
pageToken = result.nextPageToken;
|
||||
if (!pageToken) {
|
||||
return {
|
||||
messages: await fetchGmailMessages(ports, input.accessToken, ids),
|
||||
nextCursor,
|
||||
};
|
||||
}
|
||||
}
|
||||
throw new AdminMailSyncProviderError("provider_page_limit");
|
||||
}
|
||||
|
||||
let pageToken: string | undefined;
|
||||
for (let page = 0; page < MAX_PAGES; page += 1) {
|
||||
const result: GmailMessageIdPage = await ports.gmail.listMessageIds(
|
||||
input.accessToken,
|
||||
{
|
||||
q: `newer_than:${INITIAL_LOOKBACK_DAYS}d in:anywhere -in:spam -in:trash`,
|
||||
pageToken,
|
||||
maxResults: 100,
|
||||
}
|
||||
);
|
||||
result.messageIds.forEach((id) => ids.add(id));
|
||||
pageToken = result.nextPageToken;
|
||||
if (!pageToken) {
|
||||
return {
|
||||
messages: await fetchGmailMessages(ports, input.accessToken, ids),
|
||||
nextCursor: await ports.gmail.currentCursor(input.accessToken),
|
||||
};
|
||||
}
|
||||
}
|
||||
throw new AdminMailSyncProviderError("provider_page_limit");
|
||||
}
|
||||
|
||||
async function fetchGmailMessages(
|
||||
ports: AdminMailSyncProviderPorts,
|
||||
accessToken: string,
|
||||
ids: ReadonlySet<string>
|
||||
) {
|
||||
const messages: MappedEmailMessage[] = [];
|
||||
for (const id of ids) {
|
||||
const source: GmailMessage = await ports.gmail.getMessage(
|
||||
accessToken,
|
||||
id,
|
||||
"full"
|
||||
);
|
||||
messages.push(mapGmailMessage(source));
|
||||
}
|
||||
return messages;
|
||||
}
|
||||
|
||||
async function fetchMicrosoftBatch(
|
||||
ports: AdminMailSyncProviderPorts,
|
||||
input: {
|
||||
readonly accessToken: string;
|
||||
readonly externalFolderId: string;
|
||||
readonly cursorToken: string | null;
|
||||
readonly now?: Date;
|
||||
}
|
||||
): Promise<AdminMailSyncBatch> {
|
||||
const now = input.now ?? new Date();
|
||||
let url =
|
||||
input.cursorToken ??
|
||||
ports.microsoft.initialDeltaUrl(
|
||||
input.externalFolderId,
|
||||
new Date(
|
||||
now.getTime() - INITIAL_LOOKBACK_DAYS * 24 * 60 * 60 * 1_000
|
||||
).toISOString()
|
||||
);
|
||||
const messages: MappedEmailMessage[] = [];
|
||||
for (let page = 0; page < MAX_PAGES; page += 1) {
|
||||
const result: GraphDeltaPage = await ports.microsoft.deltaPage(
|
||||
input.accessToken,
|
||||
url
|
||||
);
|
||||
messages.push(
|
||||
...result.messages.map((message) =>
|
||||
mapGraphMessage(message, input.externalFolderId)
|
||||
)
|
||||
);
|
||||
if (result.deltaLink) {
|
||||
return { messages, nextCursor: result.deltaLink };
|
||||
}
|
||||
if (!result.nextLink) {
|
||||
throw new AdminMailSyncProviderError("provider_cursor_missing");
|
||||
}
|
||||
url = result.nextLink;
|
||||
}
|
||||
throw new AdminMailSyncProviderError("provider_page_limit");
|
||||
}
|
||||
|
||||
function defaultPorts(): AdminMailSyncProviderPorts {
|
||||
return {
|
||||
gmail: {
|
||||
listHistory,
|
||||
listMessageIds,
|
||||
getMessage,
|
||||
currentCursor: fetchGmailHistoryCursor,
|
||||
},
|
||||
microsoft: {
|
||||
initialDeltaUrl: buildInitialDeltaUrl,
|
||||
deltaPage: fetchDeltaPage,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export class AdminMailSyncProviderError extends Error {
|
||||
readonly code: "provider_page_limit" | "provider_cursor_missing";
|
||||
|
||||
constructor(
|
||||
code: "provider_page_limit" | "provider_cursor_missing"
|
||||
) {
|
||||
super(code);
|
||||
this.name = "AdminMailSyncProviderError";
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
claim: vi.fn(),
|
||||
settle: vi.fn(),
|
||||
withCredentials: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/admin-telephony-actions.server", () => ({
|
||||
claimAdminOutboundCallRequests: mocks.claim,
|
||||
settleAdminOutboundCallRequest: mocks.settle,
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/admin-connections.server", () => ({
|
||||
createPrismaAdminConnectionsRepository: vi.fn(() => ({})),
|
||||
createAdminConnectionsService: vi.fn(() => ({
|
||||
withCredentials: mocks.withCredentials,
|
||||
})),
|
||||
}));
|
||||
|
||||
import { processAdminOutboundCallRequests } from "./admin-outbound-calls.server.js";
|
||||
|
||||
const request = {
|
||||
id: "request-1",
|
||||
adminUserId: "admin-1",
|
||||
phoneConnectionId: "phone-connection-1",
|
||||
destinationE164: "+493012345678",
|
||||
};
|
||||
|
||||
function database(phoneConnection: unknown) {
|
||||
return {
|
||||
adminPhoneConnection: {
|
||||
findFirst: vi.fn(async () => phoneConnection),
|
||||
},
|
||||
} as never;
|
||||
}
|
||||
|
||||
describe("admin outbound call processing", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.claim.mockResolvedValue([request]);
|
||||
mocks.settle.mockImplementation(
|
||||
async (_db, input: { id: string; result: { status: string } }) => input
|
||||
);
|
||||
mocks.withCredentials.mockImplementation(
|
||||
async (_connectionId, _adminUserId, callback) =>
|
||||
callback({ accessToken: "permanent-aircall-token" })
|
||||
);
|
||||
});
|
||||
|
||||
it("uses the owner-bound provider identity and selected default line", async () => {
|
||||
const triggerOutboundCall = vi.fn(async () => ({ accepted: true as const }));
|
||||
const result = await processAdminOutboundCallRequests({
|
||||
db: database({
|
||||
connectionId: "data-connection-1",
|
||||
providerUserId: "42",
|
||||
defaultPhoneNumber: {
|
||||
providerNumberId: "7",
|
||||
selected: true,
|
||||
archivedAt: null,
|
||||
},
|
||||
}),
|
||||
provider: { triggerOutboundCall },
|
||||
});
|
||||
|
||||
expect(triggerOutboundCall).toHaveBeenCalledWith(
|
||||
{ accessToken: "permanent-aircall-token" },
|
||||
{
|
||||
userId: "42",
|
||||
numberId: "7",
|
||||
to: "+493012345678",
|
||||
}
|
||||
);
|
||||
expect(mocks.settle).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
{
|
||||
id: "request-1",
|
||||
result: { status: "accepted" },
|
||||
}
|
||||
);
|
||||
expect(result).toEqual({ claimed: 1, accepted: 1, failed: 0 });
|
||||
});
|
||||
|
||||
it("fails closed without a configured default line and stores only a stable error code", async () => {
|
||||
const triggerOutboundCall = vi.fn();
|
||||
const result = await processAdminOutboundCallRequests({
|
||||
db: database({
|
||||
connectionId: "data-connection-1",
|
||||
providerUserId: "42",
|
||||
defaultPhoneNumber: null,
|
||||
}),
|
||||
provider: { triggerOutboundCall },
|
||||
});
|
||||
|
||||
expect(triggerOutboundCall).not.toHaveBeenCalled();
|
||||
expect(mocks.settle).toHaveBeenCalledWith(
|
||||
expect.anything(),
|
||||
{
|
||||
id: "request-1",
|
||||
result: {
|
||||
status: "failed",
|
||||
errorCode: "phone_connection_incomplete",
|
||||
},
|
||||
}
|
||||
);
|
||||
expect(result).toEqual({ claimed: 1, accepted: 0, failed: 1 });
|
||||
});
|
||||
});
|
||||
+125
@@ -0,0 +1,125 @@
|
||||
import {
|
||||
createAdminConnectionsService,
|
||||
createPrismaAdminConnectionsRepository,
|
||||
} from "@hivegrid/db/admin-connections.server";
|
||||
import type { DbClient } from "@hivegrid/db/client.server";
|
||||
import {
|
||||
claimAdminOutboundCallRequests,
|
||||
settleAdminOutboundCallRequest,
|
||||
} from "@hivegrid/db/admin-telephony-actions.server";
|
||||
|
||||
import { aircallTelephonyProvider } from "./aircall/adapter.js";
|
||||
import { AircallError, type AircallCredentials } from "./aircall/types.js";
|
||||
|
||||
export type AdminOutboundCallProvider = {
|
||||
readonly triggerOutboundCall: (
|
||||
credentials: AircallCredentials,
|
||||
input: { userId: string; numberId: string; to: string }
|
||||
) => Promise<{ accepted: true }>;
|
||||
};
|
||||
|
||||
export async function processAdminOutboundCallRequests(input: {
|
||||
readonly db: DbClient;
|
||||
readonly take?: number;
|
||||
readonly provider?: AdminOutboundCallProvider;
|
||||
}): Promise<{ claimed: number; accepted: number; failed: number }> {
|
||||
const requests = await claimAdminOutboundCallRequests(
|
||||
input.db,
|
||||
input.take ?? 25
|
||||
);
|
||||
const provider = input.provider ?? aircallTelephonyProvider;
|
||||
const connections = createAdminConnectionsService({
|
||||
repository: createPrismaAdminConnectionsRepository(input.db),
|
||||
authorize: () => undefined,
|
||||
permission: "admin_sales.integrations.manage",
|
||||
});
|
||||
let accepted = 0;
|
||||
let failed = 0;
|
||||
for (const request of requests) {
|
||||
try {
|
||||
const phoneConnection = await input.db.adminPhoneConnection.findFirst({
|
||||
where: {
|
||||
id: request.phoneConnectionId,
|
||||
adminUserId: request.adminUserId,
|
||||
archivedAt: null,
|
||||
providerUserId: { not: null },
|
||||
defaultPhoneNumberId: { not: null },
|
||||
connection: {
|
||||
provider: "aircall",
|
||||
capability: "telephony",
|
||||
status: { in: ["active", "degraded"] },
|
||||
archivedAt: null,
|
||||
},
|
||||
},
|
||||
select: {
|
||||
connectionId: true,
|
||||
providerUserId: true,
|
||||
defaultPhoneNumber: {
|
||||
select: { providerNumberId: true, selected: true, archivedAt: true },
|
||||
},
|
||||
},
|
||||
});
|
||||
if (
|
||||
!phoneConnection?.providerUserId ||
|
||||
!phoneConnection.defaultPhoneNumber?.selected ||
|
||||
phoneConnection.defaultPhoneNumber.archivedAt
|
||||
) {
|
||||
throw new AdminOutboundCallProcessingError(
|
||||
"phone_connection_incomplete"
|
||||
);
|
||||
}
|
||||
await connections.withCredentials(
|
||||
phoneConnection.connectionId,
|
||||
request.adminUserId,
|
||||
async (raw) => {
|
||||
await provider.triggerOutboundCall(
|
||||
credentialBundle(raw),
|
||||
{
|
||||
userId: phoneConnection.providerUserId!,
|
||||
numberId:
|
||||
phoneConnection.defaultPhoneNumber!.providerNumberId,
|
||||
to: request.destinationE164,
|
||||
}
|
||||
);
|
||||
}
|
||||
);
|
||||
await settleAdminOutboundCallRequest(input.db, {
|
||||
id: request.id,
|
||||
result: { status: "accepted" },
|
||||
});
|
||||
accepted += 1;
|
||||
} catch (error) {
|
||||
await settleAdminOutboundCallRequest(input.db, {
|
||||
id: request.id,
|
||||
result: {
|
||||
status: "failed",
|
||||
errorCode: outboundErrorCode(error),
|
||||
},
|
||||
});
|
||||
failed += 1;
|
||||
}
|
||||
}
|
||||
return { claimed: requests.length, accepted, failed };
|
||||
}
|
||||
|
||||
function credentialBundle(
|
||||
value: Readonly<Record<string, unknown>>
|
||||
): AircallCredentials {
|
||||
if (typeof value.accessToken !== "string" || !value.accessToken.trim()) {
|
||||
throw new AdminOutboundCallProcessingError("credential_invalid");
|
||||
}
|
||||
return { accessToken: value.accessToken };
|
||||
}
|
||||
|
||||
function outboundErrorCode(error: unknown): string {
|
||||
if (error instanceof AdminOutboundCallProcessingError) return error.code;
|
||||
if (error instanceof AircallError) return `aircall_${error.code}`;
|
||||
return "provider_request_failed";
|
||||
}
|
||||
|
||||
class AdminOutboundCallProcessingError extends Error {
|
||||
constructor(readonly code: string) {
|
||||
super(code);
|
||||
this.name = "AdminOutboundCallProcessingError";
|
||||
}
|
||||
}
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
import type {
|
||||
AdminTelephonyRepository,
|
||||
PersistAdminCallEventResult,
|
||||
} from "@hivegrid/db/admin-telephony.server";
|
||||
|
||||
import {
|
||||
classifyTelephonyPhoneCandidates,
|
||||
normalizePhoneNumber,
|
||||
reduceTelephonyCallEvent,
|
||||
type TelephonyCallSnapshot,
|
||||
} from "./telephony/call-processing.js";
|
||||
import type { TelephonyCallEvent } from "./telephony/provider.js";
|
||||
|
||||
export async function processVerifiedAdminTelephonyEvent(input: {
|
||||
readonly phoneConnectionId: string;
|
||||
readonly adminUserId: string;
|
||||
readonly event: TelephonyCallEvent;
|
||||
readonly repository: AdminTelephonyRepository;
|
||||
readonly queueRecording?: (input: {
|
||||
readonly adminUserId: string;
|
||||
readonly callSessionId: string;
|
||||
readonly providerRecordingUrl: string;
|
||||
readonly occurredAt: Date;
|
||||
}) => Promise<unknown>;
|
||||
}): Promise<PersistAdminCallEventResult | null> {
|
||||
const current = await input.repository.getCallSnapshot({
|
||||
phoneConnectionId: input.phoneConnectionId,
|
||||
adminUserId: input.adminUserId,
|
||||
providerCallId: input.event.providerCallId,
|
||||
});
|
||||
const snapshot = reduceTelephonyCallEvent(
|
||||
current ? toProviderNeutralSnapshot(current) : null,
|
||||
input.event,
|
||||
);
|
||||
if (!snapshot) return null;
|
||||
const externalNumber = normalizePhoneNumber(
|
||||
input.event.externalNumber ??
|
||||
(snapshot.direction === "inbound"
|
||||
? snapshot.fromNumber
|
||||
: snapshot.toNumber),
|
||||
);
|
||||
if (!externalNumber) return null;
|
||||
const candidates = await input.repository.listPhoneCandidates({
|
||||
adminUserId: input.adminUserId,
|
||||
normalizedPhone: externalNumber,
|
||||
suffix: externalNumber.replace(/\D/gu, "").slice(-8),
|
||||
});
|
||||
const classified = classifyTelephonyPhoneCandidates(
|
||||
externalNumber,
|
||||
candidates,
|
||||
);
|
||||
const persisted = await input.repository.persistCallEvent({
|
||||
phoneConnectionId: input.phoneConnectionId,
|
||||
adminUserId: input.adminUserId,
|
||||
providerCallId: input.event.providerCallId,
|
||||
dedupeKey: input.event.dedupeKey,
|
||||
providerEvent: input.event.providerEvent,
|
||||
occurredAt: new Date(input.event.occurredAtIso),
|
||||
externalNumber,
|
||||
snapshot: {
|
||||
direction: snapshot.direction,
|
||||
status: snapshot.status,
|
||||
providerUserId: snapshot.providerUserId,
|
||||
fromNumber: snapshot.fromNumber,
|
||||
toNumber: snapshot.toNumber,
|
||||
startedAt: snapshot.startedAt,
|
||||
answeredAt: snapshot.answeredAt,
|
||||
endedAt: snapshot.endedAt,
|
||||
durationSeconds: snapshot.durationSeconds,
|
||||
},
|
||||
candidates: classified.map((candidate) => ({
|
||||
entityType: candidate.entityType,
|
||||
entityId: candidate.entityId,
|
||||
confidenceBasisPoints:
|
||||
candidate.confidence === "hard" ? 10_000 : 7_500,
|
||||
matchReason: candidate.confidence === "hard" ? "e164" : "suffix",
|
||||
})),
|
||||
});
|
||||
if (snapshot.recordingUrl && input.queueRecording) {
|
||||
await input.queueRecording({
|
||||
adminUserId: input.adminUserId,
|
||||
callSessionId: persisted.call.id,
|
||||
providerRecordingUrl: snapshot.recordingUrl,
|
||||
occurredAt: new Date(input.event.occurredAtIso),
|
||||
});
|
||||
}
|
||||
return persisted;
|
||||
}
|
||||
|
||||
function toProviderNeutralSnapshot(call: {
|
||||
readonly direction: "inbound" | "outbound";
|
||||
readonly status: "ringing" | "answered" | "completed" | "missed" | "failed";
|
||||
readonly providerUserId: string | null;
|
||||
readonly fromNumber: string;
|
||||
readonly toNumber: string;
|
||||
readonly startedAt: Date;
|
||||
readonly answeredAt: Date | null;
|
||||
readonly endedAt: Date | null;
|
||||
readonly durationSeconds: number | null;
|
||||
}): TelephonyCallSnapshot {
|
||||
return {
|
||||
...call,
|
||||
recordingUrl: null,
|
||||
};
|
||||
}
|
||||
+148
@@ -0,0 +1,148 @@
|
||||
import type { AdminTelephonyRepository } from "@hivegrid/db/admin-telephony.server";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { processVerifiedAdminTelephonyEvent } from "./admin-telephony-worker.server.js";
|
||||
import type { TelephonyCallEvent } from "./telephony/provider.js";
|
||||
|
||||
function event(
|
||||
overrides: Partial<TelephonyCallEvent> = {}
|
||||
): TelephonyCallEvent {
|
||||
return {
|
||||
provider: "aircall",
|
||||
providerEvent: "call.ended",
|
||||
type: "ended",
|
||||
dedupeKey: "aircall:call.ended:call_1:1",
|
||||
providerCallId: "call_1",
|
||||
occurredAtIso: "2026-07-24T08:02:00.000Z",
|
||||
direction: "inbound",
|
||||
status: "done",
|
||||
externalNumber: "+493012345678",
|
||||
lineId: "line_1",
|
||||
lineNumber: "+493099999999",
|
||||
providerUserId: "provider_user_1",
|
||||
providerUserEmail: "agent@example.test",
|
||||
startedAtIso: "2026-07-24T08:00:00.000Z",
|
||||
answeredAtIso: "2026-07-24T08:00:05.000Z",
|
||||
endedAtIso: "2026-07-24T08:02:00.000Z",
|
||||
durationSeconds: 115,
|
||||
missed: false,
|
||||
missedReason: null,
|
||||
recordingUrl: null,
|
||||
voicemailUrl: null,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("admin telephony worker orchestration", () => {
|
||||
it("persists all strongest matches so ambiguity remains visible", async () => {
|
||||
const repository = {
|
||||
getCallSnapshot: vi.fn().mockResolvedValue(null),
|
||||
listPhoneCandidates: vi.fn().mockResolvedValue([
|
||||
{
|
||||
entityType: "contact",
|
||||
entityId: "contact_1",
|
||||
phone: "+49 30 12345678",
|
||||
projectIds: ["deal_1"],
|
||||
},
|
||||
{
|
||||
entityType: "lead",
|
||||
entityId: "lead_1",
|
||||
phone: "030 12345678",
|
||||
projectIds: [],
|
||||
},
|
||||
]),
|
||||
persistCallEvent: vi.fn().mockResolvedValue({
|
||||
call: { id: "call_1" },
|
||||
duplicate: false,
|
||||
matchStatus: "ambiguous",
|
||||
}),
|
||||
} as unknown as AdminTelephonyRepository;
|
||||
|
||||
await processVerifiedAdminTelephonyEvent({
|
||||
phoneConnectionId: "phone_connection_1",
|
||||
adminUserId: "admin_1",
|
||||
event: event(),
|
||||
repository,
|
||||
});
|
||||
|
||||
expect(repository.listPhoneCandidates).toHaveBeenCalledWith({
|
||||
adminUserId: "admin_1",
|
||||
normalizedPhone: "+493012345678",
|
||||
suffix: "12345678",
|
||||
});
|
||||
expect(repository.persistCallEvent).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
candidates: [
|
||||
expect.objectContaining({
|
||||
entityType: "contact",
|
||||
entityId: "contact_1",
|
||||
matchReason: "e164",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
entityType: "lead",
|
||||
entityId: "lead_1",
|
||||
matchReason: "e164",
|
||||
}),
|
||||
],
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("ignores an initial event whose direction cannot be established", async () => {
|
||||
const repository = {
|
||||
getCallSnapshot: vi.fn().mockResolvedValue(null),
|
||||
listPhoneCandidates: vi.fn(),
|
||||
persistCallEvent: vi.fn(),
|
||||
} as unknown as AdminTelephonyRepository;
|
||||
|
||||
await expect(
|
||||
processVerifiedAdminTelephonyEvent({
|
||||
phoneConnectionId: "phone_connection_1",
|
||||
adminUserId: "admin_1",
|
||||
event: event({ direction: "unknown" }),
|
||||
repository,
|
||||
})
|
||||
).resolves.toBeNull();
|
||||
expect(repository.listPhoneCandidates).not.toHaveBeenCalled();
|
||||
expect(repository.persistCallEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("queues a provider recording only after the call event is durable", async () => {
|
||||
const persistCallEvent = vi.fn().mockResolvedValue({
|
||||
call: { id: "call_session_1" },
|
||||
duplicate: false,
|
||||
matchStatus: "unmatched",
|
||||
});
|
||||
const repository = {
|
||||
getCallSnapshot: vi.fn().mockResolvedValue(null),
|
||||
listPhoneCandidates: vi.fn().mockResolvedValue([]),
|
||||
persistCallEvent,
|
||||
} as unknown as AdminTelephonyRepository;
|
||||
const queueRecording = vi.fn().mockResolvedValue(undefined);
|
||||
|
||||
await processVerifiedAdminTelephonyEvent({
|
||||
phoneConnectionId: "phone_connection_1",
|
||||
adminUserId: "admin_1",
|
||||
event: event({
|
||||
type: "assets_ready",
|
||||
providerEvent: "call.comm_assets_generated",
|
||||
recordingUrl:
|
||||
"https://aircall.s3.eu-central-1.amazonaws.com/recording.mp3",
|
||||
}),
|
||||
repository,
|
||||
queueRecording,
|
||||
});
|
||||
|
||||
expect(persistCallEvent).toHaveBeenCalled();
|
||||
expect(queueRecording).toHaveBeenCalledWith({
|
||||
adminUserId: "admin_1",
|
||||
callSessionId: "call_session_1",
|
||||
providerRecordingUrl:
|
||||
"https://aircall.s3.eu-central-1.amazonaws.com/recording.mp3",
|
||||
occurredAt: new Date("2026-07-24T08:02:00.000Z"),
|
||||
});
|
||||
expect(
|
||||
persistCallEvent.mock.invocationCallOrder[0]
|
||||
).toBeLessThan(queueRecording.mock.invocationCallOrder[0]!);
|
||||
});
|
||||
});
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { aircallAdapter, aircallTelephonyProvider } from "./adapter.js";
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe("Aircall adapters", () => {
|
||||
it("registers an OAuth Apps Engine adapter without a refresh-token contract", () => {
|
||||
expect(aircallAdapter).toMatchObject({ key: "aircall", connectionType: "oauth2" });
|
||||
expect(aircallAdapter.refreshToken).toBeUndefined();
|
||||
});
|
||||
|
||||
it("exposes the provider-neutral telephony operations", () => {
|
||||
expect(aircallTelephonyProvider.key).toBe("aircall");
|
||||
expect(aircallTelephonyProvider).toMatchObject({
|
||||
connect: expect.any(Function),
|
||||
disconnect: expect.any(Function),
|
||||
listUsers: expect.any(Function),
|
||||
listProviderUsers: expect.any(Function),
|
||||
probe: expect.any(Function),
|
||||
listUserNumbers: expect.any(Function),
|
||||
startCall: expect.any(Function),
|
||||
triggerOutboundCall: expect.any(Function),
|
||||
createWebhook: expect.any(Function),
|
||||
subscribeToWebhooks: expect.any(Function),
|
||||
deleteWebhook: expect.any(Function),
|
||||
validateWebhook: expect.any(Function),
|
||||
parseWebhookEvent: expect.any(Function),
|
||||
normalizeWebhook: expect.any(Function),
|
||||
getRecordingUrl: expect.any(Function),
|
||||
});
|
||||
});
|
||||
|
||||
it("probes V1 ping and maps a valid permanent bearer token to active", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(aircallAdapter.validateConnection({ accessToken: "permanent-token" })).resolves.toEqual({
|
||||
ok: true,
|
||||
health: "active",
|
||||
messageKey: "telephony.health.active",
|
||||
});
|
||||
expect(new URL(String(fetchMock.mock.calls[0]?.[0])).pathname).toBe("/v1/ping");
|
||||
});
|
||||
|
||||
it("maps a missing token to a Klartext-ready broken state", async () => {
|
||||
await expect(aircallAdapter.healthCheck({ accessToken: null })).resolves.toEqual({
|
||||
ok: false,
|
||||
health: "broken",
|
||||
messageKey: "telephony.health.tokenInvalid",
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,84 @@
|
||||
import {
|
||||
registerIntegrationAdapter,
|
||||
type AdapterResult,
|
||||
type AdapterSyncOutcome,
|
||||
type IntegrationAdapter,
|
||||
} from "@hivegrid/foundation";
|
||||
|
||||
import type { TelephonyProviderInterface } from "../telephony/provider.js";
|
||||
import {
|
||||
createAircallWebhook,
|
||||
deleteAircallWebhook,
|
||||
listAircallUserNumbers,
|
||||
listAircallUsers,
|
||||
pingAircall,
|
||||
startAircallOutboundCall,
|
||||
} from "./client.js";
|
||||
import { AircallError, type AircallCredentials } from "./types.js";
|
||||
import {
|
||||
getAircallRecordingUrl,
|
||||
normalizeAircallWebhook,
|
||||
parseAircallWebhookEvent,
|
||||
validateAircallWebhook,
|
||||
} from "./webhook.js";
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof AircallError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_invalid":
|
||||
return { ok: false, health: "broken", messageKey: "telephony.health.tokenInvalid" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "telephony.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "telephony.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "telephony.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "telephony.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "telephony.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(credentials: AircallCredentials): Promise<AdapterResult> {
|
||||
try {
|
||||
await pingAircall(credentials);
|
||||
return { ok: true, health: "active", messageKey: "telephony.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const aircallAdapter: IntegrationAdapter<AircallCredentials> = registerIntegrationAdapter<AircallCredentials>({
|
||||
key: "aircall",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
// Aircall's telephony event engine owns domain processing. The generic sync
|
||||
// is intentionally a no-op, and no refreshToken method exists because the
|
||||
// documented Aircall OAuth access token is permanent.
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [],
|
||||
summaryKey: "telephony.sync.summary.webhookEngine",
|
||||
}),
|
||||
});
|
||||
|
||||
export const aircallTelephonyProvider: TelephonyProviderInterface<AircallCredentials> = {
|
||||
key: "aircall",
|
||||
connect: pingAircall,
|
||||
disconnect: (credentials, webhookId) => webhookId ? deleteAircallWebhook(credentials, webhookId) : Promise.resolve(),
|
||||
probe: pingAircall,
|
||||
listUsers: listAircallUsers,
|
||||
listProviderUsers: listAircallUsers,
|
||||
listUserNumbers: listAircallUserNumbers,
|
||||
startCall: startAircallOutboundCall,
|
||||
triggerOutboundCall: startAircallOutboundCall,
|
||||
createWebhook: createAircallWebhook,
|
||||
subscribeToWebhooks: createAircallWebhook,
|
||||
deleteWebhook: deleteAircallWebhook,
|
||||
validateWebhook: validateAircallWebhook,
|
||||
parseWebhookEvent: parseAircallWebhookEvent,
|
||||
normalizeWebhook: normalizeAircallWebhook,
|
||||
getRecordingUrl: getAircallRecordingUrl,
|
||||
};
|
||||
+200
@@ -0,0 +1,200 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
AIRCALL_OAUTH_AUTHORIZE_URL,
|
||||
buildAircallAuthorizationUrl,
|
||||
createAircallWebhook,
|
||||
exchangeAircallCodeForToken,
|
||||
listAircallUserNumbers,
|
||||
listAircallUsers,
|
||||
pingAircall,
|
||||
startAircallOutboundCall,
|
||||
} from "./client.js";
|
||||
import { AircallError } from "./types.js";
|
||||
|
||||
const CREDENTIALS = { accessToken: "permanent-aircall-access-token" } as const;
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe("Aircall OAuth and Public API client", () => {
|
||||
it("builds the official public_api consent URL with CSRF state", () => {
|
||||
const url = new URL(
|
||||
buildAircallAuthorizationUrl(
|
||||
{ clientId: "client-1", clientSecret: "client-secret", redirectUri: "https://app.example.test/integrations/aircall/oauth/callback" },
|
||||
"signed-state",
|
||||
),
|
||||
);
|
||||
expect(`${url.origin}${url.pathname}`).toBe(AIRCALL_OAUTH_AUTHORIZE_URL);
|
||||
expect(Object.fromEntries(url.searchParams)).toEqual({
|
||||
client_id: "client-1",
|
||||
redirect_uri: "https://app.example.test/integrations/aircall/oauth/callback",
|
||||
response_type: "code",
|
||||
scope: "public_api",
|
||||
state: "signed-state",
|
||||
});
|
||||
});
|
||||
|
||||
it("exchanges a code for a permanent access token without inventing a refresh token", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ access_token: "aircall-token" }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
const tokenSet = await exchangeAircallCodeForToken(
|
||||
{ clientId: "client-1", clientSecret: "client-secret", redirectUri: "https://app.example.test/callback" },
|
||||
"authorization-code",
|
||||
);
|
||||
|
||||
expect(tokenSet).toEqual({ accessToken: "aircall-token" });
|
||||
expect(tokenSet).not.toHaveProperty("refreshToken");
|
||||
const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
|
||||
expect(init.method).toBe("POST");
|
||||
expect(init.headers).toEqual({ "content-type": "application/json" });
|
||||
expect(JSON.parse(String(init.body))).toEqual({
|
||||
code: "authorization-code",
|
||||
redirect_uri: "https://app.example.test/callback",
|
||||
client_id: "client-1",
|
||||
client_secret: "client-secret",
|
||||
grant_type: "authorization_code",
|
||||
});
|
||||
});
|
||||
|
||||
it("uses User V2 and its dedicated numbers endpoint", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
meta: { current_page: 1, next_page_link: null },
|
||||
users: [
|
||||
{
|
||||
id: 456,
|
||||
name: "Ada Agent",
|
||||
email: "ADA@example.test",
|
||||
available: true,
|
||||
availability_status: "available",
|
||||
default_number_id: 673,
|
||||
},
|
||||
],
|
||||
}),
|
||||
)
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
meta: { current_page: 1, next_page_link: null },
|
||||
numbers: [{ id: 673, name: "Berlin", digits: "+49 30 123 45", country: "de", availability_status: "open" }],
|
||||
}),
|
||||
);
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(listAircallUsers(CREDENTIALS)).resolves.toEqual([
|
||||
{
|
||||
id: "456",
|
||||
name: "Ada Agent",
|
||||
email: "ada@example.test",
|
||||
available: true,
|
||||
availabilityStatus: "available",
|
||||
defaultNumberId: "673",
|
||||
},
|
||||
]);
|
||||
await expect(listAircallUserNumbers(CREDENTIALS, "456")).resolves.toEqual([
|
||||
{ id: "673", label: "Berlin", e164: "+493012345", countryCode: "DE", availabilityStatus: "open" },
|
||||
]);
|
||||
|
||||
expect(new URL(String(fetchMock.mock.calls[0]?.[0])).pathname).toBe("/v2/users");
|
||||
expect(new URL(String(fetchMock.mock.calls[1]?.[0])).pathname).toBe("/v2/users/456/numbers");
|
||||
for (const [, init] of fetchMock.mock.calls as Array<[string, RequestInit]>) {
|
||||
expect(init.headers).toMatchObject({ authorization: `Bearer ${CREDENTIALS.accessToken}` });
|
||||
}
|
||||
});
|
||||
|
||||
it("probes the permanent bearer token through the documented V1 ping endpoint", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ status: "ok" }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(pingAircall(CREDENTIALS)).resolves.toBeUndefined();
|
||||
|
||||
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe("https://api.aircall.io/v1/ping");
|
||||
expect(init.headers).toMatchObject({ authorization: `Bearer ${CREDENTIALS.accessToken}` });
|
||||
});
|
||||
|
||||
it("posts click-to-call to the documented V1 endpoint with number_id and E.164 destination", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(startAircallOutboundCall(CREDENTIALS, { userId: "456", numberId: "673", to: "+49301234567" })).resolves.toEqual({ accepted: true });
|
||||
|
||||
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe("https://api.aircall.io/v1/users/456/calls");
|
||||
expect(init.method).toBe("POST");
|
||||
expect(init.headers).toMatchObject({ authorization: `Bearer ${CREDENTIALS.accessToken}`, "content-type": "application/json" });
|
||||
expect(JSON.parse(String(init.body))).toEqual({ number_id: 673, to: "+49301234567" });
|
||||
});
|
||||
|
||||
it("creates a webhook and returns the provider token only to the credential boundary", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(
|
||||
jsonResponse(
|
||||
{
|
||||
webhook: {
|
||||
webhook_id: "4df567a2-41a4-4d49-91be-2c139344471c",
|
||||
token: "provider-webhook-token",
|
||||
active: true,
|
||||
events: ["call.created", "call.ended"],
|
||||
},
|
||||
},
|
||||
201,
|
||||
),
|
||||
);
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(
|
||||
createAircallWebhook(CREDENTIALS, {
|
||||
name: "HiveGrid",
|
||||
url: "https://api.example.test/v1/webhooks/telephony/aircall",
|
||||
events: ["call.created", "call.ended"],
|
||||
}),
|
||||
).resolves.toEqual({
|
||||
id: "4df567a2-41a4-4d49-91be-2c139344471c",
|
||||
token: "provider-webhook-token",
|
||||
active: true,
|
||||
events: ["call.created", "call.ended"],
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects unsupported webhook events before sending credentials", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(
|
||||
createAircallWebhook(CREDENTIALS, {
|
||||
name: "HiveGrid",
|
||||
url: "https://api.example.test/v1/webhooks/telephony/aircall",
|
||||
events: ["contact.created"],
|
||||
}),
|
||||
).rejects.toMatchObject({ code: "invalid_request" });
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("maps provider failures without copying bearer tokens or response diagnostics", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(jsonResponse({ troubleshoot: `invalid ${CREDENTIALS.accessToken}` }, 401));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
const error = await listAircallUsers(CREDENTIALS).catch((caught: unknown) => caught);
|
||||
expect(error).toBeInstanceOf(AircallError);
|
||||
expect(error).toMatchObject({ code: "auth_token_invalid", httpStatus: 401 });
|
||||
expect(String(error)).not.toContain(CREDENTIALS.accessToken);
|
||||
expect(JSON.stringify(error)).not.toContain(CREDENTIALS.accessToken);
|
||||
});
|
||||
|
||||
it("rejects non-E.164 destinations before sending credentials", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
await expect(startAircallOutboundCall(CREDENTIALS, { userId: "456", numberId: "673", to: "030 12345" })).rejects.toMatchObject({
|
||||
code: "invalid_request",
|
||||
});
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
function jsonResponse(body: unknown, status = 200): Response {
|
||||
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
|
||||
}
|
||||
@@ -0,0 +1,260 @@
|
||||
import type {
|
||||
TelephonyProviderNumber,
|
||||
TelephonyProviderUser,
|
||||
TelephonyStartCallInput,
|
||||
TelephonyStartCallResult,
|
||||
TelephonyWebhookRegistration,
|
||||
TelephonyWebhookRegistrationInput,
|
||||
} from "../telephony/provider.js";
|
||||
import { fetchProvider, readProviderJson } from "../provider-http.js";
|
||||
import {
|
||||
AircallError,
|
||||
type AircallCredentials,
|
||||
type AircallNumber,
|
||||
type AircallOAuthConfig,
|
||||
type AircallPaginationMeta,
|
||||
type AircallTokenSet,
|
||||
type AircallUserV2,
|
||||
type AircallWebhookRecord,
|
||||
AIRCALL_CALL_WEBHOOK_EVENTS,
|
||||
} from "./types.js";
|
||||
|
||||
export const AIRCALL_API_BASE = "https://api.aircall.io";
|
||||
export const AIRCALL_OAUTH_AUTHORIZE_URL = "https://dashboard.aircall.io/oauth/authorize";
|
||||
export const AIRCALL_OAUTH_TOKEN_URL = `${AIRCALL_API_BASE}/v1/oauth/token`;
|
||||
export const AIRCALL_OAUTH_SCOPE = "public_api";
|
||||
|
||||
const DEFAULT_PAGE_SIZE = 50;
|
||||
const DEFAULT_MAX_PAGES = 20;
|
||||
const E164_PATTERN = /^\+[1-9]\d{1,14}$/u;
|
||||
const PROVIDER_ID_PATTERN = /^\d+$/u;
|
||||
const WEBHOOK_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/u;
|
||||
const SUPPORTED_WEBHOOK_EVENTS = new Set<string>(AIRCALL_CALL_WEBHOOK_EVENTS);
|
||||
|
||||
type PageOptions = { readonly perPage?: number; readonly maxPages?: number };
|
||||
|
||||
export function resolveAircallOAuthConfig(env: NodeJS.ProcessEnv = process.env): AircallOAuthConfig | null {
|
||||
const clientId = env.AIRCALL_CLIENT_ID;
|
||||
const clientSecret = env.AIRCALL_CLIENT_SECRET;
|
||||
const redirectUri = env.AIRCALL_REDIRECT_URI;
|
||||
if (!clientId || !clientSecret || !redirectUri) return null;
|
||||
return { clientId, clientSecret, redirectUri };
|
||||
}
|
||||
|
||||
/** Build Aircall's consent URL. `state` must be a signed tenant/user token. */
|
||||
export function buildAircallAuthorizationUrl(config: AircallOAuthConfig, state: string): string {
|
||||
const params = new URLSearchParams({
|
||||
client_id: config.clientId,
|
||||
redirect_uri: config.redirectUri,
|
||||
response_type: "code",
|
||||
scope: AIRCALL_OAUTH_SCOPE,
|
||||
state,
|
||||
});
|
||||
return `${AIRCALL_OAUTH_AUTHORIZE_URL}?${params.toString()}`;
|
||||
}
|
||||
|
||||
/** Exchange a short-lived authorization code for Aircall's permanent token. */
|
||||
export async function exchangeAircallCodeForToken(config: AircallOAuthConfig, code: string): Promise<AircallTokenSet> {
|
||||
const response = await fetchProvider(AIRCALL_OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
code,
|
||||
redirect_uri: config.redirectUri,
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
grant_type: "authorization_code",
|
||||
}),
|
||||
});
|
||||
const body = await readProviderJson<{ access_token?: string }>(response);
|
||||
if (!response.ok || !body.access_token) throw mapAircallError(response.status);
|
||||
return { accessToken: body.access_token };
|
||||
}
|
||||
|
||||
/** Verify the permanent bearer token against Aircall's lightweight health endpoint. */
|
||||
export async function pingAircall(credentials: AircallCredentials): Promise<void> {
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v1/ping`, {
|
||||
headers: bearerHeaders(accessToken),
|
||||
});
|
||||
if (!response.ok) throw mapAircallError(response.status);
|
||||
}
|
||||
|
||||
export async function listAircallUsers(credentials: AircallCredentials, options: PageOptions = {}): Promise<readonly TelephonyProviderUser[]> {
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
const perPage = boundedInteger(options.perPage, DEFAULT_PAGE_SIZE, 1, 50);
|
||||
const maxPages = boundedInteger(options.maxPages, DEFAULT_MAX_PAGES, 1, 100);
|
||||
const users: TelephonyProviderUser[] = [];
|
||||
|
||||
for (let page = 1; page <= maxPages; page += 1) {
|
||||
const params = new URLSearchParams({ page: String(page), per_page: String(perPage), order: "asc" });
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v2/users?${params.toString()}`, {
|
||||
headers: bearerHeaders(accessToken),
|
||||
});
|
||||
const body = await readProviderJson<{ meta?: AircallPaginationMeta; users?: AircallUserV2[] }>(response);
|
||||
if (!response.ok) throw mapAircallError(response.status);
|
||||
users.push(...(body.users ?? []).map(toProviderUser).filter(isPresent));
|
||||
if (!body.meta?.next_page_link) break;
|
||||
}
|
||||
|
||||
return users;
|
||||
}
|
||||
|
||||
export async function listAircallUserNumbers(
|
||||
credentials: AircallCredentials,
|
||||
userId: string,
|
||||
options: PageOptions = {},
|
||||
): Promise<readonly TelephonyProviderNumber[]> {
|
||||
assertProviderId(userId, "user");
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
const perPage = boundedInteger(options.perPage, DEFAULT_PAGE_SIZE, 1, 50);
|
||||
const maxPages = boundedInteger(options.maxPages, DEFAULT_MAX_PAGES, 1, 100);
|
||||
const numbers: TelephonyProviderNumber[] = [];
|
||||
|
||||
for (let page = 1; page <= maxPages; page += 1) {
|
||||
const params = new URLSearchParams({ page: String(page), per_page: String(perPage), order: "asc" });
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v2/users/${encodeURIComponent(userId)}/numbers?${params.toString()}`, {
|
||||
headers: bearerHeaders(accessToken),
|
||||
});
|
||||
const body = await readProviderJson<{ meta?: AircallPaginationMeta; numbers?: AircallNumber[] }>(response);
|
||||
if (!response.ok) throw mapAircallError(response.status);
|
||||
numbers.push(...(body.numbers ?? []).map(toProviderNumber).filter(isPresent));
|
||||
if (!body.meta?.next_page_link) break;
|
||||
}
|
||||
|
||||
return numbers;
|
||||
}
|
||||
|
||||
/** Aircall accepts this command only for an available desktop Workspace user. */
|
||||
export async function startAircallOutboundCall(
|
||||
credentials: AircallCredentials,
|
||||
input: TelephonyStartCallInput,
|
||||
): Promise<TelephonyStartCallResult> {
|
||||
assertProviderId(input.userId, "user");
|
||||
assertProviderId(input.numberId, "number");
|
||||
if (!E164_PATTERN.test(input.to)) throw new AircallError("invalid_request");
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v1/users/${encodeURIComponent(input.userId)}/calls`, {
|
||||
method: "POST",
|
||||
headers: bearerHeaders(accessToken, true),
|
||||
body: JSON.stringify({ number_id: Number(input.numberId), to: input.to }),
|
||||
});
|
||||
if (!response.ok) throw mapAircallError(response.status);
|
||||
return { accepted: true };
|
||||
}
|
||||
|
||||
export async function createAircallWebhook(
|
||||
credentials: AircallCredentials,
|
||||
input: TelephonyWebhookRegistrationInput,
|
||||
): Promise<TelephonyWebhookRegistration> {
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
assertHttpsUrl(input.url);
|
||||
const name = input.name.trim();
|
||||
if (!name || input.events.length === 0 || input.events.some((event) => !SUPPORTED_WEBHOOK_EVENTS.has(event))) {
|
||||
throw new AircallError("invalid_request");
|
||||
}
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v1/webhooks`, {
|
||||
method: "POST",
|
||||
headers: bearerHeaders(accessToken, true),
|
||||
body: JSON.stringify({ custom_name: name, url: input.url, events: [...input.events] }),
|
||||
});
|
||||
const body = await readProviderJson<{ webhook?: AircallWebhookRecord }>(response);
|
||||
if (!response.ok) throw mapAircallError(response.status);
|
||||
const webhook = body.webhook;
|
||||
const id = stringId(webhook?.webhook_id ?? webhook?.id);
|
||||
if (!id || !webhook?.token) throw new AircallError("unknown", response.status);
|
||||
return { id, token: webhook.token, active: webhook.active ?? true, events: webhook.events ?? [...input.events] };
|
||||
}
|
||||
|
||||
export async function deleteAircallWebhook(credentials: AircallCredentials, webhookId: string): Promise<void> {
|
||||
if (!WEBHOOK_ID_PATTERN.test(webhookId)) throw new AircallError("invalid_request");
|
||||
const accessToken = requireAccessToken(credentials);
|
||||
const response = await fetchProvider(`${AIRCALL_API_BASE}/v1/webhooks/${encodeURIComponent(webhookId)}`, {
|
||||
method: "DELETE",
|
||||
headers: bearerHeaders(accessToken, true),
|
||||
});
|
||||
if (response.ok || response.status === 404) return;
|
||||
throw mapAircallError(response.status);
|
||||
}
|
||||
|
||||
function bearerHeaders(accessToken: string, json = false): Record<string, string> {
|
||||
return { authorization: `Bearer ${accessToken}`, ...(json ? { "content-type": "application/json" } : {}) };
|
||||
}
|
||||
|
||||
function requireAccessToken(credentials: AircallCredentials): string {
|
||||
const accessToken = credentials.accessToken?.trim();
|
||||
if (!accessToken) throw new AircallError("auth_token_invalid");
|
||||
return accessToken;
|
||||
}
|
||||
|
||||
function assertProviderId(id: string, kind: "user" | "number"): void {
|
||||
if (!PROVIDER_ID_PATTERN.test(id)) throw new AircallError("invalid_request", undefined);
|
||||
if (kind === "number" && !Number.isSafeInteger(Number(id))) throw new AircallError("invalid_request");
|
||||
}
|
||||
|
||||
function assertHttpsUrl(value: string): void {
|
||||
try {
|
||||
if (new URL(value).protocol !== "https:") throw new Error("not https");
|
||||
} catch {
|
||||
throw new AircallError("invalid_request");
|
||||
}
|
||||
}
|
||||
|
||||
function boundedInteger(value: number | undefined, fallback: number, min: number, max: number): number {
|
||||
return Number.isSafeInteger(value) && value! >= min && value! <= max ? value! : fallback;
|
||||
}
|
||||
|
||||
function stringId(value: number | string | null | undefined): string | null {
|
||||
if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
|
||||
if (typeof value === "string" && value.trim()) return value.trim();
|
||||
return null;
|
||||
}
|
||||
|
||||
function normalizeE164(value: string | undefined): string {
|
||||
if (!value) return "";
|
||||
const normalized = value.replace(/[^+\d]/gu, "").replace(/(?!^)\+/gu, "");
|
||||
return E164_PATTERN.test(normalized) ? normalized : "";
|
||||
}
|
||||
|
||||
function toProviderUser(value: AircallUserV2): TelephonyProviderUser | null {
|
||||
const id = stringId(value.id);
|
||||
if (!id || !value.email) return null;
|
||||
return {
|
||||
id,
|
||||
name: value.name?.trim() || value.email,
|
||||
email: value.email.trim().toLowerCase(),
|
||||
available: value.available ?? false,
|
||||
availabilityStatus: value.availability_status?.trim() || null,
|
||||
defaultNumberId: stringId(value.default_number_id),
|
||||
};
|
||||
}
|
||||
|
||||
function toProviderNumber(value: AircallNumber): TelephonyProviderNumber | null {
|
||||
const id = stringId(value.id);
|
||||
const e164 = normalizeE164(value.e164_digits || value.digits);
|
||||
if (!id || !e164) return null;
|
||||
return {
|
||||
id,
|
||||
label: value.name?.trim() || e164,
|
||||
e164,
|
||||
countryCode: value.country?.trim().toUpperCase() || null,
|
||||
// Aircall's legacy `open` flag does not reliably describe Smartflows.
|
||||
// Preserve the provider hint rather than deriving a misleading boolean.
|
||||
availabilityStatus: value.availability_status?.trim() || null,
|
||||
};
|
||||
}
|
||||
|
||||
function mapAircallError(status: number): AircallError {
|
||||
if (status === 401) return new AircallError("auth_token_invalid", status);
|
||||
if (status === 403) return new AircallError("auth_scope_missing", status);
|
||||
if (status === 429) return new AircallError("rate_limit_exceeded", status);
|
||||
if (status === 400 || status === 422) return new AircallError("invalid_request", status);
|
||||
if (status === 404) return new AircallError("not_found", status);
|
||||
if (status === 405) return new AircallError("user_unavailable", status);
|
||||
if (status >= 500) return new AircallError("provider_outage", status);
|
||||
return new AircallError("unknown", status);
|
||||
}
|
||||
|
||||
function isPresent<T>(value: T | null): value is T {
|
||||
return value !== null;
|
||||
}
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
import type { AircallCallWebhookEventName, AircallWebhookPayload } from "./types.js";
|
||||
|
||||
/** Non-secret token used only by provider-contract tests. */
|
||||
export const AIRCALL_TEST_WEBHOOK_TOKEN = "fixture-aircall-webhook-token";
|
||||
|
||||
export const AIRCALL_ENDED_WEBHOOK_FIXTURE: AircallWebhookPayload = {
|
||||
resource: "call",
|
||||
event: "call.ended",
|
||||
timestamp: 1_725_000_030,
|
||||
token: AIRCALL_TEST_WEBHOOK_TOKEN,
|
||||
data: {
|
||||
id: 81_200,
|
||||
direction: "inbound",
|
||||
status: "done",
|
||||
missed_call_reason: null,
|
||||
started_at: 1_725_000_000,
|
||||
answered_at: 1_725_000_005,
|
||||
ended_at: 1_725_000_030,
|
||||
duration: 30,
|
||||
raw_digits: "+49 30 123 45 67",
|
||||
recording: "https://assets.aircall.test/recordings/call-81200.mp3",
|
||||
user: { id: 456, name: "Ada Agent", email: "Ada.Agent@example.test" },
|
||||
number: { id: 673, digits: "+49 30 987 65 4", e164_digits: "+4930987654" },
|
||||
},
|
||||
};
|
||||
|
||||
export const AIRCALL_MISSED_WEBHOOK_FIXTURE: AircallWebhookPayload = {
|
||||
resource: "call",
|
||||
event: "call.ended",
|
||||
timestamp: 1_725_000_120,
|
||||
token: AIRCALL_TEST_WEBHOOK_TOKEN,
|
||||
data: {
|
||||
id: 81_201,
|
||||
direction: "inbound",
|
||||
status: "done",
|
||||
missed_call_reason: "no_available_agent",
|
||||
started_at: 1_725_000_100,
|
||||
answered_at: null,
|
||||
ended_at: 1_725_000_120,
|
||||
duration: 20,
|
||||
raw_digits: "+49307654321",
|
||||
user: null,
|
||||
number: { id: 673, e164_digits: "+4930987654" },
|
||||
},
|
||||
};
|
||||
|
||||
const AIRCALL_LIFECYCLE_BASE_DATA = {
|
||||
id: 81_202,
|
||||
direction: "inbound",
|
||||
status: "initializing",
|
||||
missed_call_reason: null,
|
||||
started_at: 1_725_000_200,
|
||||
answered_at: null,
|
||||
ended_at: null,
|
||||
duration: 0,
|
||||
raw_digits: "+493011122233",
|
||||
user: { id: 457, name: "Berta Agent", email: "berta.agent@example.test" },
|
||||
number: { id: 674, e164_digits: "+493044455566" },
|
||||
} as const;
|
||||
|
||||
function lifecycleFixture(
|
||||
event: AircallCallWebhookEventName,
|
||||
timestamp: number,
|
||||
data: Record<string, unknown> = {},
|
||||
): AircallWebhookPayload {
|
||||
return {
|
||||
resource: "call",
|
||||
event,
|
||||
timestamp,
|
||||
token: AIRCALL_TEST_WEBHOOK_TOKEN,
|
||||
data: { ...AIRCALL_LIFECYCLE_BASE_DATA, ...data },
|
||||
};
|
||||
}
|
||||
|
||||
/** Deterministic contract fixtures for every Aircall event consumed by AK-P15a. */
|
||||
export const AIRCALL_WEBHOOK_FIXTURES = {
|
||||
"call.created": lifecycleFixture("call.created", 1_725_000_200),
|
||||
"call.ringing_on_agent": lifecycleFixture("call.ringing_on_agent", 1_725_000_201, { status: "ringing" }),
|
||||
"call.agent_declined": lifecycleFixture("call.agent_declined", 1_725_000_202, { status: "agent_declined" }),
|
||||
"call.answered": lifecycleFixture("call.answered", 1_725_000_205, {
|
||||
status: "answered",
|
||||
answered_at: 1_725_000_205,
|
||||
duration: 5,
|
||||
}),
|
||||
"call.hungup": lifecycleFixture("call.hungup", 1_725_000_229, {
|
||||
status: "hungup",
|
||||
answered_at: 1_725_000_205,
|
||||
duration: 29,
|
||||
}),
|
||||
"call.ended": AIRCALL_ENDED_WEBHOOK_FIXTURE,
|
||||
"call.voicemail_left": lifecycleFixture("call.voicemail_left", 1_725_000_230, {
|
||||
status: "voicemail",
|
||||
missed_call_reason: "voicemail",
|
||||
ended_at: 1_725_000_230,
|
||||
duration: 30,
|
||||
asset: "https://assets.aircall.test/voicemails/call-81202.mp3",
|
||||
}),
|
||||
"call.comm_assets_generated": lifecycleFixture("call.comm_assets_generated", 1_725_000_231, {
|
||||
status: "done",
|
||||
answered_at: 1_725_000_205,
|
||||
ended_at: 1_725_000_230,
|
||||
duration: 30,
|
||||
asset: "https://assets.aircall.test/recordings/call-81202.mp3",
|
||||
}),
|
||||
} satisfies Readonly<Record<AircallCallWebhookEventName, AircallWebhookPayload>>;
|
||||
@@ -0,0 +1,4 @@
|
||||
export * from "./adapter.js";
|
||||
export * from "./client.js";
|
||||
export * from "./types.js";
|
||||
export * from "./webhook.js";
|
||||
@@ -0,0 +1,127 @@
|
||||
import type { TelephonyCallEventType } from "../telephony/provider.js";
|
||||
|
||||
/** Decrypted OAuth credential shape. Aircall access tokens are permanent. */
|
||||
export interface AircallCredentials {
|
||||
readonly accessToken?: string | null;
|
||||
}
|
||||
|
||||
export interface AircallOAuthConfig {
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
readonly redirectUri: string;
|
||||
}
|
||||
|
||||
export interface AircallTokenSet {
|
||||
readonly accessToken: string;
|
||||
}
|
||||
|
||||
export type AircallErrorCode =
|
||||
| "auth_token_invalid"
|
||||
| "auth_scope_missing"
|
||||
| "rate_limit_exceeded"
|
||||
| "invalid_request"
|
||||
| "not_found"
|
||||
| "user_unavailable"
|
||||
| "provider_outage"
|
||||
| "not_configured"
|
||||
| "unknown";
|
||||
|
||||
export class AircallError extends Error {
|
||||
readonly code: AircallErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
|
||||
constructor(code: AircallErrorCode, httpStatus?: number) {
|
||||
// Provider response bodies can contain sensitive diagnostics. Never attach
|
||||
// them to an exception that could be logged by an application boundary.
|
||||
super(code);
|
||||
this.name = "AircallError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
}
|
||||
}
|
||||
|
||||
export interface AircallPaginationMeta {
|
||||
readonly count?: number;
|
||||
readonly total?: number;
|
||||
readonly current_page?: number;
|
||||
readonly per_page?: number;
|
||||
readonly next_page_link?: string | null;
|
||||
}
|
||||
|
||||
export interface AircallUserV2 {
|
||||
readonly id?: number | string;
|
||||
readonly name?: string;
|
||||
readonly email?: string;
|
||||
readonly available?: boolean;
|
||||
readonly availability_status?: string;
|
||||
readonly default_number_id?: number | string | null;
|
||||
}
|
||||
|
||||
export interface AircallNumber {
|
||||
readonly id?: number | string;
|
||||
readonly name?: string;
|
||||
readonly digits?: string;
|
||||
readonly e164_digits?: string;
|
||||
readonly country?: string;
|
||||
readonly availability_status?: string;
|
||||
readonly open?: boolean;
|
||||
}
|
||||
|
||||
export interface AircallWebhookRecord {
|
||||
readonly webhook_id?: string | number;
|
||||
readonly id?: string | number;
|
||||
readonly token?: string;
|
||||
readonly active?: boolean;
|
||||
readonly events?: string[];
|
||||
}
|
||||
|
||||
export interface AircallCallData {
|
||||
readonly id?: number | string;
|
||||
readonly direction?: string;
|
||||
readonly status?: string;
|
||||
readonly missed_call_reason?: string | null;
|
||||
readonly started_at?: number | string | null;
|
||||
readonly answered_at?: number | string | null;
|
||||
readonly ended_at?: number | string | null;
|
||||
readonly duration?: number | string | null;
|
||||
readonly recording?: string | null;
|
||||
readonly recording_short_url?: string | null;
|
||||
readonly voicemail?: string | null;
|
||||
readonly voicemail_short_url?: string | null;
|
||||
readonly asset?: string | null;
|
||||
readonly raw_digits?: string | null;
|
||||
readonly user?: { readonly id?: number | string; readonly email?: string; readonly name?: string } | null;
|
||||
readonly number?: { readonly id?: number | string; readonly digits?: string; readonly e164_digits?: string } | null;
|
||||
}
|
||||
|
||||
export interface AircallWebhookPayload {
|
||||
readonly resource?: string;
|
||||
readonly event?: string;
|
||||
readonly timestamp?: number | string;
|
||||
readonly token?: string;
|
||||
readonly data?: AircallCallData;
|
||||
}
|
||||
|
||||
export const AIRCALL_CALL_WEBHOOK_EVENTS = [
|
||||
"call.created",
|
||||
"call.ringing_on_agent",
|
||||
"call.agent_declined",
|
||||
"call.answered",
|
||||
"call.hungup",
|
||||
"call.ended",
|
||||
"call.voicemail_left",
|
||||
"call.comm_assets_generated",
|
||||
] as const;
|
||||
|
||||
export type AircallCallWebhookEventName = (typeof AIRCALL_CALL_WEBHOOK_EVENTS)[number];
|
||||
|
||||
export const AIRCALL_CALL_EVENT_TYPE: Readonly<Record<AircallCallWebhookEventName, TelephonyCallEventType>> = {
|
||||
"call.created": "created",
|
||||
"call.ringing_on_agent": "ringing",
|
||||
"call.agent_declined": "agent_declined",
|
||||
"call.answered": "answered",
|
||||
"call.hungup": "hungup",
|
||||
"call.ended": "ended",
|
||||
"call.voicemail_left": "voicemail",
|
||||
"call.comm_assets_generated": "assets_ready",
|
||||
};
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
AIRCALL_ENDED_WEBHOOK_FIXTURE,
|
||||
AIRCALL_MISSED_WEBHOOK_FIXTURE,
|
||||
AIRCALL_TEST_WEBHOOK_TOKEN,
|
||||
AIRCALL_WEBHOOK_FIXTURES,
|
||||
} from "./fixtures.js";
|
||||
import { AIRCALL_CALL_EVENT_TYPE } from "./types.js";
|
||||
import {
|
||||
getAircallRecordingUrl,
|
||||
normalizeAircallWebhook,
|
||||
parseAircallWebhookEvent,
|
||||
validateAircallWebhook,
|
||||
verifyAircallWebhookToken,
|
||||
} from "./webhook.js";
|
||||
|
||||
describe("Aircall webhook normalization", () => {
|
||||
it("normalizes a deterministic fixture for every subscribed Aircall event", () => {
|
||||
for (const [providerEvent, fixture] of Object.entries(AIRCALL_WEBHOOK_FIXTURES)) {
|
||||
const result = normalizeAircallWebhook(fixture, AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
event: {
|
||||
providerEvent,
|
||||
type: AIRCALL_CALL_EVENT_TYPE[providerEvent as keyof typeof AIRCALL_CALL_EVENT_TYPE],
|
||||
providerCallId: expect.any(String),
|
||||
},
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("validates the payload token exactly", () => {
|
||||
expect(verifyAircallWebhookToken(AIRCALL_TEST_WEBHOOK_TOKEN, AIRCALL_TEST_WEBHOOK_TOKEN)).toBe(true);
|
||||
expect(verifyAircallWebhookToken(`${AIRCALL_TEST_WEBHOOK_TOKEN}-other`, AIRCALL_TEST_WEBHOOK_TOKEN)).toBe(false);
|
||||
expect(verifyAircallWebhookToken(null, AIRCALL_TEST_WEBHOOK_TOKEN)).toBe(false);
|
||||
expect(validateAircallWebhook(AIRCALL_ENDED_WEBHOOK_FIXTURE, AIRCALL_TEST_WEBHOOK_TOKEN)).toBe(true);
|
||||
expect(validateAircallWebhook(AIRCALL_ENDED_WEBHOOK_FIXTURE, "wrong-token")).toBe(false);
|
||||
});
|
||||
|
||||
it("separates authenticated parsing and resolves the recording from normalized media", () => {
|
||||
const parsed = parseAircallWebhookEvent(AIRCALL_ENDED_WEBHOOK_FIXTURE);
|
||||
expect(parsed).toMatchObject({ ok: true, event: { type: "ended" } });
|
||||
if (!parsed.ok) throw new Error("fixture must parse");
|
||||
expect(getAircallRecordingUrl(parsed.event)).toBe("https://assets.aircall.test/recordings/call-81200.mp3");
|
||||
expect(JSON.stringify(parsed)).not.toContain(AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
});
|
||||
|
||||
it("normalizes call.ended and excludes the webhook token", () => {
|
||||
const result = normalizeAircallWebhook(AIRCALL_ENDED_WEBHOOK_FIXTURE, AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
expect(result).toEqual({
|
||||
ok: true,
|
||||
event: {
|
||||
provider: "aircall",
|
||||
providerEvent: "call.ended",
|
||||
type: "ended",
|
||||
dedupeKey: "aircall:call.ended:81200:1725000030:456",
|
||||
providerCallId: "81200",
|
||||
occurredAtIso: "2024-08-30T06:40:30.000Z",
|
||||
direction: "inbound",
|
||||
status: "done",
|
||||
externalNumber: "+49301234567",
|
||||
lineId: "673",
|
||||
lineNumber: "+4930987654",
|
||||
providerUserId: "456",
|
||||
providerUserEmail: "ada.agent@example.test",
|
||||
startedAtIso: "2024-08-30T06:40:00.000Z",
|
||||
answeredAtIso: "2024-08-30T06:40:05.000Z",
|
||||
endedAtIso: "2024-08-30T06:40:30.000Z",
|
||||
durationSeconds: 30,
|
||||
missed: false,
|
||||
missedReason: null,
|
||||
recordingUrl: "https://assets.aircall.test/recordings/call-81200.mp3",
|
||||
voicemailUrl: null,
|
||||
},
|
||||
});
|
||||
expect(JSON.stringify(result)).not.toContain(AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
});
|
||||
|
||||
it("marks an unanswered terminal inbound event as missed", () => {
|
||||
const result = normalizeAircallWebhook(AIRCALL_MISSED_WEBHOOK_FIXTURE, AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
event: { type: "ended", providerCallId: "81201", missed: true, missedReason: "no_available_agent" },
|
||||
});
|
||||
});
|
||||
|
||||
it("does not classify hungup or assets events as missed before call.ended", () => {
|
||||
for (const providerEvent of ["call.hungup", "call.comm_assets_generated"] as const) {
|
||||
const result = normalizeAircallWebhook(
|
||||
{
|
||||
...AIRCALL_MISSED_WEBHOOK_FIXTURE,
|
||||
event: providerEvent,
|
||||
data: { ...AIRCALL_MISSED_WEBHOOK_FIXTURE.data, ended_at: null },
|
||||
},
|
||||
AIRCALL_TEST_WEBHOOK_TOKEN,
|
||||
);
|
||||
expect(result).toMatchObject({ ok: true, event: { missed: false } });
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects a wrong token without reflecting it", () => {
|
||||
const result = normalizeAircallWebhook(AIRCALL_ENDED_WEBHOOK_FIXTURE, "different-expected-token");
|
||||
expect(result).toEqual({ ok: false, reason: "invalid_token" });
|
||||
expect(JSON.stringify(result)).not.toContain(AIRCALL_TEST_WEBHOOK_TOKEN);
|
||||
});
|
||||
|
||||
it("rejects non-call and unknown call events", () => {
|
||||
expect(
|
||||
normalizeAircallWebhook({ ...AIRCALL_ENDED_WEBHOOK_FIXTURE, resource: "contact", event: "contact.created" }, AIRCALL_TEST_WEBHOOK_TOKEN),
|
||||
).toEqual({ ok: false, reason: "unsupported_event" });
|
||||
expect(
|
||||
normalizeAircallWebhook({ ...AIRCALL_ENDED_WEBHOOK_FIXTURE, event: "call.future_event" }, AIRCALL_TEST_WEBHOOK_TOKEN),
|
||||
).toEqual({ ok: false, reason: "unsupported_event" });
|
||||
});
|
||||
});
|
||||
+144
@@ -0,0 +1,144 @@
|
||||
import { timingSafeEqual } from "node:crypto";
|
||||
|
||||
import type {
|
||||
TelephonyCallDirection,
|
||||
TelephonyCallEvent,
|
||||
TelephonyWebhookNormalizationResult,
|
||||
} from "../telephony/provider.js";
|
||||
import {
|
||||
AIRCALL_CALL_EVENT_TYPE,
|
||||
type AircallCallWebhookEventName,
|
||||
type AircallWebhookPayload,
|
||||
} from "./types.js";
|
||||
|
||||
const MAX_WEBHOOK_TOKEN_BYTES = 2_048;
|
||||
const E164_PATTERN = /^\+[1-9]\d{1,14}$/u;
|
||||
|
||||
/** Exact, constant-time comparison. Neither token is returned or logged. */
|
||||
export function verifyAircallWebhookToken(receivedToken: unknown, expectedToken: string): boolean {
|
||||
if (typeof receivedToken !== "string" || !receivedToken || !expectedToken) return false;
|
||||
const received = Buffer.from(receivedToken, "utf8");
|
||||
const expected = Buffer.from(expectedToken, "utf8");
|
||||
if (received.length > MAX_WEBHOOK_TOKEN_BYTES || expected.length > MAX_WEBHOOK_TOKEN_BYTES) return false;
|
||||
if (received.length !== expected.length) return false;
|
||||
return timingSafeEqual(received, expected);
|
||||
}
|
||||
|
||||
export function normalizeAircallWebhook(payload: unknown, expectedToken: string): TelephonyWebhookNormalizationResult {
|
||||
if (!isRecord(payload)) return { ok: false, reason: "invalid_payload" };
|
||||
if (!validateAircallWebhook(payload, expectedToken)) return { ok: false, reason: "invalid_token" };
|
||||
return parseAircallWebhookEvent(payload);
|
||||
}
|
||||
|
||||
/** Authenticate Aircall's body token without parsing or reflecting it. */
|
||||
export function validateAircallWebhook(payload: unknown, expectedToken: string): boolean {
|
||||
return isRecord(payload) && verifyAircallWebhookToken(payload.token, expectedToken);
|
||||
}
|
||||
|
||||
/** Parse a previously authenticated Aircall payload into the provider-neutral event. */
|
||||
export function parseAircallWebhookEvent(payload: unknown): TelephonyWebhookNormalizationResult {
|
||||
if (!isRecord(payload)) return { ok: false, reason: "invalid_payload" };
|
||||
const raw = payload as AircallWebhookPayload;
|
||||
if (raw.resource !== "call" || !isSupportedCallEvent(raw.event)) return { ok: false, reason: "unsupported_event" };
|
||||
if (!isRecord(raw.data)) return { ok: false, reason: "invalid_payload" };
|
||||
|
||||
const data = raw.data as AircallWebhookPayload["data"] & Record<string, unknown>;
|
||||
const user = isRecord(data.user) ? data.user : null;
|
||||
const number = isRecord(data.number) ? data.number : null;
|
||||
const providerCallId = stringValue(data.id);
|
||||
const occurredAtIso = unixTimestampToIso(raw.timestamp);
|
||||
if (!providerCallId || !occurredAtIso) return { ok: false, reason: "invalid_payload" };
|
||||
|
||||
const type = AIRCALL_CALL_EVENT_TYPE[raw.event];
|
||||
const direction = normalizeDirection(data.direction);
|
||||
const providerUserId = stringValue(user?.id);
|
||||
const answeredAtIso = unixTimestampToIso(data.answered_at);
|
||||
const missedReason = nullableString(data.missed_call_reason);
|
||||
const terminalEvent = type === "ended" || type === "voicemail";
|
||||
const event: TelephonyCallEvent = {
|
||||
provider: "aircall",
|
||||
providerEvent: raw.event,
|
||||
type,
|
||||
dedupeKey: ["aircall", raw.event, providerCallId, String(raw.timestamp), providerUserId ?? "-"].join(":"),
|
||||
providerCallId,
|
||||
occurredAtIso,
|
||||
direction,
|
||||
status: nullableString(data.status),
|
||||
externalNumber: normalizePhoneNumber(data.raw_digits),
|
||||
lineId: stringValue(number?.id),
|
||||
lineNumber: normalizePhoneNumber(number?.e164_digits) ?? normalizePhoneNumber(number?.digits),
|
||||
providerUserId,
|
||||
providerUserEmail: normalizeEmail(user?.email),
|
||||
startedAtIso: unixTimestampToIso(data.started_at),
|
||||
answeredAtIso,
|
||||
endedAtIso: unixTimestampToIso(data.ended_at),
|
||||
durationSeconds: nonNegativeInteger(data.duration),
|
||||
missed: terminalEvent && direction === "inbound" && (missedReason !== null || answeredAtIso === null),
|
||||
missedReason,
|
||||
recordingUrl: firstUrl(data.recording, data.recording_short_url, type === "assets_ready" ? data.asset : null),
|
||||
voicemailUrl: firstUrl(data.voicemail, data.voicemail_short_url, type === "voicemail" ? data.asset : null),
|
||||
};
|
||||
return { ok: true, event };
|
||||
}
|
||||
|
||||
/** Recording media is supplied by terminal/assets webhooks, not a second API. */
|
||||
export function getAircallRecordingUrl(event: TelephonyCallEvent): string | null {
|
||||
return event.recordingUrl ?? event.voicemailUrl;
|
||||
}
|
||||
|
||||
function isSupportedCallEvent(value: unknown): value is AircallCallWebhookEventName {
|
||||
return typeof value === "string" && Object.prototype.hasOwnProperty.call(AIRCALL_CALL_EVENT_TYPE, value);
|
||||
}
|
||||
|
||||
function normalizeDirection(value: unknown): TelephonyCallDirection {
|
||||
return value === "inbound" || value === "outbound" ? value : "unknown";
|
||||
}
|
||||
|
||||
function unixTimestampToIso(value: unknown): string | null {
|
||||
const numeric = typeof value === "string" && value.trim() ? Number(value) : value;
|
||||
if (typeof numeric !== "number" || !Number.isFinite(numeric) || numeric < 0) return null;
|
||||
const milliseconds = numeric >= 1_000_000_000_000 ? numeric : numeric * 1_000;
|
||||
const date = new Date(milliseconds);
|
||||
return Number.isNaN(date.getTime()) ? null : date.toISOString();
|
||||
}
|
||||
|
||||
function nonNegativeInteger(value: unknown): number | null {
|
||||
const numeric = typeof value === "string" && value.trim() ? Number(value) : value;
|
||||
return typeof numeric === "number" && Number.isSafeInteger(numeric) && numeric >= 0 ? numeric : null;
|
||||
}
|
||||
|
||||
function stringValue(value: unknown): string | null {
|
||||
if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
|
||||
return typeof value === "string" && value.trim() ? value.trim() : null;
|
||||
}
|
||||
|
||||
function nullableString(value: unknown): string | null {
|
||||
return typeof value === "string" && value.trim() ? value.trim() : null;
|
||||
}
|
||||
|
||||
function normalizeEmail(value: unknown): string | null {
|
||||
return typeof value === "string" && value.trim() ? value.trim().toLowerCase() : null;
|
||||
}
|
||||
|
||||
function normalizePhoneNumber(value: unknown): string | null {
|
||||
if (typeof value !== "string" || !value.trim()) return null;
|
||||
const normalized = value.trim().replace(/[^+\d]/gu, "").replace(/(?!^)\+/gu, "");
|
||||
return E164_PATTERN.test(normalized) ? normalized : null;
|
||||
}
|
||||
|
||||
function firstUrl(...values: unknown[]): string | null {
|
||||
for (const value of values) {
|
||||
if (typeof value !== "string" || !value) continue;
|
||||
try {
|
||||
const url = new URL(value);
|
||||
if (url.protocol === "https:") return url.toString();
|
||||
} catch {
|
||||
// Ignore malformed provider URLs instead of leaking them downstream.
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
+20
-3
@@ -42,7 +42,7 @@ vi.mock("@hivegrid/db/notifications.server", () => ({
|
||||
createNotificationDelivery: mocks.createNotificationDelivery,
|
||||
}));
|
||||
|
||||
function createClient(options: { mapping?: Record<string, unknown> | null; patchConflict?: boolean } = {}) {
|
||||
function createClient(options: { mapping?: Record<string, unknown> | null; patchConflict?: boolean; eventCount?: number } = {}) {
|
||||
const now = new Date("2026-06-30T10:00:00.000Z");
|
||||
const connection = {
|
||||
id: "conn_1",
|
||||
@@ -72,6 +72,10 @@ function createClient(options: { mapping?: Record<string, unknown> | null; patch
|
||||
versionToken: 1,
|
||||
archivedAt: null,
|
||||
};
|
||||
const events = Array.from({ length: options.eventCount ?? 1 }, (_, index) => ({
|
||||
...event,
|
||||
id: `event_${index + 1}`,
|
||||
}));
|
||||
const mapping = options.mapping ?? null;
|
||||
const client = {
|
||||
calendarConnection: {
|
||||
@@ -81,11 +85,11 @@ function createClient(options: { mapping?: Record<string, unknown> | null; patch
|
||||
update: vi.fn(async () => ({})),
|
||||
},
|
||||
calendarEvent: {
|
||||
findMany: vi.fn(async () => [event]),
|
||||
findMany: vi.fn(async () => events),
|
||||
upsert: vi.fn(async () => ({})),
|
||||
},
|
||||
calendarEventMapping: {
|
||||
findFirst: vi.fn(async () => mapping),
|
||||
findMany: vi.fn(async () => (mapping ? [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 })),
|
||||
@@ -124,6 +128,8 @@ describe("calendar worker write sync", () => {
|
||||
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(client.calendarConnection.findFirst).not.toHaveBeenCalled();
|
||||
expect(client.calendarEventMapping.findMany).toHaveBeenCalledOnce();
|
||||
expect(mocks.insertEvent).toHaveBeenCalledWith("access-token", "primary", expect.objectContaining({ summary: "Kundentermin" }));
|
||||
expect(client.calendarEventMapping.create).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
@@ -137,6 +143,17 @@ describe("calendar worker write sync", () => {
|
||||
);
|
||||
});
|
||||
|
||||
it("loads mappings for a full event batch with one database query", async () => {
|
||||
const client = createClient({ eventCount: 50 });
|
||||
|
||||
const result = await syncInternalCalendarEventsForTenant(client, "tenant_1", { now: new Date("2026-06-30T10:00:00.000Z"), take: 50 });
|
||||
|
||||
expect(result).toMatchObject({ scanned: 50, created: 50, updated: 0, failed: 0 });
|
||||
expect(client.calendarConnection.findFirst).not.toHaveBeenCalled();
|
||||
expect(client.calendarEventMapping.findMany).toHaveBeenCalledOnce();
|
||||
expect(mocks.insertEvent).toHaveBeenCalledTimes(50);
|
||||
});
|
||||
|
||||
it("logs and notifies a Last-Write-Wins conflict on provider etag mismatch", async () => {
|
||||
const client = createClient({
|
||||
mapping: {
|
||||
|
||||
+32
-23
@@ -85,7 +85,7 @@ export type CalendarWorkerClient = {
|
||||
upsert(args: Record<string, unknown>): Promise<unknown>;
|
||||
};
|
||||
calendarEventMapping: {
|
||||
findFirst(args: Record<string, unknown>): Promise<CalendarEventMappingRow | null>;
|
||||
findMany(args: Record<string, unknown>): Promise<CalendarEventMappingRow[]>;
|
||||
create(args: Record<string, unknown>): Promise<CalendarEventMappingRow>;
|
||||
update(args: Record<string, unknown>): Promise<CalendarEventMappingRow>;
|
||||
deleteMany(args: Record<string, unknown>): Promise<{ count: number }>;
|
||||
@@ -111,12 +111,8 @@ type CalendarCreds = {
|
||||
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) {
|
||||
async function decryptConnectionCreds(client: CalendarWorkerClient, tenantId: string, row: CalendarConnectionRow): Promise<CalendarCreds | null> {
|
||||
if (row.tenantId !== tenantId || !row.oauthRefreshTokenCiphertext || !row.oauthAccessTokenCiphertext) {
|
||||
return null;
|
||||
}
|
||||
const [refreshToken, accessToken] = await Promise.all([
|
||||
@@ -273,7 +269,7 @@ export async function refreshCalendarTokensForTenant(
|
||||
let refreshed = 0;
|
||||
let failed = 0;
|
||||
for (const row of rows) {
|
||||
const creds = await loadCreds(client, tenantId, row.id);
|
||||
const creds = await decryptConnectionCreds(client, tenantId, row);
|
||||
if (!creds) {
|
||||
continue;
|
||||
}
|
||||
@@ -314,7 +310,7 @@ export async function renewCalendarWebhooksForTenant(
|
||||
skipped += 1;
|
||||
continue;
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, row.id);
|
||||
const baseCreds = await decryptConnectionCreds(client, tenantId, row);
|
||||
if (!baseCreds) {
|
||||
skipped += 1;
|
||||
continue;
|
||||
@@ -386,7 +382,7 @@ export async function syncExternalEventsForConnection(client: CalendarWorkerClie
|
||||
if (!connection || connection.syncDirection === "hivegrid_to_external_only") {
|
||||
return { upserted: 0, fullResync: false };
|
||||
}
|
||||
const baseCreds = await loadCreds(client, tenantId, connectionId);
|
||||
const baseCreds = await decryptConnectionCreds(client, tenantId, connection);
|
||||
if (!baseCreds) {
|
||||
return { upserted: 0, fullResync: false };
|
||||
}
|
||||
@@ -422,11 +418,17 @@ export async function syncExternalEventsForConnection(client: CalendarWorkerClie
|
||||
throw error;
|
||||
}
|
||||
|
||||
const pageMappings =
|
||||
page.events.length === 0
|
||||
? []
|
||||
: await client.calendarEventMapping.findMany({
|
||||
where: { tenantId, connectionId, externalEventId: { in: page.events.map((event) => event.id) }, provider: "google" },
|
||||
select: { id: true, internalEventId: true, externalEventId: true, externalCalendarId: true, connectionId: true, lastSyncedAt: true, lastKnownExternalEtag: true, lastKnownInternalVersionToken: true },
|
||||
});
|
||||
const mappingByExternalEventId = new Map(pageMappings.map((mapping) => [mapping.externalEventId, mapping]));
|
||||
|
||||
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 },
|
||||
});
|
||||
const mapping = mappingByExternalEventId.get(event.id);
|
||||
if (event.status === "cancelled" && mapping) {
|
||||
await persistConflict(client, {
|
||||
tenantId,
|
||||
@@ -482,7 +484,7 @@ export async function syncInternalCalendarEventsForTenant(
|
||||
let failed = 0;
|
||||
|
||||
for (const connection of connections) {
|
||||
const baseCreds = await loadCreds(client, tenantId, connection.id);
|
||||
const baseCreds = await decryptConnectionCreds(client, tenantId, connection);
|
||||
if (!baseCreds) {
|
||||
continue;
|
||||
}
|
||||
@@ -499,13 +501,24 @@ export async function syncInternalCalendarEventsForTenant(
|
||||
orderBy: { updatedAt: "asc" },
|
||||
take: opts.take ?? DEFAULT_TAKE,
|
||||
});
|
||||
const mappings =
|
||||
events.length === 0
|
||||
? []
|
||||
: await client.calendarEventMapping.findMany({
|
||||
where: {
|
||||
tenantId,
|
||||
connectionId: connection.id,
|
||||
internalEventId: { in: events.map((event) => event.id) },
|
||||
provider: "google",
|
||||
externalCalendarId: PRIMARY_CALENDAR,
|
||||
},
|
||||
select: { id: true, internalEventId: true, externalEventId: true, externalCalendarId: true, connectionId: true, lastSyncedAt: true, lastKnownExternalEtag: true, lastKnownInternalVersionToken: true },
|
||||
});
|
||||
const mappingByInternalEventId = new Map(mappings.map((mapping) => [mapping.internalEventId, mapping]));
|
||||
for (const event of events) {
|
||||
scanned += 1;
|
||||
const mapping = mappingByInternalEventId.get(event.id);
|
||||
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);
|
||||
@@ -545,10 +558,6 @@ export async function syncInternalCalendarEventsForTenant(
|
||||
} 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,
|
||||
|
||||
@@ -36,6 +36,9 @@ export interface AppCatalogEntry {
|
||||
readonly connectionSchema: AppConnectionSchema;
|
||||
readonly phase: string;
|
||||
readonly icon?: string;
|
||||
/** Reference/demo adapters stay registered (drift check, tests) but are hidden
|
||||
* from the tenant-facing catalog — customers must not see our fixtures. */
|
||||
readonly internal?: boolean;
|
||||
}
|
||||
|
||||
export const INTEGRATION_CATALOG: readonly AppCatalogEntry[] = [
|
||||
@@ -45,6 +48,7 @@ export const INTEGRATION_CATALOG: readonly AppCatalogEntry[] = [
|
||||
category: "erp",
|
||||
connectionType: "rest_api",
|
||||
phase: "P5",
|
||||
internal: true,
|
||||
connectionSchema: {
|
||||
fields: [
|
||||
{ name: "baseUrl", labelKey: "integrations.field.baseUrl", type: "url", required: true },
|
||||
@@ -65,6 +69,19 @@ export const INTEGRATION_CATALOG: readonly AppCatalogEntry[] = [
|
||||
phase: "P16",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// VR-P33 · Inbound-first HalloPetra assistant. The tenant supplies the
|
||||
// API key manually; post-call delivery is configured in HalloPetra's
|
||||
// webhook dashboard and processed by the telephony event engine.
|
||||
key: "hallopetra",
|
||||
titleKey: "integrations.app.hallopetra.title",
|
||||
category: "communication",
|
||||
connectionType: "api_key",
|
||||
phase: "P33",
|
||||
connectionSchema: {
|
||||
fields: [{ name: "apiKey", labelKey: "integrations.field.apiKey", type: "secret", required: true }],
|
||||
},
|
||||
},
|
||||
{
|
||||
// VA-P23 · Gmail mailbox sync. connectionType oauth2 → the connect flow is
|
||||
// the OAuth redirect (no manual credential form). The per-USER mailbox +
|
||||
@@ -87,6 +104,28 @@ export const INTEGRATION_CATALOG: readonly AppCatalogEntry[] = [
|
||||
phase: "P23",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// AK-P15a · Aircall telephony. OAuth yields one permanent bearer token per
|
||||
// connected Aircall company; the dedicated telephony surface owns user
|
||||
// bindings, calls and webhook processing.
|
||||
key: "aircall",
|
||||
titleKey: "integrations.app.aircall.title",
|
||||
category: "communication",
|
||||
connectionType: "oauth2",
|
||||
phase: "P15",
|
||||
connectionSchema: { fields: [] },
|
||||
},
|
||||
{
|
||||
// VR-P32a · Geerkens pilot for the KWP OAuth2/PKCE connector. The dedicated
|
||||
// setup flow uses the environment-bound pilot client; no manual secret form
|
||||
// is rendered by the generic Apps Engine wizard.
|
||||
key: "kwp",
|
||||
titleKey: "integrations.app.kwp.title",
|
||||
category: "erp",
|
||||
connectionType: "oauth2",
|
||||
phase: "P32",
|
||||
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
|
||||
|
||||
+3
-5
@@ -30,10 +30,8 @@ export type EmailMatchClient = EmailWorkerClient & {
|
||||
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}`;
|
||||
function activitySummaryKey(message: MappedEmailMessage): string {
|
||||
return message.direction === "inbound" ? "activity.runtime.email.received" : "activity.runtime.email.sent";
|
||||
}
|
||||
|
||||
async function gatherAndDecide(
|
||||
@@ -144,7 +142,7 @@ export function createEmailAutoMatchHook(): EmailMessageUpsertedHook {
|
||||
activityType: message.direction === "inbound" ? "email_received" : "email_sent",
|
||||
subjectType: subject.subjectType,
|
||||
subjectId: subject.subjectId,
|
||||
summaryText: klartextSummary(message),
|
||||
summaryText: activitySummaryKey(message),
|
||||
relatedEntityRefs: relatedEntityRefs.length > 0 ? relatedEntityRefs : undefined,
|
||||
metadata: {
|
||||
emailMessageId: messageId,
|
||||
|
||||
+45
@@ -189,6 +189,51 @@ describe("buildRfc2822Message", () => {
|
||||
expect(raw).toContain(`Subject: =?UTF-8?B?${Buffer.from("Rückfrage Wärmepumpe", "utf8").toString("base64")}?=`);
|
||||
expect(raw).toContain("=?UTF-8?B?");
|
||||
});
|
||||
|
||||
it.each([
|
||||
{ field: "subject", input: { subject: "Hello\r\nBcc: victim@example.test" } },
|
||||
{ field: "from address", input: { fromAddress: "sender@example.test\r\nBcc: victim@example.test" } },
|
||||
{ field: "display name", input: { to: [{ address: "max@kunde.de", name: "Max\r\nBcc: victim@example.test" }] } },
|
||||
{ field: "message id", input: { inReplyToInternetMessageId: "id@example.test\r\nBcc: victim@example.test" } },
|
||||
])("rejects RFC-2822 header injection through $field", ({ input }) => {
|
||||
expect(() =>
|
||||
buildRfc2822Message({
|
||||
fromAddress: "info@handwerk.de",
|
||||
to: [{ address: "max@kunde.de" }],
|
||||
subject: "Safe subject",
|
||||
bodyHtml: "<p>x</p>",
|
||||
...input,
|
||||
}),
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
|
||||
it("rejects attachment headers and bodies that can escape the MIME part", () => {
|
||||
const base = {
|
||||
fromAddress: "info@handwerk.de",
|
||||
to: [{ address: "max@kunde.de" }],
|
||||
subject: "Safe subject",
|
||||
bodyHtml: "<p>x</p>",
|
||||
};
|
||||
|
||||
expect(() =>
|
||||
buildRfc2822Message({
|
||||
...base,
|
||||
attachments: [{ filename: "safe.pdf\r\nBcc: victim@example.test", mimeType: "application/pdf", contentBase64: "QUJD" }],
|
||||
}),
|
||||
).toThrow(TypeError);
|
||||
expect(() =>
|
||||
buildRfc2822Message({
|
||||
...base,
|
||||
attachments: [{ filename: "safe.pdf", mimeType: "application/pdf\r\nBcc: victim@example.test", contentBase64: "QUJD" }],
|
||||
}),
|
||||
).toThrow(TypeError);
|
||||
expect(() =>
|
||||
buildRfc2822Message({
|
||||
...base,
|
||||
attachments: [{ filename: "safe.pdf", mimeType: "application/pdf", contentBase64: "QUJD\r\n--forged-boundary" }],
|
||||
}),
|
||||
).toThrow(TypeError);
|
||||
});
|
||||
});
|
||||
|
||||
describe("toBase64Url", () => {
|
||||
|
||||
+67
-10
@@ -251,9 +251,17 @@ export function buildRfc2822Message(input: {
|
||||
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 encodeWord = (value: string, label: string): string => {
|
||||
assertSafeHeaderValue(value, label);
|
||||
return /[^\x20-\x7e]|[<>,"\\]/.test(value) ? `=?UTF-8?B?${Buffer.from(value, "utf8").toString("base64")}?=` : value;
|
||||
};
|
||||
const formatAddress = (a: MappedEmailAddress): string => {
|
||||
assertSafeEmailAddress(a.address);
|
||||
return a.name ? `${encodeWord(a.name, "display name")} <${a.address}>` : a.address;
|
||||
};
|
||||
|
||||
assertSafeEmailAddress(input.fromAddress);
|
||||
assertSafeHeaderValue(input.subject, "subject");
|
||||
|
||||
const headers: string[] = [
|
||||
`From: ${formatAddress({ address: input.fromAddress, name: input.fromName })}`,
|
||||
@@ -261,12 +269,12 @@ export function buildRfc2822Message(input: {
|
||||
];
|
||||
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)}`);
|
||||
headers.push(`Subject: ${encodeWord(input.subject, "subject")}`);
|
||||
if (input.inReplyToInternetMessageId) {
|
||||
headers.push(`In-Reply-To: <${input.inReplyToInternetMessageId}>`);
|
||||
headers.push(`In-Reply-To: <${safeInternetMessageId(input.inReplyToInternetMessageId)}>`);
|
||||
}
|
||||
if (input.referencesInternetMessageIds?.length) {
|
||||
headers.push(`References: ${input.referencesInternetMessageIds.map((id) => `<${id}>`).join(" ")}`);
|
||||
headers.push(`References: ${input.referencesInternetMessageIds.map((id) => `<${safeInternetMessageId(id)}>`).join(" ")}`);
|
||||
}
|
||||
headers.push("MIME-Version: 1.0");
|
||||
|
||||
@@ -279,14 +287,63 @@ export function buildRfc2822Message(input: {
|
||||
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}`,
|
||||
)
|
||||
.map((a) => {
|
||||
const filename = safeMimeFilename(a.filename);
|
||||
const mimeType = safeMimeType(a.mimeType);
|
||||
const contentBase64 = safeBase64Body(a.contentBase64);
|
||||
return `--${boundary}\r\nContent-Type: ${mimeType}; name="${filename}"\r\nContent-Disposition: attachment; filename="${filename}"\r\nContent-Transfer-Encoding: base64\r\n\r\n${contentBase64}`;
|
||||
})
|
||||
.join("\r\n");
|
||||
return `${headers.join("\r\n")}\r\n\r\n--${boundary}\r\n${htmlPart}\r\n${attachmentParts}\r\n--${boundary}--`;
|
||||
}
|
||||
|
||||
function assertSafeHeaderValue(value: string, label: string): void {
|
||||
if (/[\u0000-\u001f\u007f]/u.test(value) || Buffer.byteLength(value, "utf8") > 998) {
|
||||
throw new TypeError(`RFC-2822 ${label} contains invalid control characters or exceeds the header limit.`);
|
||||
}
|
||||
}
|
||||
|
||||
function assertSafeEmailAddress(address: string): void {
|
||||
assertSafeHeaderValue(address, "email address");
|
||||
if (address.length > 320 || !/^[^\s@<>,";:]+@[^\s@<>,";:]+$/u.test(address)) {
|
||||
throw new TypeError("RFC-2822 email address is invalid.");
|
||||
}
|
||||
}
|
||||
|
||||
function safeInternetMessageId(value: string): string {
|
||||
assertSafeHeaderValue(value, "message id");
|
||||
const normalized = value.trim().replace(/^<|>$/g, "");
|
||||
if (!normalized || !/^[^\s<>]+$/u.test(normalized)) {
|
||||
throw new TypeError("RFC-2822 message id is invalid.");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function safeMimeFilename(value: string): string {
|
||||
assertSafeHeaderValue(value, "attachment filename");
|
||||
const normalized = value.replace(/["\\]/g, "_").trim();
|
||||
if (!normalized || Buffer.byteLength(normalized, "utf8") > 255) {
|
||||
throw new TypeError("RFC-2822 attachment filename is invalid.");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function safeMimeType(value: string): string {
|
||||
assertSafeHeaderValue(value, "attachment MIME type");
|
||||
if (!/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/iu.test(value)) {
|
||||
throw new TypeError("RFC-2822 attachment MIME type is invalid.");
|
||||
}
|
||||
return value.toLowerCase();
|
||||
}
|
||||
|
||||
function safeBase64Body(value: string): string {
|
||||
const normalized = value.replace(/\s+/gu, "");
|
||||
if (!normalized || normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/u.test(normalized)) {
|
||||
throw new TypeError("RFC-2822 attachment body is not valid base64.");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function hashCode(value: string): number {
|
||||
let hash = 0;
|
||||
for (let i = 0; i < value.length; i += 1) {
|
||||
|
||||
+98
-16
@@ -150,21 +150,27 @@ function createClient(opts: {
|
||||
},
|
||||
emailIntegrationMessage: {
|
||||
findFirst: vi.fn(async (args: { where?: { internetMessageId?: string } }) =>
|
||||
args?.where?.internetMessageId ? (opts.existingByRfc ?? null) : (opts.existingMessage ?? null),
|
||||
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" })),
|
||||
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,
|
||||
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 ?? []),
|
||||
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 })),
|
||||
@@ -203,11 +209,21 @@ describe("upsertNeutralMessage", () => {
|
||||
|
||||
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 }] });
|
||||
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()) });
|
||||
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);
|
||||
@@ -217,7 +233,11 @@ describe("syncMailboxIncremental (gmail)", () => {
|
||||
});
|
||||
|
||||
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 }] });
|
||||
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);
|
||||
@@ -225,6 +245,30 @@ describe("syncMailboxIncremental (gmail)", () => {
|
||||
expect(resetCall.data.cursorToken).toBeNull();
|
||||
expect(resetCall.data.initialSyncStatus).toBe("pending");
|
||||
});
|
||||
|
||||
it("fetches message details with bounded concurrency", async () => {
|
||||
const client = createClient({
|
||||
cursors: [
|
||||
{ id: "c1", mailboxId: "mb1", externalFolderId: EMAIL_GMAIL_FOLDER, cursorToken: "100", initialSyncStatus: "completed", initialSyncProgress: null },
|
||||
],
|
||||
});
|
||||
const ids = Array.from({ length: 12 }, (_, index) => `g${index + 1}`);
|
||||
mocks.listHistory.mockResolvedValueOnce({ addedMessageIds: ids, historyId: "200" });
|
||||
let active = 0;
|
||||
let peak = 0;
|
||||
mocks.getGmailMessage.mockImplementation(async (_token: string, id: string) => {
|
||||
active += 1;
|
||||
peak = Math.max(peak, active);
|
||||
await new Promise((resolve) => setTimeout(resolve, 2));
|
||||
active -= 1;
|
||||
return { id, 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(12);
|
||||
expect(peak).toBe(5);
|
||||
});
|
||||
});
|
||||
|
||||
describe("syncMailboxIncremental (microsoft)", () => {
|
||||
@@ -232,7 +276,14 @@ describe("syncMailboxIncremental (microsoft)", () => {
|
||||
const client = createClient({
|
||||
mailboxes: [mailboxRow({ provider: "microsoft" })],
|
||||
cursors: [
|
||||
{ id: "c1", mailboxId: "mb1", externalFolderId: "inbox", cursorToken: "https://graph/delta-inbox", initialSyncStatus: "completed", initialSyncProgress: null },
|
||||
{
|
||||
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 },
|
||||
],
|
||||
});
|
||||
@@ -251,10 +302,19 @@ describe("syncMailboxIncremental (microsoft)", () => {
|
||||
|
||||
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 }] });
|
||||
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()) });
|
||||
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);
|
||||
@@ -269,10 +329,24 @@ describe("runEmailInitialSyncForTenant", () => {
|
||||
|
||||
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 } }],
|
||||
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()) });
|
||||
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" });
|
||||
@@ -286,7 +360,11 @@ describe("runEmailInitialSyncForTenant", () => {
|
||||
});
|
||||
|
||||
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 }] });
|
||||
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);
|
||||
@@ -336,7 +414,9 @@ describe("renewEmailWebhooksForTenant", () => {
|
||||
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 }],
|
||||
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" },
|
||||
@@ -353,7 +433,9 @@ describe("drain + stale poll + cleanup", () => {
|
||||
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 }],
|
||||
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 });
|
||||
|
||||
+27
-23
@@ -43,6 +43,8 @@ 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;
|
||||
/** Keep Gmail latency bounded without creating a provider rate-limit burst. */
|
||||
const GMAIL_MESSAGE_FETCH_CONCURRENCY = 5;
|
||||
/** Estimated total for the Klartext percent line when the provider gives one. */
|
||||
const WEBHOOK_RETENTION_DAYS = 30;
|
||||
const WEBHOOK_FAILED_RETENTION_DAYS = 90;
|
||||
@@ -159,7 +161,7 @@ async function ensureFreshCreds(
|
||||
client: EmailWorkerClient,
|
||||
mailbox: { id: string; tenantId: string; provider: EmailProvider },
|
||||
creds: EmailCreds,
|
||||
now = new Date(),
|
||||
now = new Date()
|
||||
): Promise<EmailCreds> {
|
||||
if (creds.expiresAt && creds.expiresAt.getTime() > now.getTime() + 60_000) {
|
||||
return creds;
|
||||
@@ -208,7 +210,7 @@ export type EmailMessageUpsertedHook = (input: {
|
||||
export async function upsertNeutralMessage(
|
||||
client: EmailWorkerClient,
|
||||
ctx: { tenantId: string; mailboxId: string },
|
||||
message: MappedEmailMessage,
|
||||
message: MappedEmailMessage
|
||||
): Promise<{ id: string; created: boolean }> {
|
||||
const baseFields = {
|
||||
providerThreadId: message.providerThreadId,
|
||||
@@ -264,15 +266,21 @@ export async function upsertNeutralMessage(
|
||||
|
||||
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;
|
||||
}
|
||||
for (let offset = 0; offset < messageIds.length; offset += GMAIL_MESSAGE_FETCH_CONCURRENCY) {
|
||||
const batch = messageIds.slice(offset, offset + GMAIL_MESSAGE_FETCH_CONCURRENCY);
|
||||
const results = await Promise.all(
|
||||
batch.map(async (id) => {
|
||||
try {
|
||||
return mapGmailMessage(await getGmailMessage(accessToken, id, "full"));
|
||||
} catch (error) {
|
||||
if (error instanceof GmailError && error.code === "message_not_found") {
|
||||
return null; // deleted between listing and fetching — not an error
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
})
|
||||
);
|
||||
mapped.push(...results.filter((message): message is MappedEmailMessage => message !== null));
|
||||
}
|
||||
return mapped;
|
||||
}
|
||||
@@ -281,7 +289,7 @@ async function persistMessages(
|
||||
client: EmailWorkerClient,
|
||||
mailbox: EmailMailboxRow,
|
||||
messages: readonly MappedEmailMessage[],
|
||||
hook: EmailMessageUpsertedHook | undefined,
|
||||
hook: EmailMessageUpsertedHook | undefined
|
||||
): Promise<number> {
|
||||
let upserted = 0;
|
||||
for (const message of messages) {
|
||||
@@ -321,7 +329,7 @@ export async function syncMailboxIncremental(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
mailboxId: string,
|
||||
opts: { now?: Date; hook?: EmailMessageUpsertedHook } = {},
|
||||
opts: { now?: Date; hook?: EmailMessageUpsertedHook } = {}
|
||||
): Promise<{ upserted: number; resyncScheduled: boolean }> {
|
||||
const now = opts.now ?? new Date();
|
||||
const mailbox = await client.emailIntegrationMailbox.findFirst({
|
||||
@@ -422,7 +430,7 @@ export async function syncMailboxIncremental(
|
||||
export async function runEmailInitialSyncForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number; initialDays?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
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);
|
||||
@@ -521,7 +529,7 @@ export async function runEmailInitialSyncForTenant(
|
||||
export async function refreshEmailTokensForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; windowMs?: number } = {},
|
||||
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));
|
||||
@@ -557,7 +565,7 @@ export async function refreshEmailTokensForTenant(
|
||||
export async function renewEmailWebhooksForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; thresholdMs?: number; graphWebhookUrl?: 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;
|
||||
@@ -632,7 +640,7 @@ export async function renewEmailWebhooksForTenant(
|
||||
export async function drainEmailWebhookEventsForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; take?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
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({
|
||||
@@ -684,7 +692,7 @@ export async function drainEmailWebhookEventsForTenant(
|
||||
export async function pollStaleEmailMailboxesForTenant(
|
||||
client: EmailWorkerClient,
|
||||
tenantId: string,
|
||||
opts: { now?: Date; staleMs?: number; take?: number; hook?: EmailMessageUpsertedHook } = {},
|
||||
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));
|
||||
@@ -710,11 +718,7 @@ export async function pollStaleEmailMailboxesForTenant(
|
||||
}
|
||||
|
||||
/** 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 }> {
|
||||
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);
|
||||
|
||||
+11
@@ -5,6 +5,7 @@ import {
|
||||
GmailError,
|
||||
buildGmailAuthorizationUrl,
|
||||
exchangeGmailCodeForTokens,
|
||||
fetchGmailHistoryCursor,
|
||||
getMessage,
|
||||
listHistory,
|
||||
listMessageIds,
|
||||
@@ -168,6 +169,16 @@ describe("messages", () => {
|
||||
expect(String(fetchMock.mock.calls[0][0])).toContain("format=metadata");
|
||||
});
|
||||
|
||||
it("reads the current mailbox history cursor for a bounded initial sync", async () => {
|
||||
fetchMock.mockResolvedValueOnce(
|
||||
jsonResponse(200, { historyId: "history-9" })
|
||||
);
|
||||
await expect(fetchGmailHistoryCursor("at")).resolves.toBe("history-9");
|
||||
expect(String(fetchMock.mock.calls[0][0])).toContain(
|
||||
"/gmail/v1/users/me/profile"
|
||||
);
|
||||
});
|
||||
|
||||
it("sends a raw message inside a thread", async () => {
|
||||
fetchMock.mockResolvedValueOnce(jsonResponse(200, { id: "sent1", threadId: "t9" }));
|
||||
const result = await sendRawMessage("at", "cmF3", "t9");
|
||||
|
||||
+45
-35
@@ -10,6 +10,8 @@
|
||||
// never a bare provider status leaks to the UI. Gmail signals an expired
|
||||
// `historyId` with HTTP 404 on history.list → `fullResyncRequired`.
|
||||
|
||||
import { fetchProvider, readProviderJson } from "../provider-http.js";
|
||||
|
||||
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";
|
||||
@@ -124,7 +126,7 @@ function tokenSetFromResponse(body: GmailTokenResponse, now: number): GmailToken
|
||||
|
||||
/** 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, {
|
||||
const res = await fetchProvider(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
@@ -135,7 +137,7 @@ export async function exchangeGmailCodeForTokens(config: GmailOAuthConfig, code:
|
||||
code,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GmailTokenResponse;
|
||||
const body = await readProviderJson<GmailTokenResponse>(res);
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
@@ -144,7 +146,7 @@ export async function exchangeGmailCodeForTokens(config: GmailOAuthConfig, code:
|
||||
|
||||
/** 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, {
|
||||
const res = await fetchProvider(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
@@ -154,7 +156,7 @@ export async function refreshGmailAccessToken(config: GmailOAuthConfig, refreshT
|
||||
refresh_token: refreshToken,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GmailTokenResponse;
|
||||
const body = await readProviderJson<GmailTokenResponse>(res);
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
@@ -164,7 +166,7 @@ export async function refreshGmailAccessToken(config: GmailOAuthConfig, refreshT
|
||||
|
||||
/** 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" });
|
||||
const res = await fetchProvider(`${OAUTH_REVOKE_URL}?token=${encodeURIComponent(token)}`, { method: "POST" });
|
||||
// 400 = token already invalid/revoked → idempotent success.
|
||||
if (res.ok || res.status === 400) {
|
||||
return;
|
||||
@@ -192,13 +194,13 @@ export interface GmailUserInfo {
|
||||
}
|
||||
|
||||
export async function fetchGmailUserInfo(accessToken: string): Promise<GmailUserInfo> {
|
||||
const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
|
||||
const res = await fetchProvider("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 };
|
||||
const body = await readProviderJson<{ email?: string; sub?: string }>(res);
|
||||
return { email: body.email ?? "", sub: body.sub ?? "" };
|
||||
}
|
||||
|
||||
@@ -215,7 +217,7 @@ export interface GmailWatchResult {
|
||||
* 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`, {
|
||||
const res = await fetchProvider(`${GMAIL_API_BASE}/watch`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ topicName: pubsubTopic, labelIds: ["INBOX", "SENT"], labelFilterBehavior: "INCLUDE" }),
|
||||
@@ -223,7 +225,7 @@ export async function watchMailbox(accessToken: string, pubsubTopic: string): Pr
|
||||
if (!res.ok) {
|
||||
throw new GmailError("watch_subscription_failed", res.status);
|
||||
}
|
||||
const body = (await res.json()) as { historyId?: string; expiration?: string };
|
||||
const body = await readProviderJson<{ historyId?: string; expiration?: string }>(res);
|
||||
return {
|
||||
historyId: body.historyId ?? "",
|
||||
expiresAt: body.expiration ? new Date(Number(body.expiration)) : null,
|
||||
@@ -232,7 +234,7 @@ export async function watchMailbox(accessToken: string, pubsubTopic: string): Pr
|
||||
|
||||
/** Stop push notifications for the mailbox (disconnect). Idempotent. */
|
||||
export async function stopWatchMailbox(accessToken: string): Promise<void> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/stop`, {
|
||||
const res = await fetchProvider(`${GMAIL_API_BASE}/stop`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
@@ -255,14 +257,10 @@ export interface GmailHistoryPage {
|
||||
* 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> {
|
||||
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()}`, {
|
||||
const res = await fetchProvider(`${GMAIL_API_BASE}/history?${params.toString()}`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (res.status === 404) {
|
||||
@@ -271,11 +269,11 @@ export async function listHistory(
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as {
|
||||
const body = await readProviderJson<{
|
||||
history?: Array<{ messagesAdded?: Array<{ message?: { id?: string } }> }>;
|
||||
nextPageToken?: string;
|
||||
historyId?: string;
|
||||
};
|
||||
}>(res);
|
||||
const ids = new Set<string>();
|
||||
for (const entry of body.history ?? []) {
|
||||
for (const added of entry.messagesAdded ?? []) {
|
||||
@@ -295,20 +293,17 @@ export interface GmailMessageIdPage {
|
||||
* 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> {
|
||||
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()}`, {
|
||||
const res = await fetchProvider(`${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 };
|
||||
const body = await readProviderJson<{ messages?: Array<{ id: string }>; nextPageToken?: string; resultSizeEstimate?: number }>(res);
|
||||
return {
|
||||
messageIds: (body.messages ?? []).map((m) => m.id),
|
||||
nextPageToken: body.nextPageToken,
|
||||
@@ -316,6 +311,22 @@ export async function listMessageIds(
|
||||
};
|
||||
}
|
||||
|
||||
export async function fetchGmailHistoryCursor(
|
||||
accessToken: string
|
||||
): Promise<string> {
|
||||
const res = await fetchProvider(`${GMAIL_API_BASE}/profile`, {
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = await readProviderJson<{ historyId?: string }>(res);
|
||||
if (!body.historyId) {
|
||||
throw new GmailError("unknown", undefined, "missing_history_cursor");
|
||||
}
|
||||
return body.historyId;
|
||||
}
|
||||
|
||||
/** Raw Gmail message (format=full). MIME mapping happens in the module adapter. */
|
||||
export interface GmailMessage {
|
||||
readonly id: string;
|
||||
@@ -337,13 +348,13 @@ export interface 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}`, {
|
||||
const res = await fetchProvider(`${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;
|
||||
return readProviderJson<GmailMessage>(res);
|
||||
}
|
||||
|
||||
export interface GmailSendResult {
|
||||
@@ -356,7 +367,7 @@ export interface GmailSendResult {
|
||||
* 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`, {
|
||||
const res = await fetchProvider(`${GMAIL_API_BASE}/messages/send`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify(threadId ? { raw: rawBase64Url, threadId } : { raw: rawBase64Url }),
|
||||
@@ -364,7 +375,7 @@ export async function sendRawMessage(accessToken: string, rawBase64Url: string,
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; threadId?: string };
|
||||
const body = await readProviderJson<{ id: string; threadId?: string }>(res);
|
||||
return { id: body.id, threadId: body.threadId };
|
||||
}
|
||||
|
||||
@@ -372,9 +383,9 @@ export async function sendRawMessage(accessToken: string, rawBase64Url: string,
|
||||
export async function modifyMessageLabels(
|
||||
accessToken: string,
|
||||
messageId: string,
|
||||
changes: { addLabelIds?: readonly string[]; removeLabelIds?: readonly string[] },
|
||||
changes: { addLabelIds?: readonly string[]; removeLabelIds?: readonly string[] }
|
||||
): Promise<void> {
|
||||
const res = await fetch(`${GMAIL_API_BASE}/messages/${encodeURIComponent(messageId)}/modify`, {
|
||||
const res = await fetchProvider(`${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 ?? [] }),
|
||||
@@ -386,14 +397,13 @@ export async function modifyMessageLabels(
|
||||
|
||||
/** 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}` } },
|
||||
);
|
||||
const res = await fetchProvider(`${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 };
|
||||
const body = await readProviderJson<{ data?: string; size?: number }>(res);
|
||||
return { data: body.data ?? "", size: body.size ?? 0 };
|
||||
}
|
||||
|
||||
|
||||
+24
-27
@@ -9,6 +9,8 @@
|
||||
// All errors are mapped to a stable `GoogleCalendarErrorCode` (Klartext-ready,
|
||||
// M002) — never a bare provider status leaks to the UI.
|
||||
|
||||
import { fetchProvider, readProviderJson } from "../provider-http.js";
|
||||
|
||||
const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
|
||||
const CALENDAR_API_BASE = "https://www.googleapis.com/calendar/v3";
|
||||
|
||||
@@ -64,6 +66,7 @@ export function resolveGoogleOAuthConfig(env: NodeJS.ProcessEnv = process.env):
|
||||
/** Calendar OAuth scopes (Phase 1 — calendar.events + identity, no Gmail). */
|
||||
export const GOOGLE_CALENDAR_SCOPES = [
|
||||
"https://www.googleapis.com/auth/calendar.events",
|
||||
"https://www.googleapis.com/auth/calendar.freebusy",
|
||||
"openid",
|
||||
"email",
|
||||
] as const;
|
||||
@@ -111,7 +114,7 @@ function tokenSetFromResponse(body: GoogleTokenResponse, now: number): GoogleTok
|
||||
|
||||
/** 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, {
|
||||
const res = await fetchProvider(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
@@ -122,7 +125,7 @@ export async function exchangeCodeForTokens(config: GoogleOAuthConfig, code: str
|
||||
code,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GoogleTokenResponse;
|
||||
const body = await readProviderJson<GoogleTokenResponse>(res);
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
@@ -131,7 +134,7 @@ export async function exchangeCodeForTokens(config: GoogleOAuthConfig, code: str
|
||||
|
||||
/** 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, {
|
||||
const res = await fetchProvider(OAUTH_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded" },
|
||||
body: new URLSearchParams({
|
||||
@@ -141,7 +144,7 @@ export async function refreshAccessToken(config: GoogleOAuthConfig, refreshToken
|
||||
refresh_token: refreshToken,
|
||||
}),
|
||||
});
|
||||
const body = (await res.json()) as GoogleTokenResponse;
|
||||
const body = await readProviderJson<GoogleTokenResponse>(res);
|
||||
if (!res.ok || !body.access_token) {
|
||||
throw mapOAuthError(res.status, body);
|
||||
}
|
||||
@@ -169,13 +172,13 @@ export interface GoogleUserInfo {
|
||||
}
|
||||
|
||||
export async function fetchUserInfo(accessToken: string): Promise<GoogleUserInfo> {
|
||||
const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
|
||||
const res = await fetchProvider("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 };
|
||||
const body = await readProviderJson<{ email?: string; sub?: string }>(res);
|
||||
return { email: body.email ?? "", sub: body.sub ?? "" };
|
||||
}
|
||||
|
||||
@@ -186,13 +189,13 @@ export interface GoogleCalendarListEntry {
|
||||
}
|
||||
|
||||
export async function listCalendars(accessToken: string): Promise<GoogleCalendarListEntry[]> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/users/me/calendarList`, {
|
||||
const res = await fetchProvider(`${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 }> };
|
||||
const body = await readProviderJson<{ items?: Array<{ id: string; summary?: string; primary?: boolean }> }>(res);
|
||||
return (body.items ?? []).map((c) => ({ id: c.id, summary: c.summary ?? c.id, primary: c.primary ?? false }));
|
||||
}
|
||||
|
||||
@@ -226,7 +229,7 @@ export interface DeltaPage {
|
||||
export async function listEvents(
|
||||
accessToken: string,
|
||||
calendarId: string,
|
||||
opts: { syncToken?: string; pageToken?: string; timeMin?: string; timeMax?: 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) {
|
||||
@@ -237,13 +240,13 @@ export async function listEvents(
|
||||
}
|
||||
if (opts.pageToken) params.set("pageToken", opts.pageToken);
|
||||
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events?${params.toString()}`, {
|
||||
const res = await fetchProvider(`${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 };
|
||||
const body = await readProviderJson<{ items?: GoogleEvent[]; nextSyncToken?: string; nextPageToken?: string }>(res);
|
||||
return { events: body.items ?? [], nextSyncToken: body.nextSyncToken, nextPageToken: body.nextPageToken };
|
||||
}
|
||||
|
||||
@@ -263,7 +266,7 @@ export interface GoogleWriteResult {
|
||||
}
|
||||
|
||||
export async function insertEvent(accessToken: string, calendarId: string, input: GoogleEventInput): Promise<GoogleWriteResult> {
|
||||
const res = await fetch(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events`, {
|
||||
const res = await fetchProvider(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events`, {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify(input),
|
||||
@@ -271,7 +274,7 @@ export async function insertEvent(accessToken: string, calendarId: string, input
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; etag?: string };
|
||||
const body = await readProviderJson<{ id: string; etag?: string }>(res);
|
||||
return { id: body.id, etag: body.etag };
|
||||
}
|
||||
|
||||
@@ -286,11 +289,11 @@ export async function patchEvent(
|
||||
calendarId: string,
|
||||
eventId: string,
|
||||
input: Partial<GoogleEventInput>,
|
||||
ifMatchEtag?: string,
|
||||
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)}`, {
|
||||
const res = await fetchProvider(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, {
|
||||
method: "PATCH",
|
||||
headers,
|
||||
body: JSON.stringify(input),
|
||||
@@ -301,12 +304,12 @@ export async function patchEvent(
|
||||
if (!res.ok) {
|
||||
throw mapApiError(res.status);
|
||||
}
|
||||
const body = (await res.json()) as { id: string; etag?: string };
|
||||
const body = await readProviderJson<{ id: string; etag?: string }>(res);
|
||||
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)}`, {
|
||||
const res = await fetchProvider(`${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`, {
|
||||
method: "DELETE",
|
||||
headers: { authorization: `Bearer ${accessToken}` },
|
||||
});
|
||||
@@ -328,14 +331,8 @@ export interface GoogleWatchChannel {
|
||||
* `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`, {
|
||||
export async function watchCalendar(accessToken: string, calendarId: string, channelId: string, address: string, token: string): Promise<GoogleWatchChannel> {
|
||||
const res = await fetchProvider(`${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 }),
|
||||
@@ -343,7 +340,7 @@ export async function watchCalendar(
|
||||
if (!res.ok) {
|
||||
throw new GoogleCalendarError("webhook_subscription_failed", res.status);
|
||||
}
|
||||
const body = (await res.json()) as { resourceId?: string; expiration?: string };
|
||||
const body = await readProviderJson<{ resourceId?: string; expiration?: string }>(res);
|
||||
return {
|
||||
channelId,
|
||||
resourceId: body.resourceId ?? "",
|
||||
@@ -352,7 +349,7 @@ export async function watchCalendar(
|
||||
}
|
||||
|
||||
export async function stopChannel(accessToken: string, channelId: string, resourceId: string): Promise<void> {
|
||||
const res = await fetch("https://www.googleapis.com/calendar/v3/channels/stop", {
|
||||
const res = await fetchProvider("https://www.googleapis.com/calendar/v3/channels/stop", {
|
||||
method: "POST",
|
||||
headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
|
||||
body: JSON.stringify({ id: channelId, resourceId }),
|
||||
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { resolveAdapter } from "../registry.js";
|
||||
import { hallopetraTelephonyProvider } from "./adapter.js";
|
||||
|
||||
describe("HalloPetra adapters", () => {
|
||||
it("registers the Apps Engine connector as API-key based", () => {
|
||||
expect(resolveAdapter("hallopetra")).toMatchObject({ key: "hallopetra", connectionType: "api_key" });
|
||||
});
|
||||
|
||||
it("keeps unavailable carrier capabilities explicit", async () => {
|
||||
await expect(
|
||||
hallopetraTelephonyProvider.triggerOutboundCall(
|
||||
{ apiKey: "key" },
|
||||
{ userId: "user", numberId: "number", to: "+49301234567" },
|
||||
),
|
||||
).rejects.toMatchObject({ code: "capability_unsupported" });
|
||||
await expect(
|
||||
hallopetraTelephonyProvider.subscribeToWebhooks(
|
||||
{ apiKey: "key" },
|
||||
{ url: "https://api.example.test/webhook", name: "HiveGrid", events: ["post_call"] },
|
||||
),
|
||||
).rejects.toMatchObject({ code: "capability_unsupported" });
|
||||
await expect(hallopetraTelephonyProvider.listProviderUsers({ apiKey: "key" })).resolves.toEqual([]);
|
||||
});
|
||||
|
||||
it("does not perform a provider mutation on disconnect", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
await expect(hallopetraTelephonyProvider.disconnect({ apiKey: "key" }, "manual")).resolves.toBeUndefined();
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
});
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
import {
|
||||
registerIntegrationAdapter,
|
||||
type AdapterResult,
|
||||
type AdapterSyncOutcome,
|
||||
type IntegrationAdapter,
|
||||
} from "@hivegrid/foundation";
|
||||
|
||||
import type { TelephonyProviderInterface } from "../telephony/provider.js";
|
||||
import { probeHalloPetraApiKey } from "./client.js";
|
||||
import { HalloPetraError, type HalloPetraCredentials } from "./types.js";
|
||||
import {
|
||||
getHalloPetraRecordingUrl,
|
||||
normalizeHalloPetraWebhook,
|
||||
parseHalloPetraWebhookEvent,
|
||||
validateHalloPetraWebhook,
|
||||
} from "./webhook.js";
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof HalloPetraError) {
|
||||
if (error.code === "auth_token_invalid") return { ok: false, health: "broken", messageKey: "telephony.health.tokenInvalid" };
|
||||
if (error.code === "rate_limit_exceeded") return { ok: true, health: "degraded", messageKey: "telephony.health.rateLimited" };
|
||||
if (error.code === "provider_outage") return { ok: false, health: "degraded", messageKey: "telephony.health.providerOutage" };
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "telephony.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(credentials: HalloPetraCredentials): Promise<AdapterResult> {
|
||||
try {
|
||||
await probeHalloPetraApiKey(credentials);
|
||||
return { ok: true, health: "active", messageKey: "telephony.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const hallopetraAdapter: IntegrationAdapter<HalloPetraCredentials> = registerIntegrationAdapter<HalloPetraCredentials>({
|
||||
key: "hallopetra",
|
||||
connectionType: "api_key",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({ items: [], summaryKey: "telephony.sync.summary.webhookEngine" }),
|
||||
});
|
||||
|
||||
/**
|
||||
* HalloPetra is an inbound assistant, not a click-to-call carrier. Provider-side
|
||||
* webhook registration is manual in its dashboard; unsupported interface
|
||||
* methods fail explicitly instead of pretending that a remote mutation ran.
|
||||
*/
|
||||
export const hallopetraTelephonyProvider: TelephonyProviderInterface<HalloPetraCredentials> = {
|
||||
key: "hallopetra",
|
||||
connect: probeHalloPetraApiKey,
|
||||
disconnect: () => Promise.resolve(),
|
||||
probe: probeHalloPetraApiKey,
|
||||
listUsers: () => Promise.resolve([]),
|
||||
listProviderUsers: () => Promise.resolve([]),
|
||||
listUserNumbers: () => Promise.resolve([]),
|
||||
startCall: () => Promise.reject(new HalloPetraError("capability_unsupported")),
|
||||
triggerOutboundCall: () => Promise.reject(new HalloPetraError("capability_unsupported")),
|
||||
createWebhook: () => Promise.reject(new HalloPetraError("capability_unsupported")),
|
||||
subscribeToWebhooks: () => Promise.reject(new HalloPetraError("capability_unsupported")),
|
||||
deleteWebhook: () => Promise.resolve(),
|
||||
validateWebhook: validateHalloPetraWebhook,
|
||||
parseWebhookEvent: parseHalloPetraWebhookEvent,
|
||||
normalizeWebhook: normalizeHalloPetraWebhook,
|
||||
getRecordingUrl: getHalloPetraRecordingUrl,
|
||||
};
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { HALLOPETRA_API_BASE, probeHalloPetraApiKey } from "./client.js";
|
||||
import { HalloPetraError } from "./types.js";
|
||||
|
||||
afterEach(() => vi.unstubAllGlobals());
|
||||
|
||||
describe("HalloPetra API-key client", () => {
|
||||
it("sends the key only as a bearer credential to the authenticated v1 boundary", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(new Response("Not Found", { status: 404 }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(probeHalloPetraApiKey({ apiKey: "test-hallopetra-key" })).resolves.toBeUndefined();
|
||||
|
||||
const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
|
||||
expect(url).toBe(`${HALLOPETRA_API_BASE}/v1/health`);
|
||||
expect(init.headers).toEqual({ authorization: "Bearer test-hallopetra-key" });
|
||||
});
|
||||
|
||||
it("rejects an unauthorized key without copying provider diagnostics or the key", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(
|
||||
new Response(JSON.stringify({ message: "invalid test-hallopetra-key" }), {
|
||||
status: 401,
|
||||
headers: { "content-type": "application/json" },
|
||||
}),
|
||||
);
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
const error = await probeHalloPetraApiKey({ apiKey: "test-hallopetra-key" }).catch((caught: unknown) => caught);
|
||||
expect(error).toBeInstanceOf(HalloPetraError);
|
||||
expect(error).toMatchObject({ code: "auth_token_invalid", httpStatus: 401 });
|
||||
expect(String(error)).not.toContain("test-hallopetra-key");
|
||||
expect(JSON.stringify(error)).not.toContain("test-hallopetra-key");
|
||||
});
|
||||
|
||||
it("fails closed before a request when no key is present", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
await expect(probeHalloPetraApiKey({ apiKey: "" })).rejects.toMatchObject({ code: "auth_token_invalid" });
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
import { fetchProvider } from "../provider-http.js";
|
||||
import { HalloPetraError, type HalloPetraCredentials } from "./types.js";
|
||||
|
||||
export const HALLOPETRA_API_BASE = "https://api.hallopetra.de";
|
||||
|
||||
/**
|
||||
* Validate the bearer key at HalloPetra's authenticated `/v1` boundary.
|
||||
*
|
||||
* The 2026-08-01 test-account contract exposes no documented identity/ping
|
||||
* resource. Its gateway authenticates `/v1/health` first: invalid keys receive
|
||||
* 401, while accepted keys reach routing and currently receive 404. Both a
|
||||
* future successful health response and that observed routed 404 prove that
|
||||
* the bearer key passed authentication.
|
||||
*/
|
||||
export async function probeHalloPetraApiKey(credentials: HalloPetraCredentials): Promise<void> {
|
||||
const apiKey = requireApiKey(credentials);
|
||||
const response = await fetchProvider(`${HALLOPETRA_API_BASE}/v1/health`, {
|
||||
headers: { authorization: `Bearer ${apiKey}` },
|
||||
});
|
||||
if (response.ok || response.status === 404) return;
|
||||
throw mapHalloPetraError(response.status);
|
||||
}
|
||||
|
||||
function requireApiKey(credentials: HalloPetraCredentials): string {
|
||||
const apiKey = credentials.apiKey?.trim();
|
||||
if (!apiKey || apiKey.length > 2_048) throw new HalloPetraError("auth_token_invalid");
|
||||
return apiKey;
|
||||
}
|
||||
|
||||
function mapHalloPetraError(status: number): HalloPetraError {
|
||||
if (status === 401 || status === 403) return new HalloPetraError("auth_token_invalid", status);
|
||||
if (status === 429) return new HalloPetraError("rate_limit_exceeded", status);
|
||||
if (status === 400 || status === 422) return new HalloPetraError("invalid_request", status);
|
||||
if (status >= 500) return new HalloPetraError("provider_outage", status);
|
||||
return new HalloPetraError("unknown", status);
|
||||
}
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
export const HALLOPETRA_POST_CALL_FIXTURE = {
|
||||
webhook_id: "webhook-123",
|
||||
data: {
|
||||
id: "call-456",
|
||||
duration: 95,
|
||||
phone: "+49 30 1234567",
|
||||
inbound_phone_number: "+49 30 7654321",
|
||||
topic: "Terminwunsch",
|
||||
summary: "Die Anruferin möchte einen Termin am Dienstag.",
|
||||
messages: [
|
||||
{ role: "assistant", content: "Guten Tag, hier ist Petra." },
|
||||
{ role: "user", content: "Ich brauche einen Termin." },
|
||||
],
|
||||
collected_data: { preferred_day: "Dienstag" },
|
||||
main_task_id: "task-1",
|
||||
email_send_to: null,
|
||||
forwarded_to: null,
|
||||
previous_webhook_calls: [],
|
||||
},
|
||||
} as const;
|
||||
|
||||
export const HALLOPETRA_PRE_CALL_FIXTURE = {
|
||||
webhook_id: "webhook-pre",
|
||||
data: {
|
||||
calling_phone_number: "+49301234567",
|
||||
inbound_phone_number: "+49307654321",
|
||||
start_time: "2026-08-01T08:00:00.000Z",
|
||||
},
|
||||
} as const;
|
||||
@@ -0,0 +1,5 @@
|
||||
export * from "./adapter.js";
|
||||
export * from "./client.js";
|
||||
export * from "./fixtures.js";
|
||||
export * from "./types.js";
|
||||
export * from "./webhook.js";
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
/** Decrypted HalloPetra credential shape stored by the Apps Engine. */
|
||||
export interface HalloPetraCredentials {
|
||||
readonly apiKey?: string | null;
|
||||
}
|
||||
|
||||
export type HalloPetraErrorCode =
|
||||
| "auth_token_invalid"
|
||||
| "rate_limit_exceeded"
|
||||
| "invalid_request"
|
||||
| "provider_outage"
|
||||
| "capability_unsupported"
|
||||
| "unknown";
|
||||
|
||||
export class HalloPetraError extends Error {
|
||||
readonly code: HalloPetraErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
|
||||
constructor(code: HalloPetraErrorCode, httpStatus?: number) {
|
||||
// Provider bodies can contain customer data. Keep exceptions deliberately
|
||||
// free of response text and credentials.
|
||||
super(code);
|
||||
this.name = "HalloPetraError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal authenticated envelope built by HiveGrid's public ingress.
|
||||
* HalloPetra sends the native body; HiveGrid adds the custom-header secret and
|
||||
* receipt timestamp before handing the payload to the provider adapter.
|
||||
*/
|
||||
export interface HalloPetraWebhookEnvelope {
|
||||
readonly token?: unknown;
|
||||
readonly receivedAtIso?: unknown;
|
||||
readonly body?: unknown;
|
||||
}
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { HALLOPETRA_POST_CALL_FIXTURE, HALLOPETRA_PRE_CALL_FIXTURE } from "./fixtures.js";
|
||||
import {
|
||||
buildHalloPetraSummary,
|
||||
normalizeHalloPetraWebhook,
|
||||
parseHalloPetraWebhookEvent,
|
||||
verifyHalloPetraWebhookSecret,
|
||||
} from "./webhook.js";
|
||||
|
||||
const SECRET = "separate-hivegrid-webhook-secret";
|
||||
const RECEIVED_AT = "2026-08-01T08:30:00.000Z";
|
||||
|
||||
describe("HalloPetra webhook contract", () => {
|
||||
it("normalizes the documented post-call body into one inbound terminal event", () => {
|
||||
const result = normalizeHalloPetraWebhook(
|
||||
{ token: SECRET, receivedAtIso: RECEIVED_AT, body: HALLOPETRA_POST_CALL_FIXTURE },
|
||||
SECRET,
|
||||
);
|
||||
|
||||
expect(result).toEqual({
|
||||
ok: true,
|
||||
event: {
|
||||
provider: "hallopetra",
|
||||
providerEvent: "post_call",
|
||||
type: "ended",
|
||||
dedupeKey: "hallopetra:post_call:call-456:webhook-123",
|
||||
providerCallId: "call-456",
|
||||
occurredAtIso: RECEIVED_AT,
|
||||
direction: "inbound",
|
||||
status: "completed",
|
||||
externalNumber: "+49301234567",
|
||||
lineId: null,
|
||||
lineNumber: "+49307654321",
|
||||
providerUserId: null,
|
||||
providerUserEmail: null,
|
||||
startedAtIso: "2026-08-01T08:28:25.000Z",
|
||||
answeredAtIso: "2026-08-01T08:28:25.000Z",
|
||||
endedAtIso: RECEIVED_AT,
|
||||
durationSeconds: 95,
|
||||
missed: false,
|
||||
missedReason: null,
|
||||
recordingUrl: null,
|
||||
voicemailUrl: null,
|
||||
noteMarkdown: "## Terminwunsch\n\nDie Anruferin möchte einen Termin am Dienstag.",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts the dashboard example's extra body wrapper", () => {
|
||||
expect(
|
||||
parseHalloPetraWebhookEvent({
|
||||
receivedAtIso: RECEIVED_AT,
|
||||
body: { body: HALLOPETRA_POST_CALL_FIXTURE },
|
||||
}),
|
||||
).toMatchObject({ ok: true });
|
||||
});
|
||||
|
||||
it("rejects synchronous pre-call payloads as non-lifecycle events", () => {
|
||||
expect(parseHalloPetraWebhookEvent({ receivedAtIso: RECEIVED_AT, body: HALLOPETRA_PRE_CALL_FIXTURE })).toEqual({
|
||||
ok: false,
|
||||
reason: "unsupported_event",
|
||||
});
|
||||
});
|
||||
|
||||
it("authenticates a separate custom-header secret in constant-time semantics", () => {
|
||||
expect(verifyHalloPetraWebhookSecret(SECRET, SECRET)).toBe(true);
|
||||
expect(verifyHalloPetraWebhookSecret("wrong", SECRET)).toBe(false);
|
||||
expect(normalizeHalloPetraWebhook({ token: "wrong", receivedAtIso: RECEIVED_AT, body: HALLOPETRA_POST_CALL_FIXTURE }, SECRET)).toEqual({
|
||||
ok: false,
|
||||
reason: "invalid_token",
|
||||
});
|
||||
});
|
||||
|
||||
it("extracts only topic and summary, never the full conversation", () => {
|
||||
const summary = buildHalloPetraSummary({ body: HALLOPETRA_POST_CALL_FIXTURE });
|
||||
expect(summary).toBe("## Terminwunsch\n\nDie Anruferin möchte einen Termin am Dienstag.");
|
||||
expect(summary).not.toContain("Guten Tag, hier ist Petra");
|
||||
});
|
||||
});
|
||||
+151
@@ -0,0 +1,151 @@
|
||||
import { timingSafeEqual } from "node:crypto";
|
||||
|
||||
import type { TelephonyCallEvent, TelephonyWebhookNormalizationResult } from "../telephony/provider.js";
|
||||
import type { HalloPetraWebhookEnvelope } from "./types.js";
|
||||
|
||||
const MAX_WEBHOOK_SECRET_BYTES = 2_048;
|
||||
const E164_PATTERN = /^\+[1-9]\d{6,14}$/u;
|
||||
const MAX_SUMMARY_LENGTH = 20_000;
|
||||
|
||||
/** Exact, constant-time comparison for the custom Authorization header secret. */
|
||||
export function verifyHalloPetraWebhookSecret(receivedSecret: unknown, expectedSecret: string): boolean {
|
||||
if (typeof receivedSecret !== "string" || !receivedSecret || !expectedSecret) return false;
|
||||
const received = Buffer.from(receivedSecret, "utf8");
|
||||
const expected = Buffer.from(expectedSecret, "utf8");
|
||||
if (received.length > MAX_WEBHOOK_SECRET_BYTES || expected.length > MAX_WEBHOOK_SECRET_BYTES) return false;
|
||||
if (received.length !== expected.length) return false;
|
||||
return timingSafeEqual(received, expected);
|
||||
}
|
||||
|
||||
export function validateHalloPetraWebhook(payload: unknown, expectedSecret: string): boolean {
|
||||
return isRecord(payload) && verifyHalloPetraWebhookSecret(payload.token, expectedSecret);
|
||||
}
|
||||
|
||||
export function normalizeHalloPetraWebhook(payload: unknown, expectedSecret: string): TelephonyWebhookNormalizationResult {
|
||||
if (!validateHalloPetraWebhook(payload, expectedSecret)) return { ok: false, reason: "invalid_token" };
|
||||
return parseHalloPetraWebhookEvent(payload);
|
||||
}
|
||||
|
||||
/**
|
||||
* Map HalloPetra's documented post-call delivery into HiveGrid's stable event.
|
||||
* Pre-call, during-call and form webhooks are synchronous product contracts and
|
||||
* deliberately do not masquerade as call-lifecycle events here.
|
||||
*/
|
||||
export function parseHalloPetraWebhookEvent(payload: unknown): TelephonyWebhookNormalizationResult {
|
||||
if (!isRecord(payload)) return { ok: false, reason: "invalid_payload" };
|
||||
const envelope = payload as HalloPetraWebhookEnvelope;
|
||||
const native = unwrapNativeBody(envelope.body);
|
||||
if (!native) return { ok: false, reason: "invalid_payload" };
|
||||
|
||||
const webhookId = stringValue(native.webhook_id);
|
||||
const data = isRecord(native.data) ? native.data : null;
|
||||
if (!data) return { ok: false, reason: "invalid_payload" };
|
||||
|
||||
// `id`, `phone`, `duration`, `topic`, `summary` and `messages` distinguish
|
||||
// HalloPetra's post-call contract from its other webhook types.
|
||||
const providerCallId = stringValue(data.id);
|
||||
const externalNumber = normalizePhoneNumber(data.phone);
|
||||
if (!providerCallId || !externalNumber || !looksLikePostCall(data)) {
|
||||
return { ok: false, reason: "unsupported_event" };
|
||||
}
|
||||
|
||||
const occurredAtIso = dateValue(data.date) ?? dateValue(data.ended_at) ?? dateValue(envelope.receivedAtIso);
|
||||
if (!occurredAtIso) return { ok: false, reason: "invalid_payload" };
|
||||
const durationSeconds = nonNegativeInteger(data.duration);
|
||||
const endedAtIso = dateValue(data.ended_at) ?? occurredAtIso;
|
||||
const startedAtIso = dateValue(data.start_time) ?? subtractSeconds(endedAtIso, durationSeconds);
|
||||
const providerEvent = "post_call";
|
||||
|
||||
const event: TelephonyCallEvent = {
|
||||
provider: "hallopetra",
|
||||
providerEvent,
|
||||
type: "ended",
|
||||
dedupeKey: ["hallopetra", providerEvent, providerCallId, webhookId ?? "-"].join(":"),
|
||||
providerCallId,
|
||||
occurredAtIso,
|
||||
direction: "inbound",
|
||||
status: "completed",
|
||||
externalNumber,
|
||||
lineId: null,
|
||||
lineNumber: normalizePhoneNumber(data.inbound_phone_number),
|
||||
providerUserId: null,
|
||||
providerUserEmail: null,
|
||||
startedAtIso,
|
||||
answeredAtIso: startedAtIso,
|
||||
endedAtIso,
|
||||
durationSeconds,
|
||||
missed: false,
|
||||
missedReason: null,
|
||||
recordingUrl: httpsUrl(data.recording_url),
|
||||
voicemailUrl: null,
|
||||
noteMarkdown: buildHalloPetraSummary(payload),
|
||||
};
|
||||
return { ok: true, event };
|
||||
}
|
||||
|
||||
/** The observed post-call contract does not currently expose a recording URL. */
|
||||
export function getHalloPetraRecordingUrl(event: TelephonyCallEvent): string | null {
|
||||
return event.recordingUrl;
|
||||
}
|
||||
|
||||
/** Keep only the provider summary suitable for later note import, not a full transcript. */
|
||||
export function buildHalloPetraSummary(payload: unknown): string | null {
|
||||
if (!isRecord(payload)) return null;
|
||||
const native = unwrapNativeBody(payload.body);
|
||||
const data = native && isRecord(native.data) ? native.data : null;
|
||||
if (!data) return null;
|
||||
const topic = stringValue(data.topic);
|
||||
const summary = stringValue(data.summary);
|
||||
const parts = [topic ? `## ${topic}` : null, summary].filter((value): value is string => Boolean(value));
|
||||
return parts.length ? parts.join("\n\n").slice(0, MAX_SUMMARY_LENGTH) : null;
|
||||
}
|
||||
|
||||
function unwrapNativeBody(value: unknown): Record<string, unknown> | null {
|
||||
if (!isRecord(value)) return null;
|
||||
return isRecord(value.body) ? value.body : value;
|
||||
}
|
||||
|
||||
function looksLikePostCall(data: Record<string, unknown>): boolean {
|
||||
return "duration" in data || "topic" in data || "summary" in data || "messages" in data;
|
||||
}
|
||||
|
||||
function normalizePhoneNumber(value: unknown): string | null {
|
||||
if (typeof value !== "string" || !value.trim()) return null;
|
||||
const normalized = value.trim().replace(/[^+\d]/gu, "").replace(/(?!^)\+/gu, "");
|
||||
return E164_PATTERN.test(normalized) ? normalized : null;
|
||||
}
|
||||
|
||||
function stringValue(value: unknown): string | null {
|
||||
if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
|
||||
return typeof value === "string" && value.trim() ? value.trim() : null;
|
||||
}
|
||||
|
||||
function nonNegativeInteger(value: unknown): number | null {
|
||||
const numeric = typeof value === "string" && value.trim() ? Number(value) : value;
|
||||
return typeof numeric === "number" && Number.isSafeInteger(numeric) && numeric >= 0 ? numeric : null;
|
||||
}
|
||||
|
||||
function dateValue(value: unknown): string | null {
|
||||
if (typeof value !== "string" && typeof value !== "number") return null;
|
||||
const date = new Date(value);
|
||||
return Number.isNaN(date.getTime()) ? null : date.toISOString();
|
||||
}
|
||||
|
||||
function subtractSeconds(endedAtIso: string, durationSeconds: number | null): string {
|
||||
const endedAt = new Date(endedAtIso);
|
||||
return new Date(endedAt.getTime() - (durationSeconds ?? 0) * 1_000).toISOString();
|
||||
}
|
||||
|
||||
function httpsUrl(value: unknown): string | null {
|
||||
if (typeof value !== "string" || !value.trim()) return null;
|
||||
try {
|
||||
const url = new URL(value);
|
||||
return url.protocol === "https:" ? url.toString() : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
@@ -7,9 +7,29 @@ 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 "./microsoft/graphCalendarApi.js";
|
||||
export * from "./admin-calendar-provider.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";
|
||||
export * from "./admin-connections.js";
|
||||
export * from "./admin-email-sync.server.js";
|
||||
export * from "./admin-mail-provider.server.js";
|
||||
export * from "./admin-email-worker-tasks.server.js";
|
||||
export * from "./admin-email-attachments.server.js";
|
||||
export * from "./admin-mail-sync-provider.server.js";
|
||||
export * from "./admin-email-compose.js";
|
||||
export * from "./admin-email-domain.js";
|
||||
export * from "./admin-email-domain-worker.server.js";
|
||||
export * from "./admin-call-recordings.server.js";
|
||||
// AK-P15a · provider-neutral telephony contract + Aircall reference adapter.
|
||||
export * from "./telephony/index.js";
|
||||
export * from "./aircall/index.js";
|
||||
export * from "./hallopetra/index.js";
|
||||
// VR-P32a · KWP OAuth2/PKCE client + Apps Engine adapter.
|
||||
export * from "./kwp/index.js";
|
||||
// AK-P16d · HMAC verification for the public PandaDoc BYOK status webhook.
|
||||
export { verifyPandaDocWebhookSignature } from "./adapters/pandadoc-byok.js";
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
function source(file: string): string {
|
||||
return readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), file), "utf8");
|
||||
}
|
||||
|
||||
describe("KWP activity and sync-run summary i18n contract", () => {
|
||||
it("persists semantic keys for project, archive and inbound synchronization", () => {
|
||||
const sources = [
|
||||
source("project-domain.server.ts"),
|
||||
source("project-sync.server.ts"),
|
||||
source("archive-file.server.ts"),
|
||||
source("inbound-sync.server.ts"),
|
||||
].join("\n");
|
||||
|
||||
for (const key of [
|
||||
"activity.runtime.kwp.projectConnected",
|
||||
"activity.runtime.kwp.projectDisconnectedRestored",
|
||||
"activity.runtime.kwp.contactImported",
|
||||
"activity.runtime.kwp.projectMissing",
|
||||
"activity.runtime.kwp.projectStageChanged",
|
||||
"activity.runtime.kwp.projectUpdated",
|
||||
"activity.runtime.kwp.archiveImported",
|
||||
"activity.runtime.kwp.inboundDataUpdated",
|
||||
"integrations.sync.summary.kwpProjectImported",
|
||||
"integrations.sync.summary.kwpProjectSyncStarted",
|
||||
"integrations.sync.summary.kwpArchiveImportStarted",
|
||||
"integrations.sync.summary.kwpInboundSyncStarted",
|
||||
]) {
|
||||
expect(sources).toContain(key);
|
||||
}
|
||||
expect(sources).not.toMatch(/summaryText:\s*`(?:KWP|Projekt|Archivdatei|Termine)/u);
|
||||
});
|
||||
});
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const clientMocks = vi.hoisted(() => ({
|
||||
probeKwpHealth: vi.fn(),
|
||||
refreshKwpAccessToken: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("./client.js", async () => {
|
||||
const actual = await vi.importActual<typeof import("./client.js")>("./client.js");
|
||||
return {
|
||||
...actual,
|
||||
probeKwpHealth: clientMocks.probeKwpHealth,
|
||||
refreshKwpAccessToken: clientMocks.refreshKwpAccessToken,
|
||||
};
|
||||
});
|
||||
|
||||
import { getCatalogEntry } from "../catalog.js";
|
||||
import { kwpAdapter } from "./adapter.js";
|
||||
import { KWP_APP_ID, KWP_OIDC_ISSUER, KWP_REQUIRED_OAUTH_SCOPES, KwpError, type KwpCredentials } from "./client.js";
|
||||
|
||||
const CREDENTIALS: KwpCredentials = {
|
||||
accessToken: "kwp-access-token",
|
||||
refreshToken: "kwp-refresh-token",
|
||||
expiresAt: "2026-07-20T13:00:00.000Z",
|
||||
issuer: KWP_OIDC_ISSUER,
|
||||
clientId: "_extern-geerkens2",
|
||||
clientSecret: "kwp-client-secret",
|
||||
customerCode: "geerkens2",
|
||||
scopes: [...KWP_REQUIRED_OAUTH_SCOPES],
|
||||
};
|
||||
|
||||
afterEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
describe("KWP Apps Engine adapter", () => {
|
||||
it("registers KWP as an ERP OAuth2 app with no manual credential fields", () => {
|
||||
expect(kwpAdapter).toMatchObject({ key: KWP_APP_ID, connectionType: "oauth2" });
|
||||
expect(kwpAdapter.refreshToken).toEqual(expect.any(Function));
|
||||
expect(getCatalogEntry(KWP_APP_ID)).toMatchObject({
|
||||
key: KWP_APP_ID,
|
||||
category: "erp",
|
||||
connectionType: "oauth2",
|
||||
connectionSchema: { fields: [] },
|
||||
});
|
||||
});
|
||||
|
||||
it("maps a successful read-only version probe to active", async () => {
|
||||
clientMocks.probeKwpHealth.mockResolvedValue('{"version":"8.1 N3"}');
|
||||
|
||||
await expect(kwpAdapter.validateConnection(CREDENTIALS)).resolves.toEqual({
|
||||
ok: true,
|
||||
health: "active",
|
||||
messageKey: "integrations.kwp.health.active",
|
||||
});
|
||||
expect(clientMocks.probeKwpHealth).toHaveBeenCalledWith(CREDENTIALS);
|
||||
});
|
||||
|
||||
it("maps provider and credential failures to Klartext-ready health states", async () => {
|
||||
clientMocks.probeKwpHealth.mockRejectedValueOnce(new KwpError("rate_limit_exceeded", 429));
|
||||
await expect(kwpAdapter.healthCheck(CREDENTIALS)).resolves.toEqual({
|
||||
ok: false,
|
||||
health: "degraded",
|
||||
messageKey: "integrations.kwp.health.rateLimited",
|
||||
});
|
||||
|
||||
clientMocks.probeKwpHealth.mockRejectedValueOnce(new KwpError("auth_token_invalid", 401));
|
||||
await expect(kwpAdapter.healthCheck(CREDENTIALS)).resolves.toEqual({
|
||||
ok: false,
|
||||
health: "broken",
|
||||
messageKey: "integrations.kwp.health.tokenInvalid",
|
||||
});
|
||||
|
||||
clientMocks.probeKwpHealth.mockRejectedValueOnce(new KwpError("mandant_unconfirmed"));
|
||||
await expect(kwpAdapter.healthCheck(CREDENTIALS)).resolves.toEqual({
|
||||
ok: false,
|
||||
health: "broken",
|
||||
messageKey: "integrations.kwp.health.mandantUnconfirmed",
|
||||
});
|
||||
});
|
||||
|
||||
it("returns rotated credentials and expiry through the generic refresh contract", async () => {
|
||||
const rotated: KwpCredentials = {
|
||||
...CREDENTIALS,
|
||||
accessToken: "rotated-access",
|
||||
refreshToken: "rotated-refresh",
|
||||
expiresAt: "2026-07-20T14:00:00.000Z",
|
||||
};
|
||||
clientMocks.refreshKwpAccessToken.mockResolvedValue(rotated);
|
||||
|
||||
await expect(kwpAdapter.refreshToken?.(CREDENTIALS)).resolves.toEqual({
|
||||
creds: rotated,
|
||||
expiresAt: new Date("2026-07-20T14:00:00.000Z"),
|
||||
});
|
||||
});
|
||||
|
||||
it("fails closed when generic sync is invoked before the queue slice", async () => {
|
||||
await expect(kwpAdapter.sync(CREDENTIALS)).rejects.toThrow("kwp_sync_not_available");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,60 @@
|
||||
import {
|
||||
registerIntegrationAdapter,
|
||||
type AdapterResult,
|
||||
type AdapterSyncOutcome,
|
||||
type AdapterTokenRefresh,
|
||||
type IntegrationAdapter,
|
||||
} from "@hivegrid/foundation";
|
||||
|
||||
import { KWP_APP_ID, KwpError, probeKwpHealth, refreshKwpAccessToken, type KwpCredentials } from "./client.js";
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof KwpError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_invalid":
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.tokenInvalid" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
// Existing connections may be marked degraded by healthCheck, but a
|
||||
// fresh OAuth callback must not persist credentials without one proven
|
||||
// Resource-API response. `ok: false` keeps validation fail-closed.
|
||||
return { ok: false, health: "degraded", messageKey: "integrations.kwp.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "integrations.kwp.health.providerOutage" };
|
||||
case "relay_host_invalid":
|
||||
case "relay_not_found":
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.relayInvalid" };
|
||||
case "invalid_credentials":
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.credentialsInvalid" };
|
||||
case "mandant_unconfirmed":
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.mandantUnconfirmed" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "integrations.kwp.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(credentials: KwpCredentials): Promise<AdapterResult> {
|
||||
try {
|
||||
await probeKwpHealth(credentials);
|
||||
return { ok: true, health: "active", messageKey: "integrations.kwp.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const kwpAdapter: IntegrationAdapter<KwpCredentials> = registerIntegrationAdapter<KwpCredentials>({
|
||||
key: KWP_APP_ID,
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (credentials: KwpCredentials): Promise<AdapterTokenRefresh<KwpCredentials>> => {
|
||||
const next = await refreshKwpAccessToken(credentials);
|
||||
return { creds: next, expiresAt: new Date(next.expiresAt) };
|
||||
},
|
||||
// Sync/outbox delivery remains in the later VR-P32a slice. Reject explicitly
|
||||
// so an accidental generic invocation cannot record a false green no-op run.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.reject(new Error("kwp_sync_not_available")),
|
||||
});
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
|
||||
import {
|
||||
type KwpArchiveDiscoveryBatch,
|
||||
type KwpArchiveDiscoveryCursor,
|
||||
loadKwpArchiveDiscoveryBatch,
|
||||
} from "./inbound-reader.js";
|
||||
import { KwpProjectDomainError } from "./project-domain.server.js";
|
||||
|
||||
export async function discoverKwpProjectArchiveBatch(input: {
|
||||
readonly bindingId: string;
|
||||
readonly cursor?: KwpArchiveDiscoveryCursor;
|
||||
}): Promise<KwpArchiveDiscoveryBatch> {
|
||||
const bindingId = normalizeId(input.bindingId);
|
||||
const tenantId = requireTenantContext();
|
||||
const prepared = await getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findFirst({
|
||||
where: {
|
||||
id: bindingId,
|
||||
tenantId,
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
state: "active",
|
||||
},
|
||||
select: { dataConnectionId: true, externalId: true, localId: true },
|
||||
});
|
||||
if (!binding) throw new KwpProjectDomainError("project_not_found");
|
||||
const [project, connection] = await Promise.all([
|
||||
tx.projekt.findFirst({
|
||||
where: { id: binding.localId, tenantId, archivedAt: null },
|
||||
select: { id: true },
|
||||
}),
|
||||
tx.dataConnection.findFirst({
|
||||
where: {
|
||||
id: binding.dataConnectionId,
|
||||
tenantId,
|
||||
appId: "kwp",
|
||||
archivedAt: null,
|
||||
connectionStatus: { in: ["active", "degraded"] },
|
||||
},
|
||||
select: { id: true },
|
||||
}),
|
||||
]);
|
||||
if (!project || !connection) throw new KwpProjectDomainError("project_not_found");
|
||||
return {
|
||||
connectionId: binding.dataConnectionId,
|
||||
externalProjectNumber: binding.externalId,
|
||||
};
|
||||
});
|
||||
|
||||
return loadKwpArchiveDiscoveryBatch({
|
||||
...prepared,
|
||||
...(input.cursor ? { cursor: input.cursor } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function requireTenantContext(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpProjectDomainError("project_not_found");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function normalizeId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{8,191}$/u.test(normalized)) throw new KwpProjectDomainError("project_not_found");
|
||||
return normalized;
|
||||
}
|
||||
+59
@@ -0,0 +1,59 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
loadBatch: vi.fn(),
|
||||
transaction: vi.fn(),
|
||||
bindingFindFirst: vi.fn(),
|
||||
projectFindFirst: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({ $transaction: mocks.transaction }),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({ getRlsExecutionContext: mocks.getRlsExecutionContext }));
|
||||
vi.mock("./inbound-reader.js", () => ({ loadKwpArchiveDiscoveryBatch: mocks.loadBatch }));
|
||||
|
||||
import { discoverKwpProjectArchiveBatch } from "./archive-discovery.server.js";
|
||||
|
||||
const tx = {
|
||||
appEntityBinding: { findFirst: mocks.bindingFindFirst },
|
||||
projekt: { findFirst: mocks.projectFindFirst },
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
};
|
||||
|
||||
describe("KWP archive discovery", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1" });
|
||||
mocks.transaction.mockImplementation(async (callback) => callback(tx));
|
||||
mocks.bindingFindFirst.mockResolvedValue({ dataConnectionId: "connection-1", externalId: "P-100", localId: "project-1" });
|
||||
mocks.projectFindFirst.mockResolvedValue({ id: "project-1" });
|
||||
mocks.connectionFindFirst.mockResolvedValue({ id: "connection-1" });
|
||||
mocks.loadBatch.mockResolvedValue({ archiveFiles: [], processedFolders: 1, cursor: null });
|
||||
});
|
||||
|
||||
it("resolves the tenant-scoped project binding before provider reads", async () => {
|
||||
const cursor = { pendingFolderIds: [5], visitedFolderIds: [0, 1, 2, 3, 4] };
|
||||
await expect(discoverKwpProjectArchiveBatch({ bindingId: "binding_1", cursor })).resolves.toEqual({
|
||||
archiveFiles: [],
|
||||
processedFolders: 1,
|
||||
cursor: null,
|
||||
});
|
||||
expect(mocks.bindingFindFirst).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: expect.objectContaining({ tenantId: "tenant-1", state: "active" }),
|
||||
}));
|
||||
expect(mocks.loadBatch).toHaveBeenCalledWith({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "P-100",
|
||||
cursor,
|
||||
});
|
||||
});
|
||||
|
||||
it("fails closed before provider I/O when the binding is unavailable", async () => {
|
||||
mocks.bindingFindFirst.mockResolvedValueOnce(null);
|
||||
await expect(discoverKwpProjectArchiveBatch({ bindingId: "binding_1" })).rejects.toThrow("project_not_found");
|
||||
expect(mocks.loadBatch).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
+655
@@ -0,0 +1,655 @@
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
|
||||
import { logActivity } from "@hivegrid/activity";
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import type { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
import { TenantStorageCapacityError, withTenantStorageWriteReservation } from "@hivegrid/db/storage-capacity.server";
|
||||
import { auditEvent } from "@hivegrid/foundation";
|
||||
import { fetchOutboundHttpWithRedirects, readLimitedResponseText, type OutboundHttpAddressResolver } from "@hivegrid/foundation/outbound-http";
|
||||
import { z } from "zod";
|
||||
|
||||
import { KWP_INBOUND_BOUNDS, type KwpInboundArchiveFile } from "./inbound-reader.js";
|
||||
import { KwpProjectDomainError } from "./project-domain.server.js";
|
||||
import { executeKwpReadOperation } from "./resource-client.server.js";
|
||||
import { fingerprintKwpSnapshot } from "./resource-client.js";
|
||||
|
||||
const ARCHIVE_FILE_ENTITY_TYPE = "kwp_archive_file";
|
||||
const EXCHANGE_JSON_LIMIT_BYTES = 64 * 1024;
|
||||
|
||||
const exportInfoSchema = z
|
||||
.object({
|
||||
dateigroesse: z.number().int(),
|
||||
exchangeFileUri: z.string().url().nullable().optional(),
|
||||
dateiname: z.string().nullable().optional(),
|
||||
})
|
||||
.strict();
|
||||
|
||||
export type KwpArchiveStorage = {
|
||||
putObject(input: {
|
||||
key: string;
|
||||
body: Uint8Array | ReadableStream<Uint8Array>;
|
||||
contentType?: string;
|
||||
metadata?: Record<string, string>;
|
||||
}): Promise<{ bucket: string; key: string }>;
|
||||
deleteObject(input: { key: string }): Promise<unknown>;
|
||||
};
|
||||
|
||||
export type KwpArchiveScanEnqueuer = (input: {
|
||||
readonly bucket: string;
|
||||
readonly key: string;
|
||||
readonly tenantId: string;
|
||||
readonly fileId: string;
|
||||
readonly contentType: string;
|
||||
}) => Promise<void>;
|
||||
|
||||
export type KwpArchiveFileSyncResult = {
|
||||
readonly runId: string;
|
||||
readonly fileId: string;
|
||||
readonly projectId: string;
|
||||
readonly storageKey: string;
|
||||
readonly state: "created" | "replayed";
|
||||
};
|
||||
|
||||
export async function syncKwpArchiveFile(input: {
|
||||
readonly bindingId: string;
|
||||
readonly archiveFile: KwpInboundArchiveFile;
|
||||
readonly storage: KwpArchiveStorage;
|
||||
readonly storageBucket: string;
|
||||
readonly enqueueScan: KwpArchiveScanEnqueuer;
|
||||
readonly fetchImpl?: typeof fetch;
|
||||
readonly addressResolver?: OutboundHttpAddressResolver;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpArchiveFileSyncResult> {
|
||||
const now = input.now ?? new Date();
|
||||
const prepared = await prepareArchiveFileSync(normalizeId(input.bindingId), input.archiveFile, normalizeStorageBucket(input.storageBucket), now);
|
||||
if (prepared.existing) {
|
||||
if (prepared.existing.needsScan) {
|
||||
await input.enqueueScan({
|
||||
bucket: prepared.existing.bucket,
|
||||
key: prepared.existing.storageKey,
|
||||
tenantId: prepared.tenantId,
|
||||
fileId: prepared.existing.fileId,
|
||||
contentType: prepared.existing.mimeType,
|
||||
});
|
||||
}
|
||||
return {
|
||||
runId: prepared.runId,
|
||||
fileId: prepared.existing.fileId,
|
||||
projectId: prepared.projectId,
|
||||
storageKey: prepared.existing.storageKey,
|
||||
state: "replayed",
|
||||
};
|
||||
}
|
||||
try {
|
||||
const exported = await exportArchiveFile({
|
||||
connectionId: prepared.connectionId,
|
||||
descriptor: input.archiveFile,
|
||||
fetchImpl: input.fetchImpl,
|
||||
addressResolver: input.addressResolver,
|
||||
});
|
||||
const storageKey = buildArchiveStorageKey(prepared.tenantId, prepared.connectionId, input.archiveFile.externalId, exported.displayName);
|
||||
const targetFileId = `file_${randomUUID()}`;
|
||||
const outcome = await withTenantStorageWriteReservation({
|
||||
reservation: {
|
||||
tenantId: prepared.tenantId,
|
||||
actorUserId: prepared.actorUserId,
|
||||
targetFileId,
|
||||
originalFilename: exported.displayName,
|
||||
mimeType: exported.mimeType,
|
||||
sizeBytes: exported.sizeBytes,
|
||||
},
|
||||
runTransaction: (operation) => getDbClient().$transaction(operation),
|
||||
upload: () =>
|
||||
input.storage.putObject({
|
||||
key: storageKey,
|
||||
body: exported.body,
|
||||
contentType: exported.mimeType,
|
||||
metadata: {
|
||||
source: "kwp",
|
||||
project: createHash("sha256").update(prepared.projectId).digest("hex"),
|
||||
external: createHash("sha256").update(input.archiveFile.externalId).digest("hex"),
|
||||
},
|
||||
}),
|
||||
commit: async (tx, stored) => {
|
||||
const created = await persistArchiveFile(
|
||||
tx,
|
||||
prepared,
|
||||
input.archiveFile,
|
||||
targetFileId,
|
||||
{
|
||||
storageKey: stored.key,
|
||||
bucket: stored.bucket,
|
||||
displayName: exported.displayName,
|
||||
mimeType: exported.mimeType,
|
||||
sizeBytes: exported.sizeBytes,
|
||||
},
|
||||
now
|
||||
);
|
||||
return { ...created, bucket: stored.bucket, uploadedStorageKey: stored.key };
|
||||
},
|
||||
rollbackUpload: (stored) => input.storage.deleteObject({ key: stored?.key ?? storageKey }).then(() => undefined),
|
||||
});
|
||||
if (outcome.replayed && outcome.uploadedStorageKey !== outcome.storageKey) {
|
||||
await input.storage.deleteObject({ key: outcome.uploadedStorageKey });
|
||||
}
|
||||
await input.enqueueScan({
|
||||
bucket: outcome.bucket,
|
||||
key: outcome.storageKey,
|
||||
tenantId: prepared.tenantId,
|
||||
fileId: outcome.fileId,
|
||||
contentType: exported.mimeType,
|
||||
});
|
||||
return {
|
||||
runId: prepared.runId,
|
||||
fileId: outcome.fileId,
|
||||
projectId: prepared.projectId,
|
||||
storageKey: outcome.storageKey,
|
||||
state: outcome.replayed ? "replayed" : "created",
|
||||
};
|
||||
} catch (error) {
|
||||
if (error instanceof TenantStorageCapacityError && error.code === "STORAGE_RESERVATION_INVALID") {
|
||||
const replay = await loadArchiveFileReplay(prepared, input.archiveFile, now).catch(() => null);
|
||||
if (replay) {
|
||||
if (replay.needsScan) {
|
||||
await input.enqueueScan({
|
||||
bucket: input.storageBucket,
|
||||
key: replay.storageKey,
|
||||
tenantId: prepared.tenantId,
|
||||
fileId: replay.fileId,
|
||||
contentType: replay.mimeType,
|
||||
});
|
||||
}
|
||||
return {
|
||||
runId: prepared.runId,
|
||||
fileId: replay.fileId,
|
||||
projectId: prepared.projectId,
|
||||
storageKey: replay.storageKey,
|
||||
state: "replayed",
|
||||
};
|
||||
}
|
||||
}
|
||||
await failArchiveRun(prepared, error, now);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
type PreparedArchiveFileSync = {
|
||||
readonly tenantId: string;
|
||||
readonly runId: string;
|
||||
readonly connectionId: string;
|
||||
readonly projectId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
readonly actorUserId: string;
|
||||
readonly existing: {
|
||||
readonly fileId: string;
|
||||
readonly storageKey: string;
|
||||
readonly mimeType: string;
|
||||
readonly bucket: string;
|
||||
readonly needsScan: boolean;
|
||||
} | null;
|
||||
};
|
||||
|
||||
async function prepareArchiveFileSync(
|
||||
bindingId: string,
|
||||
archiveFile: KwpInboundArchiveFile,
|
||||
storageBucket: string,
|
||||
now: Date
|
||||
): Promise<PreparedArchiveFileSync> {
|
||||
const tenantId = requireTenantContext();
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findFirst({
|
||||
where: {
|
||||
id: bindingId,
|
||||
tenantId,
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
state: "active",
|
||||
},
|
||||
select: { dataConnectionId: true, externalId: true, localId: true },
|
||||
});
|
||||
if (!binding) throw new KwpProjectDomainError("project_not_found");
|
||||
const [connection, project, existingBinding] = await Promise.all([
|
||||
tx.dataConnection.findFirst({
|
||||
where: {
|
||||
id: binding.dataConnectionId,
|
||||
tenantId,
|
||||
appId: "kwp",
|
||||
archivedAt: null,
|
||||
connectionStatus: { in: ["active", "degraded"] },
|
||||
},
|
||||
select: { createdByUserId: true },
|
||||
}),
|
||||
tx.projekt.findFirst({
|
||||
where: { id: binding.localId, tenantId, archivedAt: null },
|
||||
select: { id: true, createdByUserId: true },
|
||||
}),
|
||||
tx.appEntityBinding.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalEntityType_externalId: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
externalEntityType: ARCHIVE_FILE_ENTITY_TYPE,
|
||||
externalId: archiveFile.externalId,
|
||||
},
|
||||
},
|
||||
select: { localId: true },
|
||||
}),
|
||||
]);
|
||||
if (!connection || !project) throw new KwpProjectDomainError("project_not_found");
|
||||
const actorUserId = await resolveActorUserId(tx, tenantId, connection.createdByUserId ?? project.createdByUserId);
|
||||
if (!actorUserId) throw new KwpProjectDomainError("project_not_found");
|
||||
const existingFile = existingBinding
|
||||
? await tx.file.findFirst({
|
||||
where: { id: existingBinding.localId, tenantId, archivedAt: null },
|
||||
select: { id: true, storageKey: true, mimeType: true, scanStatus: true },
|
||||
})
|
||||
: null;
|
||||
const run = await tx.appSyncRun.create({
|
||||
data: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
kind: "scheduled",
|
||||
status: existingFile ? "completed" : "running",
|
||||
itemsTotal: 1,
|
||||
itemsSucceeded: existingFile ? 1 : 0,
|
||||
summaryText: existingFile ? "integrations.sync.summary.kwpArchiveAlreadyPresent" : "integrations.sync.summary.kwpArchiveImportStarted",
|
||||
startedAt: now,
|
||||
completedAt: existingFile ? now : null,
|
||||
},
|
||||
});
|
||||
return {
|
||||
tenantId,
|
||||
runId: run.id,
|
||||
connectionId: binding.dataConnectionId,
|
||||
projectId: project.id,
|
||||
externalProjectNumber: binding.externalId,
|
||||
actorUserId,
|
||||
existing: existingFile
|
||||
? {
|
||||
fileId: existingFile.id,
|
||||
storageKey: existingFile.storageKey,
|
||||
mimeType: existingFile.mimeType,
|
||||
bucket: storageBucket,
|
||||
needsScan: existingFile.scanStatus === "pending" || existingFile.scanStatus === "skipped",
|
||||
}
|
||||
: null,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function exportArchiveFile(input: {
|
||||
readonly connectionId: string;
|
||||
readonly descriptor: KwpInboundArchiveFile;
|
||||
readonly fetchImpl?: typeof fetch;
|
||||
readonly addressResolver?: OutboundHttpAddressResolver;
|
||||
}): Promise<{
|
||||
readonly body: Uint8Array;
|
||||
readonly displayName: string;
|
||||
readonly mimeType: string;
|
||||
readonly sizeBytes: number;
|
||||
}> {
|
||||
const exportInfo = exportInfoSchema.parse(
|
||||
await executeKwpReadOperation({
|
||||
connectionId: input.connectionId,
|
||||
operationId: "archivExternalExportDatei",
|
||||
operationInput: {
|
||||
query: {
|
||||
guid: randomUUID(),
|
||||
revisionId: input.descriptor.revisionId,
|
||||
},
|
||||
},
|
||||
})
|
||||
);
|
||||
if (!exportInfo.exchangeFileUri || exportInfo.dateigroesse < 0 || exportInfo.dateigroesse > KWP_INBOUND_BOUNDS.maxArchiveFileBytes) {
|
||||
throw new KwpProjectDomainError("project_not_found");
|
||||
}
|
||||
const exchangeResponse = await safeDownload(exportInfo.exchangeFileUri, input);
|
||||
if (!exchangeResponse.ok) throw new Error("KWP archive exchange request failed.");
|
||||
const exchange = await readLimitedResponseText(exchangeResponse, EXCHANGE_JSON_LIMIT_BYTES);
|
||||
if (exchange.truncated) throw new Error("KWP archive exchange response exceeded its limit.");
|
||||
const downloadUrl = parseExchangeDownloadUrl(exchange.body);
|
||||
const fileResponse = await safeDownload(downloadUrl, input);
|
||||
if (!fileResponse.ok || !fileResponse.body) throw new Error("KWP archive download failed.");
|
||||
const declaredLength = parseContentLength(fileResponse.headers.get("content-length"));
|
||||
const advertisedSize = declaredLength ?? exportInfo.dateigroesse;
|
||||
if (advertisedSize < 0 || advertisedSize > KWP_INBOUND_BOUNDS.maxArchiveFileBytes) {
|
||||
await fileResponse.body.cancel().catch(() => undefined);
|
||||
throw new Error("KWP archive file exceeded its size limit.");
|
||||
}
|
||||
const body = new Uint8Array(await new Response(limitBody(fileResponse.body, KWP_INBOUND_BOUNDS.maxArchiveFileBytes)).arrayBuffer());
|
||||
if (body.byteLength <= 0 || (declaredLength !== null && body.byteLength !== declaredLength)) {
|
||||
throw new Error("KWP archive file size did not match its declared size.");
|
||||
}
|
||||
return {
|
||||
body,
|
||||
displayName: safeFileName(exportInfo.dateiname ?? input.descriptor.displayName),
|
||||
mimeType: safeMimeType(fileResponse.headers.get("content-type"), input.descriptor.providerFileType),
|
||||
sizeBytes: body.byteLength,
|
||||
};
|
||||
}
|
||||
|
||||
async function safeDownload(
|
||||
url: string,
|
||||
input: { readonly fetchImpl?: typeof fetch; readonly addressResolver?: OutboundHttpAddressResolver }
|
||||
): Promise<Response> {
|
||||
return fetchOutboundHttpWithRedirects(
|
||||
url,
|
||||
{
|
||||
method: "GET",
|
||||
headers: { accept: "application/json, application/octet-stream;q=0.9, */*;q=0.1" },
|
||||
},
|
||||
{
|
||||
fetchImpl: input.fetchImpl,
|
||||
addressResolver: input.addressResolver,
|
||||
timeoutMs: 30_000,
|
||||
redirectLimit: 3,
|
||||
urlValidator: requireHttpsUrl,
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
function parseExchangeDownloadUrl(value: string): string {
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(value);
|
||||
} catch {
|
||||
throw new Error("KWP archive exchange response was not valid JSON.");
|
||||
}
|
||||
const candidate =
|
||||
typeof parsed === "string"
|
||||
? parsed
|
||||
: isRecord(parsed)
|
||||
? ["downloadUrl", "downloadUri", "fileUrl", "fileUri", "url", "uri"]
|
||||
.map((key) => parsed[key])
|
||||
.find((entry): entry is string => typeof entry === "string")
|
||||
: undefined;
|
||||
if (!candidate) throw new Error("KWP archive exchange response did not contain a download URL.");
|
||||
return requireHttpsUrl(candidate);
|
||||
}
|
||||
|
||||
async function persistArchiveFile(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedArchiveFileSync,
|
||||
descriptor: KwpInboundArchiveFile,
|
||||
targetFileId: string,
|
||||
stored: {
|
||||
readonly storageKey: string;
|
||||
readonly bucket: string;
|
||||
readonly displayName: string;
|
||||
readonly mimeType: string;
|
||||
readonly sizeBytes: number;
|
||||
},
|
||||
now: Date
|
||||
): Promise<{ readonly fileId: string; readonly replayed: boolean; readonly storageKey: string }> {
|
||||
const replay = await tx.appEntityBinding.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalEntityType_externalId: {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
externalEntityType: ARCHIVE_FILE_ENTITY_TYPE,
|
||||
externalId: descriptor.externalId,
|
||||
},
|
||||
},
|
||||
select: { localId: true },
|
||||
});
|
||||
if (replay) {
|
||||
const existingFile = await tx.file.findFirstOrThrow({
|
||||
where: { id: replay.localId, tenantId: prepared.tenantId },
|
||||
select: { id: true, storageKey: true },
|
||||
});
|
||||
await completeArchiveRun(tx, prepared, now);
|
||||
return { fileId: existingFile.id, storageKey: existingFile.storageKey, replayed: true };
|
||||
}
|
||||
const file = await tx.file.create({
|
||||
data: {
|
||||
id: targetFileId,
|
||||
tenantId: prepared.tenantId,
|
||||
createdByUserId: prepared.actorUserId,
|
||||
displayName: stored.displayName,
|
||||
mimeType: stored.mimeType,
|
||||
sizeBytes: stored.sizeBytes,
|
||||
storageKey: stored.storageKey,
|
||||
previewStatus: "pending",
|
||||
scanStatus: "pending",
|
||||
source: "api",
|
||||
tags: ["kwp"],
|
||||
notes: descriptor.documentType,
|
||||
},
|
||||
});
|
||||
await tx.fileEntityLink.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
createdByUserId: prepared.actorUserId,
|
||||
fileId: file.id,
|
||||
entityType: "project",
|
||||
entityId: prepared.projectId,
|
||||
linkRole: "kwp_archive",
|
||||
},
|
||||
});
|
||||
const normalizedSnapshot = { projectId: prepared.projectId, ...descriptor };
|
||||
await tx.appEntityBinding.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
externalEntityType: ARCHIVE_FILE_ENTITY_TYPE,
|
||||
localEntityType: "file",
|
||||
externalId: descriptor.externalId,
|
||||
localId: file.id,
|
||||
state: "active",
|
||||
normalizedSnapshot: normalizedSnapshot as Prisma.InputJsonValue,
|
||||
fingerprint: fingerprintKwpSnapshot(normalizedSnapshot),
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
},
|
||||
});
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType: ARCHIVE_FILE_ENTITY_TYPE,
|
||||
entityId: file.id,
|
||||
externalId: descriptor.externalId,
|
||||
operation: "created",
|
||||
status: "synced",
|
||||
},
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId: prepared.tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_ARCHIVE_FILE_IMPORTED",
|
||||
targetType: "file",
|
||||
targetId: file.id,
|
||||
metadata: {
|
||||
source: "kwp",
|
||||
projectId: prepared.projectId,
|
||||
revision: descriptor.revision,
|
||||
},
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
await logActivity(
|
||||
{
|
||||
tenantId: prepared.tenantId,
|
||||
actorKind: "system",
|
||||
activityType: "project_updated",
|
||||
subjectType: "project",
|
||||
subjectId: prepared.projectId,
|
||||
summaryText: "activity.runtime.kwp.archiveImported",
|
||||
metadata: { source: "kwp", fileId: file.id },
|
||||
},
|
||||
{ client: tx }
|
||||
);
|
||||
await completeArchiveRun(tx, prepared, now);
|
||||
return { fileId: file.id, storageKey: file.storageKey, replayed: false };
|
||||
}
|
||||
|
||||
async function completeArchiveRun(tx: Prisma.TransactionClient, prepared: PreparedArchiveFileSync, now: Date): Promise<void> {
|
||||
await tx.appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: "completed",
|
||||
itemsTotal: 1,
|
||||
itemsSucceeded: 1,
|
||||
summaryText: "integrations.sync.summary.kwpArchiveImported",
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async function loadArchiveFileReplay(
|
||||
prepared: PreparedArchiveFileSync,
|
||||
descriptor: KwpInboundArchiveFile,
|
||||
now: Date
|
||||
): Promise<{ readonly fileId: string; readonly storageKey: string; readonly mimeType: string; readonly needsScan: boolean } | null> {
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalEntityType_externalId: {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
externalEntityType: ARCHIVE_FILE_ENTITY_TYPE,
|
||||
externalId: descriptor.externalId,
|
||||
},
|
||||
},
|
||||
select: { localId: true },
|
||||
});
|
||||
if (!binding) return null;
|
||||
const file = await tx.file.findFirst({
|
||||
where: { id: binding.localId, tenantId: prepared.tenantId },
|
||||
select: { id: true, storageKey: true, mimeType: true, scanStatus: true },
|
||||
});
|
||||
if (!file) return null;
|
||||
await completeArchiveRun(tx, prepared, now);
|
||||
return {
|
||||
fileId: file.id,
|
||||
storageKey: file.storageKey,
|
||||
mimeType: file.mimeType,
|
||||
needsScan: file.scanStatus === "pending" || file.scanStatus === "skipped",
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function failArchiveRun(prepared: PreparedArchiveFileSync, error: unknown, now: Date): Promise<void> {
|
||||
await getDbClient().appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: "failed",
|
||||
itemsTotal: 1,
|
||||
itemsFailed: 1,
|
||||
summaryText: buildArchiveFailureSummary(error),
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function buildArchiveFailureSummary(error: unknown): string {
|
||||
const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : null;
|
||||
if (code === "provider_outage" || code === "rate_limit_exceeded" || code === "auth_token_invalid") {
|
||||
return "integrations.sync.summary.kwpArchiveTemporaryFailure";
|
||||
}
|
||||
if (code === "auth_scope_missing" || code === "capability_paused" || code === "contract_drift") {
|
||||
return "integrations.sync.summary.kwpArchiveUnavailable";
|
||||
}
|
||||
return "integrations.sync.summary.kwpArchiveFailed";
|
||||
}
|
||||
|
||||
async function resolveActorUserId(tx: Prisma.TransactionClient, tenantId: string, preferredUserId: string | null | undefined): Promise<string | null> {
|
||||
if (preferredUserId) {
|
||||
const preferred = await tx.tenantUser.findFirst({
|
||||
where: { tenantId, userId: preferredUserId },
|
||||
select: { userId: true },
|
||||
});
|
||||
if (preferred) return preferred.userId;
|
||||
}
|
||||
const fallback = await tx.tenantUser.findFirst({
|
||||
where: { tenantId },
|
||||
select: { userId: true },
|
||||
orderBy: { createdAt: "asc" },
|
||||
});
|
||||
return fallback?.userId ?? null;
|
||||
}
|
||||
|
||||
function limitBody(body: ReadableStream<Uint8Array>, limit: number): ReadableStream<Uint8Array> {
|
||||
let bytes = 0;
|
||||
return body.pipeThrough(
|
||||
new TransformStream<Uint8Array, Uint8Array>({
|
||||
transform(chunk, controller) {
|
||||
bytes += chunk.byteLength;
|
||||
if (bytes > limit) {
|
||||
controller.error(new Error("KWP archive file exceeded its size limit."));
|
||||
return;
|
||||
}
|
||||
controller.enqueue(chunk);
|
||||
},
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
function buildArchiveStorageKey(tenantId: string, connectionId: string, externalId: string, fileName: string): string {
|
||||
const identity = createHash("sha256").update(`${connectionId}:${externalId}`).digest("hex");
|
||||
return `tenants/${safePathPart(tenantId)}/kwp-archive/${identity}/${safeFileName(fileName)}`;
|
||||
}
|
||||
|
||||
function safeFileName(value: string): string {
|
||||
const name = value.replaceAll("\\", "/").split("/").at(-1)?.trim() ?? "";
|
||||
const normalized = name.replace(/[\u0000-\u001f\u007f]/gu, "").slice(0, 255);
|
||||
return normalized || "kwp-datei.bin";
|
||||
}
|
||||
|
||||
function safePathPart(value: string): string {
|
||||
return value.replace(/[^A-Za-z0-9_-]/gu, "_").slice(0, 191);
|
||||
}
|
||||
|
||||
function safeMimeType(contentType: string | null, providerType: string | null): string {
|
||||
const fromHeader = contentType?.split(";")[0]?.trim().toLowerCase();
|
||||
if (fromHeader && /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u.test(fromHeader)) {
|
||||
return fromHeader;
|
||||
}
|
||||
if (providerType?.trim().toLowerCase() === "pdf") return "application/pdf";
|
||||
return "application/octet-stream";
|
||||
}
|
||||
|
||||
function parseContentLength(value: string | null): number | null {
|
||||
if (!value || !/^\d+$/u.test(value)) return null;
|
||||
const parsed = Number(value);
|
||||
return Number.isSafeInteger(parsed) ? parsed : null;
|
||||
}
|
||||
|
||||
function requireHttpsUrl(value: string): string {
|
||||
const url = new URL(value);
|
||||
if (url.protocol !== "https:" || url.username || url.password) {
|
||||
throw new Error("KWP archive URL is not allowed.");
|
||||
}
|
||||
return url.toString();
|
||||
}
|
||||
|
||||
function normalizeStorageBucket(value: string): string {
|
||||
const bucket = value.trim();
|
||||
if (!bucket || bucket.length > 255) throw new Error("KWP archive storage bucket is invalid.");
|
||||
return bucket;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function requireTenantContext(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpProjectDomainError("project_not_found");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function normalizeId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{3,191}$/u.test(normalized)) throw new KwpProjectDomainError("project_not_found");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
export const __kwpArchiveInternals = {
|
||||
buildArchiveStorageKey,
|
||||
parseExchangeDownloadUrl,
|
||||
safeFileName,
|
||||
safeMimeType,
|
||||
};
|
||||
+360
@@ -0,0 +1,360 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
auditEvent: vi.fn(),
|
||||
logActivity: vi.fn(),
|
||||
executeRead: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
transaction: vi.fn(),
|
||||
runUpdateMany: vi.fn(),
|
||||
projectBindingFindFirst: vi.fn(),
|
||||
archiveBindingFindUnique: vi.fn(),
|
||||
archiveBindingCreate: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
projectFindFirst: vi.fn(),
|
||||
tenantUserFindFirst: vi.fn(),
|
||||
fileFindFirst: vi.fn(),
|
||||
fileFindFirstOrThrow: vi.fn(),
|
||||
fileCreate: vi.fn(),
|
||||
linkCreate: vi.fn(),
|
||||
runCreate: vi.fn(),
|
||||
itemCreate: vi.fn(),
|
||||
events: [] as string[],
|
||||
withStorageReservation: vi.fn(),
|
||||
StorageCapacityError: class StorageCapacityError extends Error {
|
||||
constructor(readonly code: string) {
|
||||
super(code);
|
||||
}
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/activity", () => ({ logActivity: mocks.logActivity }));
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({
|
||||
$transaction: mocks.transaction,
|
||||
appSyncRun: { updateMany: mocks.runUpdateMany },
|
||||
}),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({ getRlsExecutionContext: mocks.getRlsExecutionContext }));
|
||||
vi.mock("@hivegrid/db/storage-capacity.server", () => ({
|
||||
TenantStorageCapacityError: mocks.StorageCapacityError,
|
||||
withTenantStorageWriteReservation: mocks.withStorageReservation,
|
||||
}));
|
||||
vi.mock("@hivegrid/foundation", () => ({ auditEvent: mocks.auditEvent }));
|
||||
vi.mock("./resource-client.server.js", () => ({ executeKwpReadOperation: mocks.executeRead }));
|
||||
|
||||
import { __kwpArchiveInternals, syncKwpArchiveFile } from "./archive-file.server.js";
|
||||
|
||||
const now = new Date("2026-07-24T10:00:00.000Z");
|
||||
const descriptor = {
|
||||
externalId: "20:21:22",
|
||||
headerId: 20,
|
||||
revisionId: 22,
|
||||
revision: 1,
|
||||
folderId: 0,
|
||||
displayName: "plan.pdf",
|
||||
documentType: "ZEICHNUNG",
|
||||
providerFileType: "PDF",
|
||||
providerSizeBytes: 3,
|
||||
lastModifiedAt: null,
|
||||
};
|
||||
|
||||
const tx = {
|
||||
appEntityBinding: {
|
||||
findFirst: mocks.projectBindingFindFirst,
|
||||
findUnique: mocks.archiveBindingFindUnique,
|
||||
create: mocks.archiveBindingCreate,
|
||||
},
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
projekt: { findFirst: mocks.projectFindFirst },
|
||||
tenantUser: { findFirst: mocks.tenantUserFindFirst },
|
||||
file: { findFirst: mocks.fileFindFirst, findFirstOrThrow: mocks.fileFindFirstOrThrow, create: mocks.fileCreate },
|
||||
fileEntityLink: { create: mocks.linkCreate },
|
||||
appSyncRun: { create: mocks.runCreate, updateMany: mocks.runUpdateMany },
|
||||
appSyncItem: { create: mocks.itemCreate },
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.events.length = 0;
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1" });
|
||||
mocks.transaction.mockImplementation(async (callback) => {
|
||||
mocks.events.push("tx:start");
|
||||
const result = await callback(tx);
|
||||
mocks.events.push("tx:end");
|
||||
return result;
|
||||
});
|
||||
mocks.withStorageReservation.mockImplementation(async (input) => {
|
||||
await input.runTransaction(async () => {
|
||||
mocks.events.push("reserve");
|
||||
});
|
||||
const stored = await input.upload();
|
||||
return input.runTransaction((transaction: typeof tx) => input.commit(transaction, stored));
|
||||
});
|
||||
mocks.projectBindingFindFirst.mockResolvedValue({
|
||||
dataConnectionId: "connection-1",
|
||||
externalId: "P-100",
|
||||
localId: "project-1",
|
||||
});
|
||||
mocks.connectionFindFirst.mockResolvedValue({ createdByUserId: "user-1" });
|
||||
mocks.projectFindFirst.mockResolvedValue({ id: "project-1", createdByUserId: "user-1" });
|
||||
mocks.tenantUserFindFirst.mockResolvedValue({ userId: "user-1" });
|
||||
mocks.archiveBindingFindUnique.mockResolvedValue(null);
|
||||
mocks.runCreate.mockResolvedValue({ id: "run-1" });
|
||||
mocks.runUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.fileCreate.mockResolvedValue({ id: "file-1", storageKey: "tenants/tenant-1/kwp-archive/hash/plan.pdf" });
|
||||
mocks.linkCreate.mockResolvedValue({ id: "link-1" });
|
||||
mocks.archiveBindingCreate.mockResolvedValue({});
|
||||
mocks.itemCreate.mockResolvedValue({});
|
||||
mocks.executeRead.mockResolvedValue({
|
||||
dateigroesse: 3,
|
||||
exchangeFileUri: "https://exchange.example/file.json",
|
||||
dateiname: "../plan.pdf",
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP archive file importer", () => {
|
||||
it("downloads outside DB, writes a pending file atomically and then enqueues fail-closed scanning", async () => {
|
||||
const fetchImpl = vi
|
||||
.fn<typeof fetch>()
|
||||
.mockResolvedValueOnce(Response.json({ downloadUrl: "https://blob.example/plan.pdf" }))
|
||||
.mockResolvedValueOnce(
|
||||
new Response(new Uint8Array([1, 2, 3]), {
|
||||
status: 200,
|
||||
headers: { "content-type": "application/pdf", "content-length": "3" },
|
||||
})
|
||||
);
|
||||
const putObject = vi.fn().mockImplementation(async () => {
|
||||
mocks.events.push("storage");
|
||||
return { bucket: "files", key: "tenants/tenant-1/kwp-archive/hash/plan.pdf" };
|
||||
});
|
||||
const deleteObject = vi.fn();
|
||||
const enqueueScan = vi.fn().mockImplementation(async () => {
|
||||
mocks.events.push("scan");
|
||||
});
|
||||
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject, deleteObject },
|
||||
storageBucket: "files",
|
||||
enqueueScan,
|
||||
fetchImpl,
|
||||
addressResolver: async () => ["203.0.113.10"],
|
||||
now,
|
||||
})
|
||||
).resolves.toMatchObject({
|
||||
runId: "run-1",
|
||||
fileId: "file-1",
|
||||
projectId: "project-1",
|
||||
state: "created",
|
||||
});
|
||||
|
||||
expect(mocks.events).toEqual(["tx:start", "tx:end", "tx:start", "reserve", "tx:end", "storage", "tx:start", "tx:end", "scan"]);
|
||||
expect(mocks.withStorageReservation).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
reservation: expect.objectContaining({ tenantId: "tenant-1", actorUserId: "user-1", sizeBytes: 3 }),
|
||||
})
|
||||
);
|
||||
expect(mocks.executeRead).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
operationId: "archivExternalExportDatei",
|
||||
operationInput: { query: expect.objectContaining({ revisionId: 22 }) },
|
||||
})
|
||||
);
|
||||
expect(mocks.fileCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
displayName: "plan.pdf",
|
||||
mimeType: "application/pdf",
|
||||
scanStatus: "pending",
|
||||
source: "api",
|
||||
}),
|
||||
});
|
||||
expect(mocks.linkCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
entityType: "project",
|
||||
entityId: "project-1",
|
||||
linkRole: "kwp_archive",
|
||||
}),
|
||||
});
|
||||
expect(enqueueScan).toHaveBeenCalledWith(expect.objectContaining({ fileId: "file-1", tenantId: "tenant-1" }));
|
||||
});
|
||||
|
||||
it("blocks a private exchange target before file or storage mutation", async () => {
|
||||
const fetchImpl = vi.fn<typeof fetch>().mockResolvedValueOnce(Response.json({ url: "https://127.0.0.1/private" }));
|
||||
const putObject = vi.fn();
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject, deleteObject: vi.fn() },
|
||||
storageBucket: "files",
|
||||
enqueueScan: vi.fn(),
|
||||
fetchImpl,
|
||||
addressResolver: async () => ["203.0.113.10"],
|
||||
now,
|
||||
})
|
||||
).rejects.toThrow(/not allowed|blocked/u);
|
||||
expect(putObject).not.toHaveBeenCalled();
|
||||
expect(mocks.fileCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
data: expect.objectContaining({ status: "failed" }),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("fails closed before reservation when the downloaded byte length is not reliable", async () => {
|
||||
const fetchImpl = vi
|
||||
.fn<typeof fetch>()
|
||||
.mockResolvedValueOnce(Response.json({ downloadUrl: "https://blob.example/plan.pdf" }))
|
||||
.mockResolvedValueOnce(
|
||||
new Response(new Uint8Array([1, 2]), {
|
||||
status: 200,
|
||||
headers: { "content-type": "application/pdf", "content-length": "3" },
|
||||
})
|
||||
);
|
||||
const putObject = vi.fn();
|
||||
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject, deleteObject: vi.fn() },
|
||||
storageBucket: "files",
|
||||
enqueueScan: vi.fn(),
|
||||
fetchImpl,
|
||||
addressResolver: async () => ["203.0.113.10"],
|
||||
now,
|
||||
})
|
||||
).rejects.toThrow("did not match its declared size");
|
||||
|
||||
expect(mocks.withStorageReservation).not.toHaveBeenCalled();
|
||||
expect(putObject).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("removes a race-lost upload while preserving and scanning the existing file", async () => {
|
||||
mocks.archiveBindingFindUnique
|
||||
.mockResolvedValueOnce(null)
|
||||
.mockResolvedValueOnce({ localId: "file-existing" })
|
||||
.mockResolvedValueOnce({ localId: "file-existing" });
|
||||
mocks.fileFindFirstOrThrow.mockResolvedValueOnce({
|
||||
id: "file-existing",
|
||||
storageKey: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
});
|
||||
mocks.fileFindFirst.mockResolvedValueOnce({
|
||||
id: "file-existing",
|
||||
storageKey: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
mimeType: "application/pdf",
|
||||
scanStatus: "pending",
|
||||
});
|
||||
mocks.withStorageReservation.mockImplementationOnce(async (input) => {
|
||||
const stored = await input.upload();
|
||||
const outcome = await input.runTransaction((transaction: typeof tx) => input.commit(transaction, stored));
|
||||
if (outcome.replayed) {
|
||||
await input.rollbackUpload(stored);
|
||||
throw new mocks.StorageCapacityError("STORAGE_RESERVATION_INVALID");
|
||||
}
|
||||
return outcome;
|
||||
});
|
||||
const fetchImpl = vi
|
||||
.fn<typeof fetch>()
|
||||
.mockResolvedValueOnce(Response.json({ downloadUrl: "https://blob.example/plan.pdf" }))
|
||||
.mockResolvedValueOnce(
|
||||
new Response(new Uint8Array([1, 2, 3]), {
|
||||
status: 200,
|
||||
headers: { "content-type": "application/pdf", "content-length": "3" },
|
||||
})
|
||||
);
|
||||
const putObject = vi.fn().mockResolvedValue({
|
||||
bucket: "files",
|
||||
key: "tenants/tenant-1/kwp-archive/race/plan.pdf",
|
||||
});
|
||||
const deleteObject = vi.fn().mockResolvedValue(undefined);
|
||||
const enqueueScan = vi.fn();
|
||||
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject, deleteObject },
|
||||
storageBucket: "files",
|
||||
enqueueScan,
|
||||
fetchImpl,
|
||||
addressResolver: async () => ["203.0.113.10"],
|
||||
now,
|
||||
})
|
||||
).resolves.toMatchObject({
|
||||
state: "replayed",
|
||||
fileId: "file-existing",
|
||||
storageKey: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
});
|
||||
|
||||
expect(deleteObject).toHaveBeenCalledWith({ key: "tenants/tenant-1/kwp-archive/race/plan.pdf" });
|
||||
expect(enqueueScan).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
fileId: "file-existing",
|
||||
key: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps the connection active in the failure status for temporary provider outages", async () => {
|
||||
mocks.executeRead.mockRejectedValueOnce(Object.assign(new Error("upstream 500"), { code: "provider_outage" }));
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject: vi.fn(), deleteObject: vi.fn() },
|
||||
storageBucket: "files",
|
||||
enqueueScan: vi.fn(),
|
||||
now,
|
||||
})
|
||||
).rejects.toMatchObject({ code: "provider_outage" });
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
status: "failed",
|
||||
summaryText: "integrations.sync.summary.kwpArchiveTemporaryFailure",
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("repairs scan enqueue on replay without repeating provider or storage calls", async () => {
|
||||
mocks.archiveBindingFindUnique.mockResolvedValueOnce({ localId: "file-existing" });
|
||||
mocks.fileFindFirst.mockResolvedValueOnce({
|
||||
id: "file-existing",
|
||||
storageKey: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
mimeType: "application/pdf",
|
||||
scanStatus: "pending",
|
||||
});
|
||||
const enqueueScan = vi.fn();
|
||||
await expect(
|
||||
syncKwpArchiveFile({
|
||||
bindingId: "binding-1",
|
||||
archiveFile: descriptor,
|
||||
storage: { putObject: vi.fn(), deleteObject: vi.fn() },
|
||||
storageBucket: "files",
|
||||
enqueueScan,
|
||||
now,
|
||||
})
|
||||
).resolves.toMatchObject({ state: "replayed", fileId: "file-existing" });
|
||||
expect(mocks.executeRead).not.toHaveBeenCalled();
|
||||
expect(mocks.fileCreate).not.toHaveBeenCalled();
|
||||
expect(enqueueScan).toHaveBeenCalledWith({
|
||||
bucket: "files",
|
||||
key: "tenants/tenant-1/kwp-archive/existing/plan.pdf",
|
||||
tenantId: "tenant-1",
|
||||
fileId: "file-existing",
|
||||
contentType: "application/pdf",
|
||||
});
|
||||
});
|
||||
|
||||
it("parses only explicit exchange URL keys and sanitizes filenames", () => {
|
||||
expect(__kwpArchiveInternals.parseExchangeDownloadUrl(JSON.stringify({ fileUri: "https://blob.example/a" }))).toBe("https://blob.example/a");
|
||||
expect(() => __kwpArchiveInternals.parseExchangeDownloadUrl(JSON.stringify({ nested: { url: "https://blob.example/a" } }))).toThrow(/did not contain/u);
|
||||
expect(__kwpArchiveInternals.safeFileName("../../plan\u0000.pdf")).toBe("plan.pdf");
|
||||
});
|
||||
});
|
||||
+481
@@ -0,0 +1,481 @@
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
KWP_OAUTH_SCOPE,
|
||||
KWP_OIDC_ISSUER,
|
||||
KWP_REQUIRED_OAUTH_SCOPES,
|
||||
KwpError,
|
||||
discoverKwpMandants,
|
||||
isValidKwpContextCode,
|
||||
isValidKwpReturnedOAuthScopes,
|
||||
probeKwpHealth,
|
||||
refreshKwpAccessToken,
|
||||
resolveKwpRelayBaseUrl,
|
||||
validateKwpOnlineUrl,
|
||||
type KwpCredentials,
|
||||
type KwpOutboundRequestOptions,
|
||||
} from "./client.js";
|
||||
|
||||
const PUBLIC_ADDRESS_RESOLVER = async (): Promise<readonly string[]> => ["93.184.216.34"];
|
||||
const NOW = new Date("2026-07-20T12:00:00.000Z");
|
||||
const DOMAIN_SCOPES = "adresse-extern archiv-extern termin-extern vorgang-extern aktivitaet-extern";
|
||||
const CREDENTIALS: KwpCredentials = {
|
||||
accessToken: "kwp-access-token",
|
||||
refreshToken: "kwp-refresh-token",
|
||||
expiresAt: "2026-07-20T13:00:00.000Z",
|
||||
issuer: KWP_OIDC_ISSUER,
|
||||
clientId: "_extern-geerkens2",
|
||||
clientSecret: "kwp-client-secret",
|
||||
customerCode: "geerkens2",
|
||||
scopes: [...KWP_REQUIRED_OAUTH_SCOPES],
|
||||
mandantBinding: { kind: "selected", code: "mandant1", label: "Mandant 1" },
|
||||
};
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
describe("KWP OAuth client", () => {
|
||||
it("validates the KWP HTTPS host allowlist", () => {
|
||||
expect(validateKwpOnlineUrl("https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa")).toBe("https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa");
|
||||
expect(() => validateKwpOnlineUrl("http://geerkens2.app04.kwp-online.de")).toThrowError(KwpError);
|
||||
expect(() => validateKwpOnlineUrl("https://kwp-online.de.evil.test")).toThrowError(KwpError);
|
||||
expect(() => validateKwpOnlineUrl("https://user@kwp-online.de")).toThrowError(KwpError);
|
||||
expect(() => validateKwpOnlineUrl("https://kwp-online.de:8443")).toThrowError(KwpError);
|
||||
});
|
||||
|
||||
it("uses one canonical 128-character context-code contract", () => {
|
||||
expect(isValidKwpContextCode("geerkens2")).toBe(true);
|
||||
expect(isValidKwpContextCode(`a${"_".repeat(127)}`)).toBe(true);
|
||||
for (const value of ["", " geerkens2", "geerkens.2", "geerkens/2", `a${"_".repeat(128)}`]) {
|
||||
expect(isValidKwpContextCode(value)).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it.each([
|
||||
["domain scopes only", DOMAIN_SCOPES],
|
||||
["openid only as technical scope", `openid ${DOMAIN_SCOPES}`],
|
||||
["offline_access only as technical scope", `${DOMAIN_SCOPES} offline_access`],
|
||||
["both technical scopes", KWP_OAUTH_SCOPE],
|
||||
["leading and trailing whitespace", ` ${DOMAIN_SCOPES}\topenid `],
|
||||
["repeated mixed whitespace", `openid\n${DOMAIN_SCOPES.replaceAll(" ", "\t ")}\noffline_access`],
|
||||
])("accepts a returned scope echo with %s", (_name, scopes) => {
|
||||
expect(isValidKwpReturnedOAuthScopes(scopes)).toBe(true);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["an empty value", ""],
|
||||
["a whitespace-only value", " \t\n "],
|
||||
["a missing domain scope", "adresse-extern archiv-extern termin-extern vorgang-extern"],
|
||||
["an unknown scope", `${DOMAIN_SCOPES} email`],
|
||||
["an unknown identity scope", `${DOMAIN_SCOPES} profile`],
|
||||
["an unknown domain-shaped scope", `${DOMAIN_SCOPES} projekt-extern`],
|
||||
["a duplicate scope", `${DOMAIN_SCOPES} adresse-extern`],
|
||||
["wrong capitalization", "Adresse-extern archiv-extern termin-extern vorgang-extern aktivitaet-extern"],
|
||||
])("rejects a returned scope echo with %s", (_name, scopes) => {
|
||||
expect(isValidKwpReturnedOAuthScopes(scopes)).toBe(false);
|
||||
});
|
||||
|
||||
it.each(DOMAIN_SCOPES.split(" "))("rejects a returned scope echo missing %s", (missingScope) => {
|
||||
const scopes = DOMAIN_SCOPES.split(" ")
|
||||
.filter((scope) => scope !== missingScope)
|
||||
.join(" ");
|
||||
expect(isValidKwpReturnedOAuthScopes(scopes)).toBe(false);
|
||||
});
|
||||
|
||||
it("resolves the relay from the official load balancer without hard-coding an app host", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(new Response("https://geerkens2.app04.kwp-online.de"));
|
||||
|
||||
await expect(resolveKwpRelayBaseUrl("geerkens2", outboundOptions(fetchMock))).resolves.toBe("https://geerkens2.app04.kwp-online.de");
|
||||
|
||||
const endpoint = new URL(String(fetchMock.mock.calls[0]?.[0]));
|
||||
expect(`${endpoint.origin}${endpoint.pathname}`).toBe("https://loadbalancer.kwp-online.de/Relay/GetAppUrl");
|
||||
expect(endpoint.searchParams.get("linkId")).toBe("geerkens2");
|
||||
});
|
||||
|
||||
it("rejects a relay response outside kwp-online.de before sending a bearer token", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValue(new Response("https://kwp-online.de.evil.test"));
|
||||
|
||||
await expect(resolveKwpRelayBaseUrl("geerkens2", outboundOptions(fetchMock))).rejects.toMatchObject({
|
||||
code: "relay_host_invalid",
|
||||
});
|
||||
expect(fetchMock).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("runs read-only health through the resolved relay with the selected mandant", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(1));
|
||||
|
||||
await expect(probeKwpHealth(CREDENTIALS, outboundOptions(fetchMock))).resolves.toBe("1");
|
||||
|
||||
const [healthUrl, healthInit] = fetchMock.mock.calls[1] as [string, RequestInit];
|
||||
const endpoint = new URL(healthUrl);
|
||||
expect(endpoint.pathname).toBe("/relay/geerkens2/pwa/api/Core/GetApiVersion");
|
||||
expect(endpoint.searchParams.get("mandant")).toBe("mandant1");
|
||||
expect(new Headers(healthInit.headers).get("authorization")).toBe(`Bearer ${CREDENTIALS.accessToken}`);
|
||||
expect(healthInit.method).toBe("GET");
|
||||
});
|
||||
|
||||
it("omits the mandant query only for an explicitly confirmed none binding", async () => {
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(1));
|
||||
|
||||
await expect(probeKwpHealth({ ...CREDENTIALS, mandantBinding: { kind: "none" } }, outboundOptions(fetchMock))).resolves.toBe("1");
|
||||
|
||||
const endpoint = new URL(String(fetchMock.mock.calls[1]?.[0]));
|
||||
expect(endpoint.searchParams.has("mandant")).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects an unconfirmed legacy binding before making a health request", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
const { mandantBinding: _mandantBinding, ...unconfirmedCredentials } = CREDENTIALS;
|
||||
|
||||
await expect(probeKwpHealth(unconfirmedCredentials, outboundOptions(fetchMock))).rejects.toMatchObject({ code: "mandant_unconfirmed" });
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each([[{ kind: "selected", code: "" }], [{ kind: "selected", code: "mandant1", label: "" }], [{ kind: "none", code: "mandant1" }], [{ kind: "unknown" }]])(
|
||||
"rejects an invalid explicit mandant binding before making a health request",
|
||||
async (mandantBinding) => {
|
||||
const fetchMock = vi.fn();
|
||||
|
||||
await expect(
|
||||
probeKwpHealth({ ...CREDENTIALS, mandantBinding: mandantBinding as unknown as KwpCredentials["mandantBinding"] }, outboundOptions(fetchMock))
|
||||
).rejects.toMatchObject({ code: "invalid_credentials" });
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
}
|
||||
);
|
||||
|
||||
it("discovers, normalizes, sorts, and deduplicates mandants without sending a mandant query", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse([
|
||||
{ id: 12, kuerzel: "beta", bezeichnung: " duplicate " },
|
||||
{ id: 4, kuerzel: "alpha", bezeichnung: null },
|
||||
{ id: 3, kuerzel: "beta", bezeichnung: " Beta GmbH " },
|
||||
{ id: 9, kuerzel: "gamma", bezeichnung: " " },
|
||||
])
|
||||
);
|
||||
|
||||
await expect(discoverKwpMandants(CREDENTIALS, outboundOptions(fetchMock))).resolves.toEqual([
|
||||
{ id: 4, code: "alpha" },
|
||||
{ id: 3, code: "beta", label: "Beta GmbH" },
|
||||
{ id: 9, code: "gamma" },
|
||||
]);
|
||||
|
||||
const [discoveryUrl, discoveryInit] = fetchMock.mock.calls[1] as [string, RequestInit];
|
||||
const endpoint = new URL(discoveryUrl);
|
||||
expect(endpoint.pathname).toBe("/relay/geerkens2/pwa/api/Mandant/Load");
|
||||
expect(endpoint.searchParams.has("mandant")).toBe(false);
|
||||
expect(discoveryInit.method).toBe("GET");
|
||||
expect(new Headers(discoveryInit.headers).get("accept")).toBe("application/json");
|
||||
expect(new Headers(discoveryInit.headers).get("authorization")).toBe(`Bearer ${CREDENTIALS.accessToken}`);
|
||||
});
|
||||
|
||||
it("allows mandant discovery while the legacy binding is still unconfirmed", async () => {
|
||||
const { mandantBinding: _mandantBinding, ...unconfirmedCredentials } = CREDENTIALS;
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse([]));
|
||||
|
||||
await expect(discoverKwpMandants(unconfirmedCredentials, outboundOptions(fetchMock))).resolves.toEqual([]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["a non-array response", { id: 1, kuerzel: "alpha", bezeichnung: "Alpha" }],
|
||||
["a non-object entry", [null]],
|
||||
["a missing DTO property", [{ id: 1, kuerzel: "alpha" }]],
|
||||
["an extra DTO property", [{ id: 1, kuerzel: "alpha", bezeichnung: "Alpha", tenant: "secret" }]],
|
||||
["a fractional id", [{ id: 1.5, kuerzel: "alpha", bezeichnung: "Alpha" }]],
|
||||
["an id outside int32", [{ id: 2_147_483_648, kuerzel: "alpha", bezeichnung: "Alpha" }]],
|
||||
["a null code", [{ id: 1, kuerzel: null, bezeichnung: "Alpha" }]],
|
||||
["an invalid code", [{ id: 1, kuerzel: "alpha/beta", bezeichnung: "Alpha" }]],
|
||||
["a non-string label", [{ id: 1, kuerzel: "alpha", bezeichnung: 42 }]],
|
||||
["a control character in the label", [{ id: 1, kuerzel: "alpha", bezeichnung: "Alpha\u0000Beta" }]],
|
||||
["an oversized label", [{ id: 1, kuerzel: "alpha", bezeichnung: "a".repeat(257) }]],
|
||||
])("rejects %s as an invalid discovery response", async (_name, body) => {
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(body));
|
||||
|
||||
await expect(discoverKwpMandants(CREDENTIALS, outboundOptions(fetchMock))).rejects.toMatchObject({
|
||||
code: "invalid_response",
|
||||
httpStatus: 200,
|
||||
});
|
||||
});
|
||||
|
||||
it("bounds mandant discovery by entry count and response bytes", async () => {
|
||||
const tooManyEntries = Array.from({ length: 101 }, (_, index) => ({
|
||||
id: index,
|
||||
kuerzel: `m${index}`,
|
||||
bezeichnung: null,
|
||||
}));
|
||||
const entryFetch = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(tooManyEntries));
|
||||
await expect(discoverKwpMandants(CREDENTIALS, outboundOptions(entryFetch))).rejects.toMatchObject({ code: "invalid_response" });
|
||||
|
||||
const responseFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse([{ id: 1, kuerzel: "alpha", bezeichnung: "a".repeat(17 * 1024) }]));
|
||||
await expect(discoverKwpMandants(CREDENTIALS, outboundOptions(responseFetch))).rejects.toMatchObject({ code: "invalid_response" });
|
||||
});
|
||||
|
||||
it.each([
|
||||
[401, "auth_token_invalid"],
|
||||
[403, "mandant_discovery_unavailable"],
|
||||
[404, "mandant_discovery_unavailable"],
|
||||
[429, "rate_limit_exceeded"],
|
||||
[503, "provider_outage"],
|
||||
])("classifies mandant discovery HTTP %i as %s", async (status, code) => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse({ diagnostic: CREDENTIALS.accessToken }, status));
|
||||
|
||||
const error = await discoverKwpMandants(CREDENTIALS, outboundOptions(fetchMock)).catch((caught: unknown) => caught);
|
||||
expect(error).toMatchObject({ code, httpStatus: status });
|
||||
expect(JSON.stringify(error)).not.toContain(CREDENTIALS.accessToken);
|
||||
});
|
||||
|
||||
it("rotates one-time refresh tokens centrally and rejects a missing replacement", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(jsonResponse({ access_token: "rotated-access", refresh_token: "rotated-refresh", expires_in: 300 }))
|
||||
.mockResolvedValueOnce(jsonResponse({ access_token: "next-access", expires_in: 300 }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
const rotated = await refreshKwpAccessToken(CREDENTIALS, { now: () => NOW });
|
||||
expect(rotated).toMatchObject({
|
||||
accessToken: "rotated-access",
|
||||
refreshToken: "rotated-refresh",
|
||||
expiresAt: "2026-07-20T12:05:00.000Z",
|
||||
mandantBinding: CREDENTIALS.mandantBinding,
|
||||
});
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS, { now: () => NOW })).rejects.toMatchObject({
|
||||
code: "invalid_response",
|
||||
diagnosticCode: "missing_refresh_token",
|
||||
});
|
||||
|
||||
for (const [tokenUrl, tokenInit] of fetchMock.mock.calls as Array<[string, RequestInit]>) {
|
||||
expect(tokenUrl).toBe("https://id.kwp-online.de/realms/kwp-federated/protocol/openid-connect/token");
|
||||
const form = new URLSearchParams(String(tokenInit.body));
|
||||
expect(form.get("grant_type")).toBe("refresh_token");
|
||||
expect(form.get("scope")).toBe(KWP_OAUTH_SCOPE);
|
||||
expect(form.get("scope")?.split(" ")).not.toContain("email");
|
||||
}
|
||||
});
|
||||
|
||||
it.each([
|
||||
["unconfirmed", undefined],
|
||||
["confirmed without a bnWin mandant", { kind: "none" }],
|
||||
["selected", { kind: "selected", code: "mandant1", label: "Mandant 1" }],
|
||||
] as const)("preserves the %s mandant binding during refresh", async (_name, mandantBinding) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse({ access_token: "next-access", refresh_token: "next-refresh", expires_in: 300 })));
|
||||
|
||||
const refreshed = await refreshKwpAccessToken({ ...CREDENTIALS, mandantBinding }, { now: () => NOW });
|
||||
|
||||
expect(refreshed.mandantBinding).toEqual(mandantBinding);
|
||||
});
|
||||
|
||||
it("chains the persisted one-time refresh token from r1 to r2 to r3", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(jsonResponse({ access_token: "access-2", refresh_token: "refresh-2", expires_in: 300 }))
|
||||
.mockResolvedValueOnce(jsonResponse({ access_token: "access-3", refresh_token: "refresh-3", expires_in: 300 }));
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
const second = await refreshKwpAccessToken({ ...CREDENTIALS, refreshToken: "refresh-1" }, { now: () => NOW });
|
||||
const third = await refreshKwpAccessToken(second, { now: () => new Date("2026-07-20T12:05:00.000Z") });
|
||||
|
||||
expect(second).toMatchObject({ accessToken: "access-2", refreshToken: "refresh-2" });
|
||||
expect(third).toMatchObject({ accessToken: "access-3", refreshToken: "refresh-3", expiresAt: "2026-07-20T12:10:00.000Z" });
|
||||
expect(fetchMock.mock.calls.map(([, init]) => new URLSearchParams(String((init as RequestInit).body)).get("refresh_token"))).toEqual([
|
||||
"refresh-1",
|
||||
"refresh-2",
|
||||
]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
[400, "auth_token_invalid"],
|
||||
[401, "auth_token_invalid"],
|
||||
[403, "auth_scope_missing"],
|
||||
[408, "refresh_outcome_unknown"],
|
||||
[429, "rate_limit_exceeded"],
|
||||
[503, "refresh_outcome_unknown"],
|
||||
])("classifies token endpoint HTTP %i as %s", async (status, code) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse({ error: "redacted" }, status)));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({ code, httpStatus: status });
|
||||
});
|
||||
|
||||
it.each([
|
||||
[400, "auth_token_invalid"],
|
||||
[503, "refresh_outcome_unknown"],
|
||||
])("classifies a non-object token error body at HTTP %i as %s", async (status, code) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse(null, status)));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({ code, httpStatus: status });
|
||||
});
|
||||
|
||||
it("rejects a successful non-object token body as an invalid response", async () => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse(null)));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({
|
||||
code: "invalid_response",
|
||||
httpStatus: 200,
|
||||
diagnosticCode: "token_response_not_object",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects a successful non-JSON token body with a redacted diagnostic", async () => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("{not-json", { status: 200 })));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({
|
||||
code: "invalid_response",
|
||||
httpStatus: 200,
|
||||
diagnosticCode: "token_response_not_json",
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
["temporarily_unavailable", "provider_outage"],
|
||||
["server_error", "provider_outage"],
|
||||
["invalid_scope", "auth_scope_missing"],
|
||||
["invalid_grant", "auth_token_invalid"],
|
||||
["invalid_client", "invalid_credentials"],
|
||||
])("classifies allowlisted OAuth error %s as %s without retaining the provider body", async (providerError, code) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse({ error: providerError, error_description: CREDENTIALS.refreshToken }, 400)));
|
||||
|
||||
const error = await refreshKwpAccessToken(CREDENTIALS).catch((caught: unknown) => caught);
|
||||
expect(error).toMatchObject({ code, httpStatus: 400 });
|
||||
expect(JSON.stringify(error)).not.toContain(CREDENTIALS.refreshToken);
|
||||
});
|
||||
|
||||
it.each(["temporarily_unavailable", "server_error"])(
|
||||
"keeps an explicit OAuth %s response replay-safe even at HTTP 503",
|
||||
async (providerError) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse({ error: providerError }, 503)));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({ code: "provider_outage", httpStatus: 503 });
|
||||
},
|
||||
);
|
||||
|
||||
it("classifies a token POST without a response as an ambiguous refresh outcome", async () => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new TypeError("network unavailable")));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS)).rejects.toMatchObject({ code: "refresh_outcome_unknown" });
|
||||
});
|
||||
|
||||
it("rejects non-canonical stored scopes before requesting a refresh token", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
|
||||
await expect(refreshKwpAccessToken({ ...CREDENTIALS, scopes: DOMAIN_SCOPES.split(" ") }, { now: () => NOW })).rejects.toMatchObject({
|
||||
code: "invalid_credentials",
|
||||
});
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fails closed with redacted diagnostics on unsafe refresh responses", async () => {
|
||||
const responses = [
|
||||
[{ refresh_token: "next-no-access", expires_in: 300 }, "missing_access_token"],
|
||||
[{ access_token: "access", expires_in: 300 }, "missing_refresh_token"],
|
||||
[{ access_token: "access", refresh_token: CREDENTIALS.refreshToken, expires_in: 300 }, "refresh_token_not_rotated"],
|
||||
[{ access_token: "access", refresh_token: ` ${CREDENTIALS.refreshToken} `, expires_in: 300 }, "refresh_token_not_rotated"],
|
||||
[{ access_token: "access", refresh_token: "next-1", expires_in: 300, scope: `${KWP_OAUTH_SCOPE} email` }, "scope_mismatch"],
|
||||
[{ access_token: "access", refresh_token: "next-duplicate", expires_in: 300, scope: `${DOMAIN_SCOPES} adresse-extern` }, "scope_mismatch"],
|
||||
[{ access_token: "access", refresh_token: "next-empty", expires_in: 300, scope: " \t\n " }, "scope_mismatch"],
|
||||
[
|
||||
{
|
||||
access_token: "access",
|
||||
refresh_token: "next-case",
|
||||
expires_in: 300,
|
||||
scope: `Adresse-extern ${DOMAIN_SCOPES.split(" ").slice(1).join(" ")}`,
|
||||
},
|
||||
"scope_mismatch",
|
||||
],
|
||||
[
|
||||
{
|
||||
access_token: "access",
|
||||
refresh_token: "next-missing",
|
||||
expires_in: 300,
|
||||
scope: "adresse-extern archiv-extern termin-extern vorgang-extern",
|
||||
},
|
||||
"scope_mismatch",
|
||||
],
|
||||
[{ access_token: "access", refresh_token: "next-zero", expires_in: 0 }, "invalid_expiry"],
|
||||
[{ access_token: "access", refresh_token: "next-2", expires_in: 301 }, "invalid_expiry"],
|
||||
[{ access_token: "access", refresh_token: "next-3", expires_in: 300.5 }, "invalid_expiry"],
|
||||
];
|
||||
|
||||
for (const [response, diagnosticCode] of responses) {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse(response)));
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS, { now: () => NOW })).rejects.toMatchObject({
|
||||
code: "invalid_response",
|
||||
diagnosticCode,
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it.each([1, 299, 300])("accepts a positive contract-bounded expires_in of %i seconds", async (expiresIn) => {
|
||||
vi.stubGlobal(
|
||||
"fetch",
|
||||
vi.fn().mockResolvedValue(
|
||||
jsonResponse({ access_token: "access", refresh_token: "next-valid", expires_in: expiresIn }),
|
||||
),
|
||||
);
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS, { now: () => NOW })).resolves.toMatchObject({
|
||||
expiresAt: new Date(NOW.getTime() + expiresIn * 1_000).toISOString(),
|
||||
refreshToken: "next-valid",
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
["domain scopes only", DOMAIN_SCOPES],
|
||||
["openid only as technical scope", `openid ${DOMAIN_SCOPES}`],
|
||||
["offline_access only as technical scope", `${DOMAIN_SCOPES} offline_access`],
|
||||
["both technical scopes", [...KWP_REQUIRED_OAUTH_SCOPES].reverse().join(" ")],
|
||||
["mixed repeated whitespace", `\topenid ${DOMAIN_SCOPES.replaceAll(" ", "\n ")}\toffline_access\n`],
|
||||
])("accepts refresh scope echo with %s and keeps canonical stored scopes", async (_name, scope) => {
|
||||
vi.stubGlobal("fetch", vi.fn().mockResolvedValue(jsonResponse({ access_token: "access", refresh_token: "next-valid", expires_in: 300, scope })));
|
||||
|
||||
await expect(refreshKwpAccessToken(CREDENTIALS, { now: () => NOW })).resolves.toMatchObject({
|
||||
refreshToken: "next-valid",
|
||||
scopes: [...KWP_REQUIRED_OAUTH_SCOPES],
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts only a finite int32 API-major response", async () => {
|
||||
for (const body of ["", '"1"', "1.5", "2147483648", '{"version":1}', "true", "null"]) {
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(new Response(body));
|
||||
await expect(probeKwpHealth(CREDENTIALS, outboundOptions(fetchMock))).rejects.toMatchObject({ code: "invalid_response", httpStatus: 200 });
|
||||
}
|
||||
|
||||
const plainTextFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(new Response("2147483647"));
|
||||
await expect(probeKwpHealth(CREDENTIALS, outboundOptions(plainTextFetch))).resolves.toBe("2147483647");
|
||||
});
|
||||
|
||||
it("maps provider failures without exposing tokens or provider diagnostics", async () => {
|
||||
const healthFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse({ diagnostic: CREDENTIALS.accessToken }, 401));
|
||||
const healthError = await probeKwpHealth(CREDENTIALS, outboundOptions(healthFetch)).catch((error: unknown) => error);
|
||||
expect(healthError).toMatchObject({ code: "auth_token_invalid", httpStatus: 401 });
|
||||
expect(JSON.stringify(healthError)).not.toContain(CREDENTIALS.accessToken);
|
||||
|
||||
const tokenFetch = vi.fn().mockResolvedValue(jsonResponse({ diagnostic: CREDENTIALS.refreshToken }, 400));
|
||||
vi.stubGlobal("fetch", tokenFetch);
|
||||
const refreshError = await refreshKwpAccessToken(CREDENTIALS).catch((error: unknown) => error);
|
||||
expect(refreshError).toMatchObject({ code: "auth_token_invalid", httpStatus: 400 });
|
||||
expect(JSON.stringify(refreshError)).not.toContain(CREDENTIALS.refreshToken);
|
||||
});
|
||||
});
|
||||
|
||||
function outboundOptions(fetchImpl: typeof fetch): KwpOutboundRequestOptions {
|
||||
return { fetchImpl, addressResolver: PUBLIC_ADDRESS_RESOLVER };
|
||||
}
|
||||
|
||||
function jsonResponse(body: unknown, status = 200): Response {
|
||||
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
|
||||
}
|
||||
@@ -0,0 +1,605 @@
|
||||
import {
|
||||
fetchOutboundHttpWithRedirects,
|
||||
OutboundHttpUrlValidationError,
|
||||
readLimitedResponseText,
|
||||
type OutboundHttpFetchOptions,
|
||||
} from "@hivegrid/foundation/outbound-http";
|
||||
|
||||
import { fetchProvider, readProviderJson } from "../provider-http.js";
|
||||
|
||||
export const KWP_APP_ID = "kwp";
|
||||
export const KWP_OIDC_ISSUER = "https://id.kwp-online.de/realms/kwp-federated";
|
||||
export const KWP_REQUIRED_OAUTH_SCOPES = Object.freeze([
|
||||
"openid",
|
||||
"adresse-extern",
|
||||
"archiv-extern",
|
||||
"termin-extern",
|
||||
"vorgang-extern",
|
||||
"aktivitaet-extern",
|
||||
"offline_access",
|
||||
] as const);
|
||||
export const KWP_OAUTH_SCOPE = KWP_REQUIRED_OAUTH_SCOPES.join(" ");
|
||||
|
||||
const KWP_REQUIRED_DOMAIN_OAUTH_SCOPES = KWP_REQUIRED_OAUTH_SCOPES.filter((scope) => scope.endsWith("-extern"));
|
||||
const KWP_RETURNED_OAUTH_SCOPE_SET = new Set<string>(KWP_REQUIRED_OAUTH_SCOPES);
|
||||
|
||||
const KWP_TOKEN_URL = `${KWP_OIDC_ISSUER}/protocol/openid-connect/token`;
|
||||
const KWP_LOAD_BALANCER_URL = "https://loadbalancer.kwp-online.de/Relay/GetAppUrl";
|
||||
const KWP_RESPONSE_LIMIT_BYTES = 16 * 1024;
|
||||
const KWP_ACCESS_TOKEN_TTL_SECONDS = 5 * 60;
|
||||
const KWP_CONTEXT_CODE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
|
||||
const KWP_MANDANT_RESPONSE_MAX_ENTRIES = 100;
|
||||
const KWP_MANDANT_LABEL_MAX_LENGTH = 256;
|
||||
const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
|
||||
|
||||
export type KwpMandantBinding = { readonly kind: "none" } | { readonly kind: "selected"; readonly code: string; readonly label?: string };
|
||||
|
||||
export interface KwpMandant {
|
||||
readonly id: number;
|
||||
readonly code: string;
|
||||
readonly label?: string;
|
||||
}
|
||||
|
||||
export interface KwpCredentials {
|
||||
readonly accessToken: string;
|
||||
readonly refreshToken: string;
|
||||
readonly expiresAt: string;
|
||||
readonly issuer: string;
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
readonly customerCode: string;
|
||||
readonly scopes: readonly string[];
|
||||
/** Missing only while a legacy/pending connection still awaits confirmation. */
|
||||
readonly mandantBinding?: KwpMandantBinding;
|
||||
}
|
||||
|
||||
interface KwpOAuthClientConfig {
|
||||
readonly issuer: string;
|
||||
readonly clientId: string;
|
||||
readonly clientSecret: string;
|
||||
readonly customerCode: string;
|
||||
readonly mandantBinding?: KwpMandantBinding;
|
||||
}
|
||||
|
||||
export type KwpOutboundRequestOptions = Pick<OutboundHttpFetchOptions, "fetchImpl" | "addressResolver" | "timeoutMs" | "redirectLimit" | "pinResolvedAddress">;
|
||||
|
||||
export interface KwpTokenRequestOptions {
|
||||
readonly now?: () => Date;
|
||||
}
|
||||
|
||||
export type KwpErrorCode =
|
||||
| "auth_scope_missing"
|
||||
| "auth_token_invalid"
|
||||
| "capability_paused"
|
||||
| "contract_drift"
|
||||
| "invalid_credentials"
|
||||
| "invalid_response"
|
||||
| "mandant_discovery_unavailable"
|
||||
| "mandant_unconfirmed"
|
||||
| "provider_outage"
|
||||
| "resource_not_found"
|
||||
| "rate_limit_exceeded"
|
||||
| "refresh_outcome_unknown"
|
||||
| "relay_host_invalid"
|
||||
| "relay_not_found"
|
||||
| "unknown";
|
||||
|
||||
export type KwpRefreshDiagnosticCode =
|
||||
| "invalid_clock"
|
||||
| "invalid_expiry"
|
||||
| "missing_access_token"
|
||||
| "missing_refresh_token"
|
||||
| "refresh_token_not_rotated"
|
||||
| "scope_mismatch"
|
||||
| "token_response_not_json"
|
||||
| "token_response_not_object";
|
||||
|
||||
export class KwpError extends Error {
|
||||
readonly code: KwpErrorCode;
|
||||
readonly httpStatus?: number;
|
||||
readonly diagnosticCode?: KwpRefreshDiagnosticCode;
|
||||
|
||||
constructor(code: KwpErrorCode, httpStatus?: number, diagnosticCode?: KwpRefreshDiagnosticCode) {
|
||||
// Provider bodies may contain tokens or customer diagnostics. Keep the
|
||||
// exception deliberately limited to stable, Klartext-mappable codes.
|
||||
super(code);
|
||||
this.name = "KwpError";
|
||||
this.code = code;
|
||||
this.httpStatus = httpStatus;
|
||||
this.diagnosticCode = diagnosticCode;
|
||||
}
|
||||
}
|
||||
|
||||
/** Validate a credential snapshot before any business-resource request. */
|
||||
export function assertKwpResourceCredentials(credentials: KwpCredentials): void {
|
||||
validateCredentials(credentials, "resource");
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate KWP's optional token-response scope echo. KWP may omit either
|
||||
* technical scope (`openid` / `offline_access`) from that echo, while all five
|
||||
* licensed `*-extern` scopes remain mandatory. Callers keep the canonical
|
||||
* seven-scope request policy instead of persisting this provider representation.
|
||||
*/
|
||||
export function isValidKwpReturnedOAuthScopes(value: unknown): value is string {
|
||||
if (typeof value !== "string") return false;
|
||||
const normalized = value.trim();
|
||||
if (normalized.length === 0) return false;
|
||||
const scopes = normalized.split(/\s+/u);
|
||||
const scopeSet = new Set(scopes);
|
||||
return (
|
||||
scopes.every((scope) => KWP_RETURNED_OAUTH_SCOPE_SET.has(scope)) &&
|
||||
scopeSet.size === scopes.length &&
|
||||
KWP_REQUIRED_DOMAIN_OAUTH_SCOPES.every((scope) => scopeSet.has(scope))
|
||||
);
|
||||
}
|
||||
|
||||
interface KwpTokenResponse {
|
||||
readonly access_token?: unknown;
|
||||
readonly refresh_token?: unknown;
|
||||
readonly expires_in?: unknown;
|
||||
readonly scope?: unknown;
|
||||
readonly error?: unknown;
|
||||
}
|
||||
|
||||
/** Refresh through central Keycloak and require KWP's documented one-time token rotation. */
|
||||
export async function refreshKwpAccessToken(credentials: KwpCredentials, options: KwpTokenRequestOptions = {}): Promise<KwpCredentials> {
|
||||
const config = validateCredentials(credentials, "refresh");
|
||||
const token = await requestKwpToken(
|
||||
new URLSearchParams({
|
||||
grant_type: "refresh_token",
|
||||
refresh_token: credentials.refreshToken,
|
||||
client_id: config.clientId,
|
||||
client_secret: config.clientSecret,
|
||||
scope: KWP_OAUTH_SCOPE,
|
||||
})
|
||||
);
|
||||
const rotatedRefreshToken = readTokenValue(token.refresh_token);
|
||||
if (!rotatedRefreshToken) {
|
||||
throw new KwpError("invalid_response", undefined, "missing_refresh_token");
|
||||
}
|
||||
if (rotatedRefreshToken === credentials.refreshToken.trim()) {
|
||||
// KWP refresh tokens are single-use. Keeping the consumed token would make
|
||||
// the next refresh fail while falsely persisting a healthy credential set.
|
||||
throw new KwpError("invalid_response", undefined, "refresh_token_not_rotated");
|
||||
}
|
||||
if (token.scope !== undefined && !isValidKwpReturnedOAuthScopes(token.scope)) {
|
||||
throw new KwpError("invalid_response", undefined, "scope_mismatch");
|
||||
}
|
||||
return toCredentials(config, token, rotatedRefreshToken, options.now?.() ?? new Date());
|
||||
}
|
||||
|
||||
/** Resolve the current tenant relay. The provider returns a plain-text HTTPS base URL. */
|
||||
export async function resolveKwpRelayBaseUrl(customerCode: string, options: KwpOutboundRequestOptions = {}): Promise<string> {
|
||||
const normalizedCustomerCode = normalizeCustomerCode(customerCode);
|
||||
const endpoint = new URL(KWP_LOAD_BALANCER_URL);
|
||||
endpoint.searchParams.set("linkId", normalizedCustomerCode);
|
||||
const response = await fetchKwpOutbound(endpoint.toString(), { method: "GET", headers: { accept: "text/plain" } }, options);
|
||||
if (!response.ok) {
|
||||
throw mapRelayError(response.status);
|
||||
}
|
||||
|
||||
const relayBody = await readKwpResponseBody(response);
|
||||
return normalizeRelayBaseUrl(relayBody);
|
||||
}
|
||||
|
||||
/**
|
||||
* Discover the bnWin mandants visible to the authenticated user. This setup-only
|
||||
* request deliberately omits the `mandant` query parameter because it is the
|
||||
* operation that establishes the binding in the first place.
|
||||
*/
|
||||
export async function discoverKwpMandants(credentials: KwpCredentials, options: KwpOutboundRequestOptions = {}): Promise<KwpMandant[]> {
|
||||
const config = validateCredentials(credentials, "discovery");
|
||||
const relayBaseUrl = await resolveKwpRelayBaseUrl(config.customerCode, options);
|
||||
const endpoint = new URL(`/relay/${encodeURIComponent(config.customerCode)}/pwa/api/Mandant/Load`, `${relayBaseUrl}/`);
|
||||
const response = await fetchKwpOutbound(
|
||||
endpoint.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
headers: { accept: "application/json", authorization: `Bearer ${credentials.accessToken}` },
|
||||
},
|
||||
options
|
||||
);
|
||||
if (!response.ok) {
|
||||
throw mapMandantDiscoveryError(response.status);
|
||||
}
|
||||
return parseKwpMandants(await readKwpResponseBody(response), response.status);
|
||||
}
|
||||
|
||||
/** Read-only Apps Engine health probe against the dynamically resolved KWP relay. */
|
||||
export async function probeKwpHealth(credentials: KwpCredentials, options: KwpOutboundRequestOptions = {}): Promise<string> {
|
||||
const config = validateCredentials(credentials, "health");
|
||||
const relayBaseUrl = await resolveKwpRelayBaseUrl(config.customerCode, options);
|
||||
const endpoint = new URL(`/relay/${encodeURIComponent(config.customerCode)}/pwa/api/Core/GetApiVersion`, `${relayBaseUrl}/`);
|
||||
if (config.mandantBinding?.kind === "selected") {
|
||||
endpoint.searchParams.set("mandant", config.mandantBinding.code);
|
||||
}
|
||||
|
||||
const response = await fetchKwpOutbound(
|
||||
endpoint.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
headers: { accept: "application/json", authorization: `Bearer ${credentials.accessToken}` },
|
||||
},
|
||||
options
|
||||
);
|
||||
if (!response.ok) {
|
||||
throw mapHealthError(response.status);
|
||||
}
|
||||
const body = await readKwpResponseBody(response);
|
||||
return parseKwpApiMajorVersion(body, response.status);
|
||||
}
|
||||
|
||||
/** Canonical KWP tenant/mandant code contract shared by OAuth, callback and relay calls. */
|
||||
export function isValidKwpContextCode(value: unknown): value is string {
|
||||
return typeof value === "string" && KWP_CONTEXT_CODE_PATTERN.test(value);
|
||||
}
|
||||
|
||||
/** Feature-specific policy applied before DNS resolution and on every redirect. */
|
||||
export function validateKwpOnlineUrl(endpoint: string): string {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(endpoint);
|
||||
} catch {
|
||||
throw new KwpError("relay_host_invalid");
|
||||
}
|
||||
|
||||
const hostname = url.hostname.toLowerCase();
|
||||
const allowedHost = hostname === "kwp-online.de" || hostname.endsWith(".kwp-online.de");
|
||||
if (
|
||||
url.protocol !== "https:" ||
|
||||
!allowedHost ||
|
||||
hostname.endsWith(".") ||
|
||||
Boolean(url.username || url.password) ||
|
||||
(url.port !== "" && url.port !== "443") ||
|
||||
Boolean(url.hash)
|
||||
) {
|
||||
throw new KwpError("relay_host_invalid");
|
||||
}
|
||||
return url.toString();
|
||||
}
|
||||
|
||||
function validateOAuthConfig(config: KwpOAuthClientConfig): KwpOAuthClientConfig {
|
||||
assertCentralIssuer(config.issuer);
|
||||
const mandantBinding = normalizeMandantBinding(config.mandantBinding);
|
||||
return {
|
||||
issuer: KWP_OIDC_ISSUER,
|
||||
clientId: requireValue(config.clientId),
|
||||
clientSecret: requireValue(config.clientSecret),
|
||||
customerCode: normalizeCustomerCode(config.customerCode),
|
||||
...(mandantBinding ? { mandantBinding } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
function validateCredentials(credentials: KwpCredentials, operation: "discovery" | "health" | "refresh" | "resource"): KwpOAuthClientConfig {
|
||||
const config = validateOAuthConfig(credentials);
|
||||
if (!hasExactRequiredScopes(credentials.scopes) || !Number.isFinite(Date.parse(credentials.expiresAt))) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
if (operation === "health" || operation === "discovery" || operation === "resource") {
|
||||
requireValue(credentials.accessToken);
|
||||
} else {
|
||||
requireValue(credentials.refreshToken);
|
||||
}
|
||||
if ((operation === "health" || operation === "resource") && !config.mandantBinding) {
|
||||
throw new KwpError("mandant_unconfirmed");
|
||||
}
|
||||
return config;
|
||||
}
|
||||
|
||||
function hasExactRequiredScopes(scopes: readonly string[]): boolean {
|
||||
if (scopes.length !== KWP_REQUIRED_OAUTH_SCOPES.length || new Set(scopes).size !== scopes.length) {
|
||||
return false;
|
||||
}
|
||||
return KWP_REQUIRED_OAUTH_SCOPES.every((scope) => scopes.includes(scope)) && !scopes.includes("email");
|
||||
}
|
||||
|
||||
async function requestKwpToken(form: URLSearchParams): Promise<KwpTokenResponse> {
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetchProvider(KWP_TOKEN_URL, {
|
||||
method: "POST",
|
||||
headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
|
||||
body: form.toString(),
|
||||
});
|
||||
} catch {
|
||||
// The POST may already have consumed KWP's one-time refresh token even
|
||||
// though no response reached HiveGrid. Keep that ambiguity distinct from
|
||||
// a demonstrably non-consuming provider response: replaying the same token
|
||||
// here could consume a rotated token twice.
|
||||
throw new KwpError("refresh_outcome_unknown");
|
||||
}
|
||||
|
||||
let body: unknown;
|
||||
try {
|
||||
body = await readProviderJson<unknown>(response, KWP_RESPONSE_LIMIT_BYTES);
|
||||
} catch {
|
||||
if (!response.ok) {
|
||||
throw mapTokenError(response.status);
|
||||
}
|
||||
throw new KwpError("invalid_response", response.status, "token_response_not_json");
|
||||
}
|
||||
if (!response.ok) {
|
||||
throw mapTokenError(response.status, isJsonObject(body) ? body.error : undefined);
|
||||
}
|
||||
if (!isJsonObject(body)) {
|
||||
throw new KwpError("invalid_response", response.status, "token_response_not_object");
|
||||
}
|
||||
return body as unknown as KwpTokenResponse;
|
||||
}
|
||||
|
||||
function isJsonObject(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function toCredentials(config: KwpOAuthClientConfig, token: KwpTokenResponse, refreshToken: string, now: Date): KwpCredentials {
|
||||
const accessToken = readTokenValue(token.access_token);
|
||||
if (!accessToken) {
|
||||
throw new KwpError("invalid_response", undefined, "missing_access_token");
|
||||
}
|
||||
const expiresIn = token.expires_in;
|
||||
if (
|
||||
typeof expiresIn !== "number" ||
|
||||
!Number.isSafeInteger(expiresIn) ||
|
||||
expiresIn <= 0 ||
|
||||
expiresIn > KWP_ACCESS_TOKEN_TTL_SECONDS
|
||||
) {
|
||||
throw new KwpError("invalid_response", undefined, "invalid_expiry");
|
||||
}
|
||||
if (!Number.isFinite(now.getTime())) {
|
||||
throw new KwpError("invalid_response", undefined, "invalid_clock");
|
||||
}
|
||||
const expiresAt = new Date(now.getTime() + expiresIn * 1_000);
|
||||
if (!Number.isFinite(expiresAt.getTime())) {
|
||||
throw new KwpError("invalid_response", undefined, "invalid_expiry");
|
||||
}
|
||||
return {
|
||||
accessToken,
|
||||
refreshToken,
|
||||
expiresAt: expiresAt.toISOString(),
|
||||
issuer: KWP_OIDC_ISSUER,
|
||||
clientId: config.clientId,
|
||||
clientSecret: config.clientSecret,
|
||||
customerCode: config.customerCode,
|
||||
// Persist HiveGrid's canonical request/policy set, never the provider's
|
||||
// potentially reduced token-response scope echo.
|
||||
scopes: [...KWP_REQUIRED_OAUTH_SCOPES],
|
||||
...(config.mandantBinding ? { mandantBinding: config.mandantBinding } : {}),
|
||||
};
|
||||
}
|
||||
|
||||
async function fetchKwpOutbound(endpoint: string, init: RequestInit, options: KwpOutboundRequestOptions): Promise<Response> {
|
||||
try {
|
||||
return await fetchOutboundHttpWithRedirects(endpoint, init, {
|
||||
...options,
|
||||
allowCrossOriginRedirects: false,
|
||||
urlValidator: validateKwpOnlineUrl,
|
||||
});
|
||||
} catch (error) {
|
||||
if (error instanceof KwpError) {
|
||||
throw error;
|
||||
}
|
||||
if (error instanceof OutboundHttpUrlValidationError) {
|
||||
throw new KwpError("relay_host_invalid");
|
||||
}
|
||||
throw new KwpError("provider_outage");
|
||||
}
|
||||
}
|
||||
|
||||
async function readKwpResponseBody(response: Response): Promise<string> {
|
||||
try {
|
||||
const result = await readLimitedResponseText(response, KWP_RESPONSE_LIMIT_BYTES);
|
||||
if (result.truncated) {
|
||||
throw new KwpError("invalid_response", response.status);
|
||||
}
|
||||
return result.body.trim();
|
||||
} catch (error) {
|
||||
if (error instanceof KwpError) {
|
||||
throw error;
|
||||
}
|
||||
throw new KwpError("invalid_response", response.status);
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeRelayBaseUrl(value: string): string {
|
||||
const validated = validateKwpOnlineUrl(value);
|
||||
const url = new URL(validated);
|
||||
if ((url.pathname !== "" && url.pathname !== "/") || url.search) {
|
||||
throw new KwpError("relay_host_invalid");
|
||||
}
|
||||
return url.origin;
|
||||
}
|
||||
|
||||
function assertCentralIssuer(issuer: string): void {
|
||||
let normalized: string;
|
||||
try {
|
||||
const url = new URL(issuer);
|
||||
if (url.search || url.hash || url.username || url.password) {
|
||||
throw new Error("invalid issuer");
|
||||
}
|
||||
normalized = url.toString().replace(/\/$/u, "");
|
||||
} catch {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
if (normalized !== KWP_OIDC_ISSUER) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeCustomerCode(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!isValidKwpContextCode(normalized)) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeMandantBinding(value: KwpMandantBinding | undefined): KwpMandantBinding | undefined {
|
||||
if (value === undefined) return undefined;
|
||||
if (!isJsonObject(value)) throw new KwpError("invalid_credentials");
|
||||
const keys = Object.keys(value);
|
||||
if (value.kind === "none") {
|
||||
if (keys.length !== 1 || keys[0] !== "kind" || !Object.hasOwn(value, "kind")) throw new KwpError("invalid_credentials");
|
||||
return { kind: "none" };
|
||||
}
|
||||
if (value.kind !== "selected" || !Object.hasOwn(value, "kind") || !keys.every((key) => key === "kind" || key === "code" || key === "label")) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
if (!Object.hasOwn(value, "code") || typeof value.code !== "string" || keys.length < 2 || keys.length > 3) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
const code = normalizeCustomerCode(value.code);
|
||||
const label = normalizeMandantLabel(value.label);
|
||||
return { kind: "selected", code, ...(label ? { label } : {}) };
|
||||
}
|
||||
|
||||
function requireValue(value: string): string {
|
||||
if (typeof value !== "string" || !value.trim()) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function readTokenValue(value: unknown): string | null {
|
||||
return typeof value === "string" && value.trim() ? value.trim() : null;
|
||||
}
|
||||
|
||||
function parseKwpApiMajorVersion(body: string, status: number): string {
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(body);
|
||||
} catch {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
if (typeof value !== "number" || !Number.isInteger(value) || value < -2_147_483_648 || value > 2_147_483_647) {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
return String(value);
|
||||
}
|
||||
|
||||
function parseKwpMandants(body: string, status: number): KwpMandant[] {
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(body);
|
||||
} catch {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
if (!Array.isArray(value) || value.length > KWP_MANDANT_RESPONSE_MAX_ENTRIES) {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
|
||||
const normalized = value.map((entry) => normalizeKwpMandant(entry, status));
|
||||
normalized.sort(compareKwpMandants);
|
||||
const uniqueByCode = new Map<string, KwpMandant>();
|
||||
for (const mandant of normalized) {
|
||||
if (!uniqueByCode.has(mandant.code)) uniqueByCode.set(mandant.code, mandant);
|
||||
}
|
||||
return [...uniqueByCode.values()];
|
||||
}
|
||||
|
||||
function normalizeKwpMandant(value: unknown, status: number): KwpMandant {
|
||||
if (!isJsonObject(value)) throw new KwpError("invalid_response", status);
|
||||
const keys = Object.keys(value);
|
||||
if (
|
||||
keys.length !== 3 ||
|
||||
!keys.every((key) => key === "id" || key === "kuerzel" || key === "bezeichnung") ||
|
||||
!Object.hasOwn(value, "id") ||
|
||||
!Object.hasOwn(value, "kuerzel") ||
|
||||
!Object.hasOwn(value, "bezeichnung") ||
|
||||
typeof value.id !== "number" ||
|
||||
!Number.isInteger(value.id) ||
|
||||
value.id < -2_147_483_648 ||
|
||||
value.id > 2_147_483_647 ||
|
||||
(value.kuerzel !== null && typeof value.kuerzel !== "string") ||
|
||||
(value.bezeichnung !== null && typeof value.bezeichnung !== "string")
|
||||
) {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
|
||||
// The OpenAPI DTO permits null, but a null code cannot form a selected
|
||||
// binding. Reject it instead of silently turning a multi-mandant tenant into
|
||||
// the semantically different `none` binding.
|
||||
if (value.kuerzel === null) throw new KwpError("invalid_response", status);
|
||||
const code = normalizeDiscoveredMandantCode(value.kuerzel, status);
|
||||
const label = normalizeDiscoveredMandantLabel(value.bezeichnung, status);
|
||||
return { id: value.id, code, ...(label ? { label } : {}) };
|
||||
}
|
||||
|
||||
function normalizeDiscoveredMandantCode(value: string, status: number): string {
|
||||
const normalized = value.trim();
|
||||
if (!isValidKwpContextCode(normalized)) throw new KwpError("invalid_response", status);
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeDiscoveredMandantLabel(value: string | null, status: number): string | undefined {
|
||||
if (value === null) return undefined;
|
||||
const normalized = value.trim();
|
||||
if (normalized.length > KWP_MANDANT_LABEL_MAX_LENGTH || CONTROL_CHARACTER_PATTERN.test(normalized)) {
|
||||
throw new KwpError("invalid_response", status);
|
||||
}
|
||||
return normalized || undefined;
|
||||
}
|
||||
|
||||
function normalizeMandantLabel(value: unknown): string | undefined {
|
||||
if (value === undefined) return undefined;
|
||||
if (typeof value !== "string") throw new KwpError("invalid_credentials");
|
||||
const normalized = value.trim();
|
||||
if (!normalized || normalized.length > KWP_MANDANT_LABEL_MAX_LENGTH || CONTROL_CHARACTER_PATTERN.test(normalized)) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function compareKwpMandants(left: KwpMandant, right: KwpMandant): number {
|
||||
if (left.code !== right.code) return left.code < right.code ? -1 : 1;
|
||||
if (left.id !== right.id) return left.id - right.id;
|
||||
const leftLabel = left.label ?? "";
|
||||
const rightLabel = right.label ?? "";
|
||||
return leftLabel === rightLabel ? 0 : leftLabel < rightLabel ? -1 : 1;
|
||||
}
|
||||
|
||||
function mapTokenError(status: number, providerError?: unknown): KwpError {
|
||||
if (status === 408) return new KwpError("refresh_outcome_unknown", status);
|
||||
if (status === 429) return new KwpError("rate_limit_exceeded", status);
|
||||
if (typeof providerError === "string") {
|
||||
if (providerError === "temporarily_unavailable" || providerError === "server_error") {
|
||||
return new KwpError("provider_outage", status);
|
||||
}
|
||||
if (providerError === "invalid_scope") return new KwpError("auth_scope_missing", status);
|
||||
if (providerError === "invalid_grant") return new KwpError("auth_token_invalid", status);
|
||||
if (providerError === "invalid_client" || providerError === "unauthorized_client" || providerError === "unsupported_grant_type") {
|
||||
return new KwpError("invalid_credentials", status);
|
||||
}
|
||||
}
|
||||
// A generic 5xx does not prove whether Keycloak consumed KWP's single-use
|
||||
// refresh token before an intermediary replaced or truncated the response.
|
||||
// Only the explicit OAuth errors above are safe to replay.
|
||||
if (status >= 500) return new KwpError("refresh_outcome_unknown", status);
|
||||
if (status === 400 || status === 401) return new KwpError("auth_token_invalid", status);
|
||||
if (status === 403) return new KwpError("auth_scope_missing", status);
|
||||
return new KwpError("unknown", status);
|
||||
}
|
||||
|
||||
function mapRelayError(status: number): KwpError {
|
||||
if (status === 404) return new KwpError("relay_not_found", status);
|
||||
if (status === 429) return new KwpError("rate_limit_exceeded", status);
|
||||
if (status >= 500) return new KwpError("provider_outage", status);
|
||||
return new KwpError("unknown", status);
|
||||
}
|
||||
|
||||
function mapHealthError(status: number): KwpError {
|
||||
if (status === 401) return new KwpError("auth_token_invalid", status);
|
||||
if (status === 403) return new KwpError("auth_scope_missing", status);
|
||||
if (status === 404) return new KwpError("relay_not_found", status);
|
||||
if (status === 429) return new KwpError("rate_limit_exceeded", status);
|
||||
if (status >= 500) return new KwpError("provider_outage", status);
|
||||
return new KwpError("unknown", status);
|
||||
}
|
||||
|
||||
function mapMandantDiscoveryError(status: number): KwpError {
|
||||
if (status === 401) return new KwpError("auth_token_invalid", status);
|
||||
if (status === 403 || status === 404) return new KwpError("mandant_discovery_unavailable", status);
|
||||
if (status === 429) return new KwpError("rate_limit_exceeded", status);
|
||||
if (status >= 500) return new KwpError("provider_outage", status);
|
||||
return new KwpError("unknown", status);
|
||||
}
|
||||
+626
@@ -0,0 +1,626 @@
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import type { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
import { auditEvent, notify } from "@hivegrid/foundation";
|
||||
|
||||
import { loadScopedSemanticContracts, loadProjectSemanticContract, validateProjectAdapterAgainstCurrentContract } from "./resource-client.server.js";
|
||||
import { getKwpScopedCapabilityKey, KWP_PROJECT_ADAPTER_REVISION, KWP_PROJECT_CAPABILITY, type KwpSemanticContract } from "./resource-client.js";
|
||||
import { listKwpCapabilities, type KwpCapability, type KwpCapabilitySemanticContract } from "./scoped-contract.js";
|
||||
|
||||
export type KwpContractSentinelResult =
|
||||
| { readonly status: "initialized" | "unchanged"; readonly fingerprint: string }
|
||||
| { readonly status: "paused"; readonly fingerprint: string; readonly previousFingerprint: string; readonly diff: KwpRedactedContractDiff };
|
||||
|
||||
export type KwpRedactedContractDiff = {
|
||||
readonly added: readonly string[];
|
||||
readonly removed: readonly string[];
|
||||
readonly changed: readonly string[];
|
||||
readonly truncated: boolean;
|
||||
};
|
||||
|
||||
export type KwpScopedContractSentinelResult = Readonly<Record<KwpCapability, KwpContractSentinelResult>>;
|
||||
|
||||
export class KwpContractSentinelError extends Error {
|
||||
readonly code: "not_found" | "stale_write" | "validation_required";
|
||||
constructor(code: KwpContractSentinelError["code"]) {
|
||||
super(code);
|
||||
this.name = "KwpContractSentinelError";
|
||||
this.code = code;
|
||||
}
|
||||
}
|
||||
|
||||
export async function runKwpProjectContractSentinel(input: { readonly connectionId: string }): Promise<KwpContractSentinelResult> {
|
||||
const tenantId = requireTenantContext();
|
||||
const connectionId = normalizeId(input.connectionId);
|
||||
|
||||
// Tenant OpenAPI is provider I/O and must finish before the short state tx.
|
||||
const current = await loadProjectSemanticContract({ connectionId });
|
||||
const now = new Date();
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const connection = await tx.dataConnection.findFirst({
|
||||
where: { id: connectionId, tenantId, appId: "kwp", archivedAt: null },
|
||||
select: { id: true, createdByUserId: true },
|
||||
});
|
||||
if (!connection) throw new KwpContractSentinelError("not_found");
|
||||
const state = await tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
},
|
||||
},
|
||||
});
|
||||
const approvedFingerprint = state?.approvedFingerprint;
|
||||
const previousSnapshot = approvedFingerprint
|
||||
? await tx.kwpApiContractSnapshot.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability_semanticFingerprint: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
semanticFingerprint: approvedFingerprint,
|
||||
},
|
||||
},
|
||||
})
|
||||
: null;
|
||||
await persistContractSnapshot(tx, tenantId, connectionId, current, now);
|
||||
|
||||
if (!state || !approvedFingerprint) {
|
||||
const recoversUninitializedPause = state?.status === "paused";
|
||||
await tx.kwpCapabilityState.upsert({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
status: "active",
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
approvedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 1,
|
||||
lastCheckedAt: now,
|
||||
approvedAt: now,
|
||||
},
|
||||
update: {
|
||||
status: "active",
|
||||
reasonCode: null,
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
approvedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: null,
|
||||
lastCheckedAt: now,
|
||||
approvedAt: now,
|
||||
},
|
||||
});
|
||||
if (recoversUninitializedPause) {
|
||||
await tx.kwpErrorReport.updateMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
resolvedAt: null,
|
||||
},
|
||||
data: { resolvedAt: now },
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_CONTRACT_BASELINE_RECOVERED",
|
||||
targetType: "DataConnection",
|
||||
targetId: connectionId,
|
||||
metadata: {
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
approvedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
}
|
||||
return { status: "initialized", fingerprint: current.semanticFingerprint };
|
||||
}
|
||||
|
||||
if (approvedFingerprint === current.semanticFingerprint) {
|
||||
await tx.kwpCapabilityState.update({
|
||||
where: { id: state.id },
|
||||
data: {
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
});
|
||||
return { status: "unchanged", fingerprint: current.semanticFingerprint };
|
||||
}
|
||||
|
||||
const diff = buildRedactedContractDiff(previousSnapshot?.consumedContract ?? {}, current.consumedContract);
|
||||
await tx.kwpCapabilityState.update({
|
||||
where: { id: state.id },
|
||||
data: {
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: now,
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
});
|
||||
await tx.kwpErrorReport.create({
|
||||
data: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
code: "kwp.project.contract_drift",
|
||||
redactedDetails: {
|
||||
previousFingerprint: approvedFingerprint,
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
diff,
|
||||
},
|
||||
},
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_CONTRACT_DRIFT_DETECTED",
|
||||
targetType: "DataConnection",
|
||||
targetId: connectionId,
|
||||
metadata: {
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
previousFingerprint: approvedFingerprint,
|
||||
observedFingerprint: current.semanticFingerprint,
|
||||
},
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
await notify(
|
||||
{
|
||||
tenantId,
|
||||
userId: connection.createdByUserId,
|
||||
category: "integrations",
|
||||
messageKey: "integrations.kwp.project.contractDrift",
|
||||
sourceKey: `kwp-contract:${connectionId}:${current.semanticFingerprint}`,
|
||||
payloadMetadata: { connectionId, capability: KWP_PROJECT_CAPABILITY },
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
return {
|
||||
status: "paused",
|
||||
fingerprint: current.semanticFingerprint,
|
||||
previousFingerprint: approvedFingerprint,
|
||||
diff,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/** Runs the complete licensed OpenAPI contract through five independent state
|
||||
* machines. Drift in one family cannot pause another family or OAuth health. */
|
||||
export async function runKwpScopedContractSentinel(input: { readonly connectionId: string }): Promise<KwpScopedContractSentinelResult> {
|
||||
const tenantId = requireTenantContext();
|
||||
const connectionId = normalizeId(input.connectionId);
|
||||
const contracts = await loadScopedSemanticContracts({ connectionId });
|
||||
const byCapability = new Map(contracts.map((contract) => [contract.capability, contract]));
|
||||
const now = new Date();
|
||||
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const connection = await tx.dataConnection.findFirst({
|
||||
where: { id: connectionId, tenantId, appId: "kwp", archivedAt: null },
|
||||
select: { id: true, createdByUserId: true },
|
||||
});
|
||||
if (!connection) throw new KwpContractSentinelError("not_found");
|
||||
|
||||
const results = {} as Record<KwpCapability, KwpContractSentinelResult>;
|
||||
for (const capability of listKwpCapabilities()) {
|
||||
const current = byCapability.get(capability);
|
||||
if (!current) throw new KwpContractSentinelError("validation_required");
|
||||
results[capability] = await reconcileScopedContractState({
|
||||
tx,
|
||||
tenantId,
|
||||
connectionId,
|
||||
createdByUserId: connection.createdByUserId,
|
||||
capability,
|
||||
current,
|
||||
now,
|
||||
});
|
||||
}
|
||||
return results;
|
||||
});
|
||||
}
|
||||
|
||||
export async function runKwpAllContractSentinels(input: { readonly connectionId: string }): Promise<
|
||||
KwpContractSentinelResult & {
|
||||
readonly scoped: KwpScopedContractSentinelResult;
|
||||
}
|
||||
> {
|
||||
const project = await runKwpProjectContractSentinel(input);
|
||||
const scoped = await runKwpScopedContractSentinel(input);
|
||||
return { ...project, scoped };
|
||||
}
|
||||
|
||||
export async function approveKwpProjectContract(input: {
|
||||
readonly tenantId: string;
|
||||
readonly connectionId: string;
|
||||
readonly expectedRevision: number;
|
||||
readonly observedFingerprint: string;
|
||||
readonly validationProjectNumber: string;
|
||||
readonly actorUserId: string;
|
||||
}): Promise<void> {
|
||||
assertTenantContext(input.tenantId);
|
||||
const connectionId = normalizeId(input.connectionId);
|
||||
const actorUserId = normalizeId(input.actorUserId);
|
||||
const observedFingerprint = normalizeFingerprint(input.observedFingerprint);
|
||||
|
||||
// Approval is impossible until this exact adapter parses current project and
|
||||
// address responses successfully. The call is read-only and allowed while
|
||||
// the capability itself is paused.
|
||||
await validateProjectAdapterAgainstCurrentContract({
|
||||
connectionId,
|
||||
externalProjectNumber: input.validationProjectNumber.trim(),
|
||||
});
|
||||
|
||||
const now = new Date();
|
||||
await getDbClient().$transaction(async (tx) => {
|
||||
const state = await tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
},
|
||||
},
|
||||
});
|
||||
if (!state || state.status !== "paused" || state.revision !== input.expectedRevision || state.observedFingerprint !== observedFingerprint) {
|
||||
throw new KwpContractSentinelError("stale_write");
|
||||
}
|
||||
const snapshot = await tx.kwpApiContractSnapshot.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability_semanticFingerprint: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
semanticFingerprint: observedFingerprint,
|
||||
},
|
||||
},
|
||||
});
|
||||
if (!snapshot || snapshot.adapterRevision !== KWP_PROJECT_ADAPTER_REVISION) {
|
||||
throw new KwpContractSentinelError("validation_required");
|
||||
}
|
||||
const updated = await tx.kwpCapabilityState.updateMany({
|
||||
where: {
|
||||
id: state.id,
|
||||
tenantId: input.tenantId,
|
||||
revision: input.expectedRevision,
|
||||
observedFingerprint,
|
||||
},
|
||||
data: {
|
||||
status: "active",
|
||||
reasonCode: null,
|
||||
approvedFingerprint: observedFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: null,
|
||||
approvedAt: now,
|
||||
approvedByUserId: actorUserId,
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpContractSentinelError("stale_write");
|
||||
await tx.kwpErrorReport.updateMany({
|
||||
where: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
resolvedAt: null,
|
||||
},
|
||||
data: { resolvedAt: now, resolvedByUserId: actorUserId },
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId: input.tenantId,
|
||||
actorId: actorUserId,
|
||||
actorType: "user",
|
||||
action: "KWP_CONTRACT_DRIFT_APPROVED",
|
||||
targetType: "DataConnection",
|
||||
targetId: connectionId,
|
||||
metadata: {
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
approvedFingerprint: observedFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
});
|
||||
}
|
||||
|
||||
export function buildRedactedContractDiff(previous: unknown, current: unknown): KwpRedactedContractDiff {
|
||||
const previousLeaves = flattenContract(previous);
|
||||
const currentLeaves = flattenContract(current);
|
||||
const added: string[] = [];
|
||||
const removed: string[] = [];
|
||||
const changed: string[] = [];
|
||||
for (const path of currentLeaves.keys()) {
|
||||
if (!previousLeaves.has(path)) added.push(path);
|
||||
else if (previousLeaves.get(path) !== currentLeaves.get(path)) changed.push(path);
|
||||
}
|
||||
for (const path of previousLeaves.keys()) if (!currentLeaves.has(path)) removed.push(path);
|
||||
added.sort();
|
||||
removed.sort();
|
||||
changed.sort();
|
||||
const total = added.length + removed.length + changed.length;
|
||||
const limit = 100;
|
||||
return {
|
||||
added: added.slice(0, limit),
|
||||
removed: removed.slice(0, Math.max(0, limit - Math.min(limit, added.length))),
|
||||
changed: changed.slice(0, Math.max(0, limit - Math.min(limit, added.length + removed.length))),
|
||||
truncated: total > limit,
|
||||
};
|
||||
}
|
||||
|
||||
async function persistContractSnapshot(
|
||||
tx: Prisma.TransactionClient,
|
||||
tenantId: string,
|
||||
connectionId: string,
|
||||
contract: KwpSemanticContract,
|
||||
now: Date
|
||||
): Promise<void> {
|
||||
await tx.kwpApiContractSnapshot.upsert({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability_semanticFingerprint: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
semanticFingerprint: contract.semanticFingerprint,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
apiVersion: contract.apiVersion,
|
||||
semanticFingerprint: contract.semanticFingerprint,
|
||||
consumedContract: contract.consumedContract as Prisma.InputJsonValue,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
validatedAt: now,
|
||||
},
|
||||
update: {
|
||||
apiVersion: contract.apiVersion,
|
||||
consumedContract: contract.consumedContract as Prisma.InputJsonValue,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
validatedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async function reconcileScopedContractState(input: {
|
||||
readonly tx: Prisma.TransactionClient;
|
||||
readonly tenantId: string;
|
||||
readonly connectionId: string;
|
||||
readonly createdByUserId: string | null;
|
||||
readonly capability: KwpCapability;
|
||||
readonly current: KwpCapabilitySemanticContract;
|
||||
readonly now: Date;
|
||||
}): Promise<KwpContractSentinelResult> {
|
||||
const capabilityKey = getKwpScopedCapabilityKey(input.capability);
|
||||
const state = await input.tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: input.connectionId,
|
||||
capability: capabilityKey,
|
||||
},
|
||||
},
|
||||
});
|
||||
const approvedFingerprint = state?.approvedFingerprint;
|
||||
const previousSnapshot = approvedFingerprint
|
||||
? await input.tx.kwpApiContractSnapshot.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability_semanticFingerprint: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: input.connectionId,
|
||||
capability: capabilityKey,
|
||||
semanticFingerprint: approvedFingerprint,
|
||||
},
|
||||
},
|
||||
})
|
||||
: null;
|
||||
await persistScopedContractSnapshot(input.tx, input.tenantId, input.connectionId, capabilityKey, input.current, input.now);
|
||||
|
||||
if (!state) {
|
||||
await input.tx.kwpCapabilityState.create({
|
||||
data: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: input.connectionId,
|
||||
capability: capabilityKey,
|
||||
status: "active",
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
approvedFingerprint: input.current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 1,
|
||||
lastCheckedAt: input.now,
|
||||
approvedAt: input.now,
|
||||
},
|
||||
});
|
||||
return { status: "initialized", fingerprint: input.current.semanticFingerprint };
|
||||
}
|
||||
|
||||
if (!approvedFingerprint) {
|
||||
await input.tx.kwpCapabilityState.update({
|
||||
where: { id: state.id },
|
||||
data: {
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
lastCheckedAt: input.now,
|
||||
},
|
||||
});
|
||||
return {
|
||||
status: "paused",
|
||||
fingerprint: input.current.semanticFingerprint,
|
||||
previousFingerprint: input.current.semanticFingerprint,
|
||||
diff: emptyContractDiff(),
|
||||
};
|
||||
}
|
||||
|
||||
if (approvedFingerprint === input.current.semanticFingerprint) {
|
||||
await input.tx.kwpCapabilityState.update({
|
||||
where: { id: state.id },
|
||||
data: {
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
lastCheckedAt: input.now,
|
||||
},
|
||||
});
|
||||
return { status: "unchanged", fingerprint: input.current.semanticFingerprint };
|
||||
}
|
||||
|
||||
const diff = buildRedactedContractDiff(previousSnapshot?.consumedContract ?? {}, input.current.consumedContract);
|
||||
const reasonCode = `kwp.${input.capability}.contract_drift`;
|
||||
await input.tx.kwpCapabilityState.update({
|
||||
where: { id: state.id },
|
||||
data: {
|
||||
status: "paused",
|
||||
reasonCode,
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: input.now,
|
||||
lastCheckedAt: input.now,
|
||||
},
|
||||
});
|
||||
await input.tx.kwpErrorReport.create({
|
||||
data: {
|
||||
tenantId: input.tenantId,
|
||||
dataConnectionId: input.connectionId,
|
||||
capability: capabilityKey,
|
||||
code: reasonCode,
|
||||
redactedDetails: {
|
||||
previousFingerprint: approvedFingerprint,
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
diff,
|
||||
},
|
||||
},
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId: input.tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_CONTRACT_DRIFT_DETECTED",
|
||||
targetType: "DataConnection",
|
||||
targetId: input.connectionId,
|
||||
metadata: {
|
||||
capability: capabilityKey,
|
||||
previousFingerprint: approvedFingerprint,
|
||||
observedFingerprint: input.current.semanticFingerprint,
|
||||
},
|
||||
},
|
||||
input.tx as never
|
||||
);
|
||||
await notify(
|
||||
{
|
||||
tenantId: input.tenantId,
|
||||
userId: input.createdByUserId,
|
||||
category: "integrations",
|
||||
messageKey: "integrations.kwp.project.contractDrift",
|
||||
sourceKey: `kwp-contract:${input.connectionId}:${capabilityKey}:${input.current.semanticFingerprint}`,
|
||||
payloadMetadata: { connectionId: input.connectionId, capability: capabilityKey },
|
||||
},
|
||||
input.tx as never
|
||||
);
|
||||
return {
|
||||
status: "paused",
|
||||
fingerprint: input.current.semanticFingerprint,
|
||||
previousFingerprint: approvedFingerprint,
|
||||
diff,
|
||||
};
|
||||
}
|
||||
|
||||
async function persistScopedContractSnapshot(
|
||||
tx: Prisma.TransactionClient,
|
||||
tenantId: string,
|
||||
connectionId: string,
|
||||
capability: string,
|
||||
contract: KwpCapabilitySemanticContract,
|
||||
now: Date
|
||||
): Promise<void> {
|
||||
await tx.kwpApiContractSnapshot.upsert({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability_semanticFingerprint: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability,
|
||||
semanticFingerprint: contract.semanticFingerprint,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability,
|
||||
apiVersion: contract.apiVersion,
|
||||
semanticFingerprint: contract.semanticFingerprint,
|
||||
consumedContract: contract.consumedContract as Prisma.InputJsonValue,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
validatedAt: now,
|
||||
},
|
||||
update: {
|
||||
apiVersion: contract.apiVersion,
|
||||
consumedContract: contract.consumedContract as Prisma.InputJsonValue,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
validatedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function emptyContractDiff(): KwpRedactedContractDiff {
|
||||
return { added: [], removed: [], changed: [], truncated: false };
|
||||
}
|
||||
|
||||
function flattenContract(value: unknown, prefix = "$", result = new Map<string, string>()): Map<string, string> {
|
||||
if (Array.isArray(value)) {
|
||||
value.forEach((item, index) => flattenContract(item, `${prefix}[${index}]`, result));
|
||||
return result;
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
|
||||
flattenContract(nested, `${prefix}.${key}`, result);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
result.set(prefix, JSON.stringify(value));
|
||||
return result;
|
||||
}
|
||||
|
||||
function requireTenantContext(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpContractSentinelError("not_found");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function assertTenantContext(tenantId: string): void {
|
||||
if (requireTenantContext() !== normalizeId(tenantId)) throw new KwpContractSentinelError("not_found");
|
||||
}
|
||||
|
||||
function normalizeId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{3,191}$/u.test(normalized)) throw new KwpContractSentinelError("not_found");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeFingerprint(value: string): string {
|
||||
const normalized = value.trim().toLowerCase();
|
||||
if (!/^[a-f0-9]{64}$/u.test(normalized)) throw new KwpContractSentinelError("stale_write");
|
||||
return normalized;
|
||||
}
|
||||
+349
@@ -0,0 +1,349 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
transaction: vi.fn(),
|
||||
loadProjectSemanticContract: vi.fn(),
|
||||
loadScopedSemanticContracts: vi.fn(),
|
||||
validateProjectAdapterAgainstCurrentContract: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
auditEvent: vi.fn(),
|
||||
notify: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
stateFindUnique: vi.fn(),
|
||||
stateCreate: vi.fn(),
|
||||
stateUpsert: vi.fn(),
|
||||
stateUpdate: vi.fn(),
|
||||
stateUpdateMany: vi.fn(),
|
||||
snapshotFindUnique: vi.fn(),
|
||||
snapshotUpsert: vi.fn(),
|
||||
reportCreate: vi.fn(),
|
||||
reportUpdateMany: vi.fn(),
|
||||
events: [] as string[],
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({ $transaction: mocks.transaction }),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({
|
||||
getRlsExecutionContext: mocks.getRlsExecutionContext,
|
||||
}));
|
||||
vi.mock("@hivegrid/foundation", () => ({
|
||||
auditEvent: mocks.auditEvent,
|
||||
notify: mocks.notify,
|
||||
}));
|
||||
vi.mock("./resource-client.server.js", () => ({
|
||||
loadProjectSemanticContract: mocks.loadProjectSemanticContract,
|
||||
loadScopedSemanticContracts: mocks.loadScopedSemanticContracts,
|
||||
validateProjectAdapterAgainstCurrentContract: mocks.validateProjectAdapterAgainstCurrentContract,
|
||||
}));
|
||||
|
||||
import {
|
||||
approveKwpProjectContract,
|
||||
buildRedactedContractDiff,
|
||||
runKwpScopedContractSentinel,
|
||||
runKwpProjectContractSentinel,
|
||||
} from "./contract-sentinel.server.js";
|
||||
import { KWP_PROJECT_ADAPTER_REVISION } from "./resource-client.js";
|
||||
|
||||
const tx = {
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
kwpCapabilityState: {
|
||||
findUnique: mocks.stateFindUnique,
|
||||
create: mocks.stateCreate,
|
||||
upsert: mocks.stateUpsert,
|
||||
update: mocks.stateUpdate,
|
||||
updateMany: mocks.stateUpdateMany,
|
||||
},
|
||||
kwpApiContractSnapshot: {
|
||||
findUnique: mocks.snapshotFindUnique,
|
||||
upsert: mocks.snapshotUpsert,
|
||||
},
|
||||
kwpErrorReport: {
|
||||
create: mocks.reportCreate,
|
||||
updateMany: mocks.reportUpdateMany,
|
||||
},
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.events.length = 0;
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1", userId: "user-1" });
|
||||
mocks.transaction.mockImplementation(async (callback) => {
|
||||
mocks.events.push("tx");
|
||||
return callback(tx);
|
||||
});
|
||||
mocks.connectionFindFirst.mockResolvedValue({ id: "connection-1", createdByUserId: "user-1" });
|
||||
mocks.snapshotUpsert.mockResolvedValue({});
|
||||
mocks.reportCreate.mockResolvedValue({});
|
||||
mocks.reportUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.stateUpdate.mockResolvedValue({});
|
||||
mocks.stateCreate.mockResolvedValue({});
|
||||
mocks.stateUpsert.mockResolvedValue({});
|
||||
mocks.stateUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.auditEvent.mockResolvedValue(undefined);
|
||||
mocks.notify.mockResolvedValue(undefined);
|
||||
mocks.validateProjectAdapterAgainstCurrentContract.mockImplementation(async () => {
|
||||
mocks.events.push("adapter-validation");
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP project contract sentinel diff", () => {
|
||||
it("reports only semantic leaf paths and never includes values", () => {
|
||||
const diff = buildRedactedContractDiff(
|
||||
{
|
||||
project: {
|
||||
fields: {
|
||||
projNr: { type: "string" },
|
||||
internalToken: "must-not-leak",
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
project: {
|
||||
fields: {
|
||||
projNr: { type: "integer" },
|
||||
newField: { type: "string" },
|
||||
},
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
expect(diff).toEqual({
|
||||
added: ["$.project.fields.newField.type"],
|
||||
removed: ["$.project.fields.internalToken"],
|
||||
changed: ["$.project.fields.projNr.type"],
|
||||
truncated: false,
|
||||
});
|
||||
expect(JSON.stringify(diff)).not.toContain("must-not-leak");
|
||||
});
|
||||
|
||||
it("caps an operator-visible diff at one hundred paths", () => {
|
||||
const current = Object.fromEntries(Array.from({ length: 125 }, (_, index) => [`field${index}`, { type: "string" }]));
|
||||
const diff = buildRedactedContractDiff({}, current);
|
||||
|
||||
expect(diff.added).toHaveLength(100);
|
||||
expect(diff.removed).toHaveLength(0);
|
||||
expect(diff.changed).toHaveLength(0);
|
||||
expect(diff.truncated).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP project contract capability state", () => {
|
||||
it("recovers and audits an uninitialized response-schema pause against the current semantic contract", async () => {
|
||||
const fingerprint = "a".repeat(64);
|
||||
mocks.loadProjectSemanticContract.mockResolvedValue({
|
||||
apiVersion: "v1",
|
||||
semanticFingerprint: fingerprint,
|
||||
consumedContract: { project: { projNr: { type: "string" } } },
|
||||
});
|
||||
mocks.stateFindUnique.mockResolvedValue({
|
||||
id: "state-1",
|
||||
status: "paused",
|
||||
approvedFingerprint: null,
|
||||
});
|
||||
|
||||
await expect(runKwpProjectContractSentinel({ connectionId: "connection-1" })).resolves.toEqual({
|
||||
status: "initialized",
|
||||
fingerprint,
|
||||
});
|
||||
|
||||
expect(mocks.stateUpsert).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
update: expect.objectContaining({
|
||||
status: "active",
|
||||
reasonCode: null,
|
||||
approvedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
}),
|
||||
})
|
||||
);
|
||||
expect(mocks.reportUpdateMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
resolvedAt: null,
|
||||
},
|
||||
data: { resolvedAt: expect.any(Date) },
|
||||
});
|
||||
expect(mocks.auditEvent).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
action: "KWP_CONTRACT_BASELINE_RECOVERED",
|
||||
metadata: expect.objectContaining({
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
approvedFingerprint: fingerprint,
|
||||
}),
|
||||
}),
|
||||
tx
|
||||
);
|
||||
});
|
||||
|
||||
it("pauses only the project import capability when the consumed semantic contract drifts", async () => {
|
||||
mocks.loadProjectSemanticContract.mockResolvedValue({
|
||||
apiVersion: "v2",
|
||||
semanticFingerprint: "b".repeat(64),
|
||||
consumedContract: { project: { projNr: { type: "integer" } } },
|
||||
});
|
||||
mocks.stateFindUnique.mockResolvedValue({
|
||||
id: "state-1",
|
||||
approvedFingerprint: "a".repeat(64),
|
||||
});
|
||||
mocks.snapshotFindUnique.mockResolvedValue({
|
||||
consumedContract: { project: { projNr: { type: "string" } } },
|
||||
});
|
||||
|
||||
const result = await runKwpProjectContractSentinel({ connectionId: "connection-1" });
|
||||
|
||||
expect(result).toMatchObject({
|
||||
status: "paused",
|
||||
fingerprint: "b".repeat(64),
|
||||
previousFingerprint: "a".repeat(64),
|
||||
});
|
||||
expect(mocks.stateUpdate).toHaveBeenCalledWith({
|
||||
where: { id: "state-1" },
|
||||
data: expect.objectContaining({
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
observedFingerprint: "b".repeat(64),
|
||||
}),
|
||||
});
|
||||
expect(mocks.reportCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
capability: "project-import",
|
||||
code: "kwp.project.contract_drift",
|
||||
redactedDetails: expect.objectContaining({
|
||||
previousFingerprint: "a".repeat(64),
|
||||
observedFingerprint: "b".repeat(64),
|
||||
}),
|
||||
}),
|
||||
});
|
||||
expect(mocks.notify).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
messageKey: "integrations.kwp.project.contractDrift",
|
||||
}),
|
||||
tx
|
||||
);
|
||||
});
|
||||
|
||||
it("validates the current adapter before safely approving the exact observed fingerprint", async () => {
|
||||
const fingerprint = "c".repeat(64);
|
||||
mocks.stateFindUnique.mockResolvedValue({
|
||||
id: "state-1",
|
||||
status: "paused",
|
||||
revision: 5,
|
||||
observedFingerprint: fingerprint,
|
||||
});
|
||||
mocks.snapshotFindUnique.mockResolvedValue({
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
});
|
||||
|
||||
await approveKwpProjectContract({
|
||||
tenantId: "tenant-1",
|
||||
connectionId: "connection-1",
|
||||
expectedRevision: 5,
|
||||
observedFingerprint: fingerprint,
|
||||
validationProjectNumber: "P-100",
|
||||
actorUserId: "user-1",
|
||||
});
|
||||
|
||||
expect(mocks.events).toEqual(["adapter-validation", "tx"]);
|
||||
expect(mocks.validateProjectAdapterAgainstCurrentContract).toHaveBeenCalledWith({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "P-100",
|
||||
});
|
||||
expect(mocks.stateUpdateMany).toHaveBeenCalledWith({
|
||||
where: expect.objectContaining({
|
||||
id: "state-1",
|
||||
revision: 5,
|
||||
tenantId: "tenant-1",
|
||||
observedFingerprint: fingerprint,
|
||||
}),
|
||||
data: expect.objectContaining({
|
||||
status: "active",
|
||||
approvedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
}),
|
||||
});
|
||||
expect(mocks.reportUpdateMany).toHaveBeenCalledWith({
|
||||
where: expect.objectContaining({
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
resolvedAt: null,
|
||||
}),
|
||||
data: expect.objectContaining({ resolvedByUserId: "user-1" }),
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP scoped contract capability state", () => {
|
||||
it("pauses only the drifted family while all other scoped capabilities remain active", async () => {
|
||||
const capabilities = ["activity", "address", "archive", "project", "schedule"] as const;
|
||||
mocks.loadScopedSemanticContracts.mockResolvedValue(
|
||||
capabilities.map((capability) => ({
|
||||
apiVersion: "v1",
|
||||
capability,
|
||||
semanticFingerprint: capability === "address" ? "b".repeat(64) : "a".repeat(64),
|
||||
consumedContract: { capability, response: { type: capability === "address" ? "integer" : "string" } },
|
||||
}))
|
||||
);
|
||||
mocks.stateFindUnique.mockImplementation(async (query) => {
|
||||
const capability = query.where.tenantId_dataConnectionId_capability.capability as string;
|
||||
return {
|
||||
id: `state-${capability}`,
|
||||
status: "active",
|
||||
approvedFingerprint: "a".repeat(64),
|
||||
};
|
||||
});
|
||||
mocks.snapshotFindUnique.mockResolvedValue({
|
||||
consumedContract: { capability: "address", response: { type: "string" } },
|
||||
});
|
||||
|
||||
const result = await runKwpScopedContractSentinel({ connectionId: "connection-1" });
|
||||
|
||||
expect(result.address).toMatchObject({
|
||||
status: "paused",
|
||||
fingerprint: "b".repeat(64),
|
||||
previousFingerprint: "a".repeat(64),
|
||||
});
|
||||
expect(result.activity.status).toBe("unchanged");
|
||||
expect(result.archive.status).toBe("unchanged");
|
||||
expect(result.project.status).toBe("unchanged");
|
||||
expect(result.schedule.status).toBe("unchanged");
|
||||
expect(mocks.stateUpdate).toHaveBeenCalledTimes(5);
|
||||
expect(mocks.stateUpdate).toHaveBeenCalledWith({
|
||||
where: { id: "state-kwp-scoped-address" },
|
||||
data: expect.objectContaining({
|
||||
status: "paused",
|
||||
reasonCode: "kwp.address.contract_drift",
|
||||
observedFingerprint: "b".repeat(64),
|
||||
}),
|
||||
});
|
||||
expect(mocks.reportCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
capability: "kwp-scoped-address",
|
||||
code: "kwp.address.contract_drift",
|
||||
}),
|
||||
});
|
||||
expect(mocks.notify).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("initializes all five capabilities independently on a first revision", async () => {
|
||||
const capabilities = ["activity", "address", "archive", "project", "schedule"] as const;
|
||||
mocks.loadScopedSemanticContracts.mockResolvedValue(
|
||||
capabilities.map((capability, index) => ({
|
||||
apiVersion: "v1",
|
||||
capability,
|
||||
semanticFingerprint: String(index + 1).repeat(64),
|
||||
consumedContract: { capability },
|
||||
}))
|
||||
);
|
||||
mocks.stateFindUnique.mockResolvedValue(null);
|
||||
|
||||
const result = await runKwpScopedContractSentinel({ connectionId: "connection-1" });
|
||||
|
||||
expect(Object.values(result).map((entry) => entry.status)).toEqual(["initialized", "initialized", "initialized", "initialized", "initialized"]);
|
||||
expect(mocks.stateCreate).toHaveBeenCalledTimes(5);
|
||||
expect(mocks.snapshotUpsert).toHaveBeenCalledTimes(5);
|
||||
});
|
||||
});
|
||||
+190
@@ -0,0 +1,190 @@
|
||||
// Generated by scripts/generate-kwp-scoped-contract.mjs. Do not edit manually.
|
||||
export const KWP_SCOPED_OPERATION_INVENTORY = Object.freeze({
|
||||
sourceOperationCount: 554,
|
||||
scopedOperationCount: 113,
|
||||
readOperationCount: 77,
|
||||
mutationOperationCount: 36,
|
||||
excludedOperationCount: 441,
|
||||
} as const);
|
||||
|
||||
export const KWP_SCOPED_OPERATIONS = Object.freeze([
|
||||
{ id: "aktivitaetAddAktivitaet", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddAktivitaet" },
|
||||
{ id: "aktivitaetAddAktivitaetBase", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddAktivitaetBase" },
|
||||
{ id: "aktivitaetAddHilfreich", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddHilfreich" },
|
||||
{ id: "aktivitaetAddInfoEintrag", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddInfoEintrag" },
|
||||
{ id: "aktivitaetAddVerknuepfung", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddVerknuepfung" },
|
||||
{ id: "aktivitaetAddZusatzadresse", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/AddZusatzadresse" },
|
||||
{ id: "aktivitaetDeleteHilfreich", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/DeleteHilfreich" },
|
||||
{ id: "aktivitaetDeleteInfoEintrag", capability: "activity", mode: "mutation", method: "DELETE", path: "/api/Aktivitaet/DeleteInfoEintrag" },
|
||||
{ id: "aktivitaetDeleteVerknuepfung", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/DeleteVerknuepfung" },
|
||||
{ id: "aktivitaetDeleteZusatzadresse", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/DeleteZusatzadresse" },
|
||||
{ id: "aktivitaetLoadAktivitaetTerminIdGet", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaet/LoadAktivitaetTerminId" },
|
||||
{ id: "aktivitaetLoadAktivitaetTerminIdPost", capability: "activity", mode: "read", method: "POST", path: "/api/Aktivitaet/LoadAktivitaetTerminId" },
|
||||
{ id: "aktivitaetLoadArten", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaet/LoadArten" },
|
||||
{ id: "aktivitaetLoadKennzeichen", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaet/LoadKennzeichen" },
|
||||
{ id: "aktivitaetSaveAktivitaetProperties", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/SaveAktivitaetProperties" },
|
||||
{ id: "aktivitaetSaveInfoEintrag", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/SaveInfoEintrag" },
|
||||
{ id: "aktivitaetSaveInformierteBenutzer", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/SaveInformierteBenutzer" },
|
||||
{
|
||||
id: "aktivitaetSaveInformierteBenutzerProperties",
|
||||
capability: "activity",
|
||||
mode: "mutation",
|
||||
method: "POST",
|
||||
path: "/api/Aktivitaet/SaveInformierteBenutzerProperties",
|
||||
},
|
||||
{ id: "aktivitaetSaveZusatzadresse", capability: "activity", mode: "mutation", method: "POST", path: "/api/Aktivitaet/SaveZusatzadresse" },
|
||||
{ id: "aktivitaetenverwaltungCount", capability: "activity", mode: "read", method: "POST", path: "/api/Aktivitaetenverwaltung/Count" },
|
||||
{ id: "aktivitaetenverwaltungGetSetup", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaetenverwaltung/GetSetup" },
|
||||
{ id: "aktivitaetenverwaltungLoadAdressen", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaetenverwaltung/LoadAdressen" },
|
||||
{ id: "aktivitaetenverwaltungLoadAktivitaet", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaetenverwaltung/LoadAktivitaet" },
|
||||
{ id: "aktivitaetenverwaltungLoadAktivitaeten", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaetenverwaltung/LoadAktivitaeten" },
|
||||
{
|
||||
id: "aktivitaetenverwaltungLoadAktivitaetenByAdresskuerzel",
|
||||
capability: "activity",
|
||||
mode: "read",
|
||||
method: "GET",
|
||||
path: "/api/Aktivitaetenverwaltung/LoadAktivitaetenByAdresskuerzel",
|
||||
},
|
||||
{
|
||||
id: "aktivitaetenverwaltungLoadAktivitaetenByVorgang",
|
||||
capability: "activity",
|
||||
mode: "read",
|
||||
method: "GET",
|
||||
path: "/api/Aktivitaetenverwaltung/LoadAktivitaetenByVorgang",
|
||||
},
|
||||
{ id: "aktivitaetenverwaltungLoadEinstellungen", capability: "activity", mode: "read", method: "GET", path: "/api/Aktivitaetenverwaltung/LoadEinstellungen" },
|
||||
{
|
||||
id: "aktivitaetenverwaltungLoadVerknuepfungen",
|
||||
capability: "activity",
|
||||
mode: "read",
|
||||
method: "GET",
|
||||
path: "/api/Aktivitaetenverwaltung/LoadVerknuepfungen",
|
||||
},
|
||||
{
|
||||
id: "aktivitaetenverwaltungSaveEinstellungen",
|
||||
capability: "activity",
|
||||
mode: "mutation",
|
||||
method: "POST",
|
||||
path: "/api/Aktivitaetenverwaltung/SaveEinstellungen",
|
||||
},
|
||||
{ id: "aktivitaetenverwaltungSearch", capability: "activity", mode: "read", method: "POST", path: "/api/Aktivitaetenverwaltung/Search" },
|
||||
{ id: "adresseAddAdresse", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/AddAdresse" },
|
||||
{ id: "adresseAddAnsprechpartner", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/AddAnsprechpartner" },
|
||||
{ id: "adresseAddKontakt", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/AddKontakt" },
|
||||
{ id: "adresseCheckDebitKreditNummerVergeben", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/CheckDebitKreditNummerVergeben" },
|
||||
{ id: "adresseGetDebitKreditNummer", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/GetDebitKreditNummer" },
|
||||
{ id: "adresseGetGeoLocation", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/GetGeoLocation" },
|
||||
{ id: "adresseGetSetup", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/GetSetup" },
|
||||
{ id: "adresseLoadAdressDetails", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadAdressDetails" },
|
||||
{ id: "adresseLoadAdressKomplett", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadAdressKomplett" },
|
||||
{ id: "adresseLoadAnreden", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadAnreden" },
|
||||
{ id: "adresseLoadAnruferInformation", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadAnruferInformation" },
|
||||
{ id: "adresseLoadAnsprechpartnerById", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadAnsprechpartnerById" },
|
||||
{ id: "adresseLoadBriefanreden", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadBriefanreden" },
|
||||
{ id: "adresseLoadSelekts", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadSelekts" },
|
||||
{ id: "adresseLoadWunschtermine", capability: "address", mode: "read", method: "GET", path: "/api/Adresse/LoadWunschtermine" },
|
||||
{ id: "adresseRemoveAnsprechpartner", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/RemoveAnsprechpartner" },
|
||||
{ id: "adresseRemoveKontakt", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/RemoveKontakt" },
|
||||
{ id: "adresseSaveAdresse", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/SaveAdresse" },
|
||||
{ id: "adresseSaveAnsprechpartner", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/SaveAnsprechpartner" },
|
||||
{ id: "adresseSaveKontakt", capability: "address", mode: "mutation", method: "POST", path: "/api/Adresse/SaveKontakt" },
|
||||
{ id: "adresseSearch", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/Search" },
|
||||
{ id: "adresseSearchBenutzerfeldInhalt", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/SearchBenutzerfeldInhalt" },
|
||||
{ id: "adresseSearchKontakt", capability: "address", mode: "read", method: "POST", path: "/api/Adresse/SearchKontakt" },
|
||||
{ id: "archivExternalCountHeader", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/CountHeader" },
|
||||
{ id: "archivExternalDeleteEintrag", capability: "archive", mode: "mutation", method: "DELETE", path: "/api/archiv-extern/DeleteEintrag" },
|
||||
{ id: "archivExternalExportDatei", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/ExportDatei" },
|
||||
{ id: "archivExternalGetBezug", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/GetBezug" },
|
||||
{ id: "archivExternalGetSetup", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/GetSetup" },
|
||||
{ id: "archivExternalImportAdditionalDatei", capability: "archive", mode: "mutation", method: "POST", path: "/api/archiv-extern/ImportAdditionalDatei" },
|
||||
{ id: "archivExternalImportDatei", capability: "archive", mode: "mutation", method: "POST", path: "/api/archiv-extern/ImportDatei" },
|
||||
{ id: "archivExternalLoadDateienByVerzeichnisId", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/LoadDateienByVerzeichnisId" },
|
||||
{ id: "archivExternalLoadEinstellungen", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/LoadEinstellungen" },
|
||||
{ id: "archivExternalLoadEintragDetails", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/LoadEintragDetails" },
|
||||
{
|
||||
id: "archivExternalLoadLetzteRevisionArchivEintragFilesForIds",
|
||||
capability: "archive",
|
||||
mode: "read",
|
||||
method: "POST",
|
||||
path: "/api/archiv-extern/LoadLetzteRevisionArchivEintragFilesForIds",
|
||||
},
|
||||
{ id: "archivExternalLoadVerzeichnisse", capability: "archive", mode: "read", method: "GET", path: "/api/archiv-extern/LoadVerzeichnisse" },
|
||||
{
|
||||
id: "archivExternalSearchDateienByVerzeichnisId",
|
||||
capability: "archive",
|
||||
mode: "read",
|
||||
method: "GET",
|
||||
path: "/api/archiv-extern/SearchDateienByVerzeichnisId",
|
||||
},
|
||||
{ id: "archivExternalSearchVorgaenge", capability: "archive", mode: "read", method: "POST", path: "/api/archiv-extern/SearchVorgaenge" },
|
||||
{ id: "projektLoad", capability: "project", mode: "read", method: "GET", path: "/api/Projekt/Load" },
|
||||
{ id: "projektLoadKategorien", capability: "project", mode: "read", method: "GET", path: "/api/Projekt/LoadKategorien" },
|
||||
{ id: "projektLoadSachbearbeiter", capability: "project", mode: "read", method: "GET", path: "/api/Projekt/LoadSachbearbeiter" },
|
||||
{ id: "projektSave", capability: "project", mode: "mutation", method: "POST", path: "/api/Projekt/Save" },
|
||||
{ id: "projektSearch", capability: "project", mode: "read", method: "POST", path: "/api/Projekt/Search" },
|
||||
{ id: "projektampelGetSetup", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/GetSetup" },
|
||||
{ id: "projektampelLoadBenutzerDetails", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/LoadBenutzerDetails" },
|
||||
{ id: "projektampelLoadBenutzerNachFilter", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/LoadBenutzerNachFilter" },
|
||||
{ id: "projektampelLoadEinstellungen", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/LoadEinstellungen" },
|
||||
{ id: "projektampelLoadProjektDetailsGet", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/LoadProjektDetails" },
|
||||
{ id: "projektampelLoadProjektDetailsPost", capability: "project", mode: "read", method: "POST", path: "/api/Projektampel/LoadProjektDetails" },
|
||||
{ id: "projektampelLoadProjekteNachFilter", capability: "project", mode: "read", method: "GET", path: "/api/Projektampel/LoadProjekteNachFilter" },
|
||||
{
|
||||
id: "projektampelResetBenutzergruppenFilter",
|
||||
capability: "project",
|
||||
mode: "mutation",
|
||||
method: "POST",
|
||||
path: "/api/Projektampel/ResetBenutzergruppenFilter",
|
||||
},
|
||||
{ id: "projektampelResetProjektFilter", capability: "project", mode: "mutation", method: "POST", path: "/api/Projektampel/ResetProjektFilter" },
|
||||
{ id: "projektampelSaveEinstellungen", capability: "project", mode: "mutation", method: "POST", path: "/api/Projektampel/SaveEinstellungen" },
|
||||
{ id: "projektampelSearch", capability: "project", mode: "read", method: "POST", path: "/api/Projektampel/Search" },
|
||||
{ id: "vorgangAnzeigeGetSetup", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/GetSetup" },
|
||||
{ id: "vorgangAnzeigeLoadAdressen", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/LoadAdressen" },
|
||||
{ id: "vorgangAnzeigeLoadAngebote", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadAngebote" },
|
||||
{ id: "vorgangAnzeigeLoadAnzahlen", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/LoadAnzahlen" },
|
||||
{ id: "vorgangAnzeigeLoadBestellungen", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadBestellungen" },
|
||||
{ id: "vorgangAnzeigeLoadDetails", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/LoadDetails" },
|
||||
{ id: "vorgangAnzeigeLoadEingangsrechnungen", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadEingangsrechnungen" },
|
||||
{ id: "vorgangAnzeigeLoadMontageauftraege", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadMontageauftraege" },
|
||||
{ id: "vorgangAnzeigeLoadNachtraege", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadNachtraege" },
|
||||
{ id: "vorgangAnzeigeLoadPositionen", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadPositionen" },
|
||||
{ id: "vorgangAnzeigeLoadRechnungen", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadRechnungen" },
|
||||
{ id: "vorgangAnzeigeLoadRegieauftraege", capability: "project", mode: "read", method: "POST", path: "/api/VorgangAnzeige/LoadRegieauftraege" },
|
||||
{ id: "vorgangAnzeigeLoadTableMeta", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/LoadTableMeta" },
|
||||
{ id: "vorgangAnzeigeLoadVorgaenge", capability: "project", mode: "read", method: "GET", path: "/api/VorgangAnzeige/LoadVorgaenge" },
|
||||
{ id: "vorgangAnzeigeSaveTableMeta", capability: "project", mode: "mutation", method: "POST", path: "/api/VorgangAnzeige/SaveTableMeta" },
|
||||
{ id: "vorgangInfoLoadVorgangInfo", capability: "project", mode: "read", method: "GET", path: "/api/VorgangInfo/LoadVorgangInfo" },
|
||||
{ id: "monteursteuerungGetSetup", capability: "schedule", mode: "read", method: "GET", path: "/api/Monteursteuerung/GetSetup" },
|
||||
{ id: "monteursteuerungLoadTermine", capability: "schedule", mode: "read", method: "POST", path: "/api/Monteursteuerung/LoadTermine" },
|
||||
{
|
||||
id: "monteursteuerungLoadTermineProjektplanung",
|
||||
capability: "schedule",
|
||||
mode: "read",
|
||||
method: "POST",
|
||||
path: "/api/Monteursteuerung/LoadTermineProjektplanung",
|
||||
},
|
||||
{ id: "terminDeleteTermin", capability: "schedule", mode: "mutation", method: "POST", path: "/api/Termin/DeleteTermin" },
|
||||
{ id: "terminGetTeilnehmerverfuegbargeit", capability: "schedule", mode: "read", method: "POST", path: "/api/Termin/GetTeilnehmerverfuegbargeit" },
|
||||
{ id: "terminGetTerminUeberschneidungen", capability: "schedule", mode: "read", method: "POST", path: "/api/Termin/GetTerminUeberschneidungen" },
|
||||
{ id: "terminLoadEigeneTermine", capability: "schedule", mode: "read", method: "GET", path: "/api/Termin/LoadEigeneTermine" },
|
||||
{ id: "terminLoadFeiertage", capability: "schedule", mode: "read", method: "GET", path: "/api/Termin/LoadFeiertage" },
|
||||
{
|
||||
id: "terminLoadLastWartungAuftragTerminIntervall",
|
||||
capability: "schedule",
|
||||
mode: "read",
|
||||
method: "GET",
|
||||
path: "/api/Termin/LoadLastWartungAuftragTerminIntervall",
|
||||
},
|
||||
{ id: "terminLoadTerminById", capability: "schedule", mode: "read", method: "GET", path: "/api/Termin/LoadTerminById" },
|
||||
{ id: "terminLoadTermine", capability: "schedule", mode: "read", method: "GET", path: "/api/Termin/LoadTermine" },
|
||||
{ id: "terminPublishTermin", capability: "schedule", mode: "mutation", method: "POST", path: "/api/Termin/PublishTermin" },
|
||||
{ id: "terminSaveTermin", capability: "schedule", mode: "mutation", method: "POST", path: "/api/Termin/SaveTermin" },
|
||||
{ id: "terminSaveTerminAktivitaet", capability: "schedule", mode: "mutation", method: "POST", path: "/api/Termin/SaveTerminAktivitaet" },
|
||||
] as const);
|
||||
|
||||
export type KwpScopedOperation = (typeof KWP_SCOPED_OPERATIONS)[number];
|
||||
export type KwpScopedOperationId = KwpScopedOperation["id"];
|
||||
export type KwpReadOperationId = Extract<KwpScopedOperation, { readonly mode: "read" }>["id"];
|
||||
export type KwpMutationOperationId = Extract<KwpScopedOperation, { readonly mode: "mutation" }>["id"];
|
||||
export type KwpCapability = KwpScopedOperation["capability"];
|
||||
+13623
File diff suppressed because it is too large.
Load diff
+156
@@ -0,0 +1,156 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const executeKwpReadOperation = vi.fn();
|
||||
|
||||
vi.mock("./resource-client.server.js", () => ({ executeKwpReadOperation }));
|
||||
|
||||
describe("KWP inbound reader", () => {
|
||||
beforeEach(() => {
|
||||
executeKwpReadOperation.mockReset();
|
||||
});
|
||||
|
||||
it("normalizes plantafel, activity and material data without private records", async () => {
|
||||
executeKwpReadOperation.mockImplementation(async ({ operationId, operationInput }) => {
|
||||
if (operationId === "monteursteuerungLoadTermineProjektplanung") {
|
||||
return [{
|
||||
projektnummer: "P-100",
|
||||
termine: [
|
||||
{ terminId: 1, terminVon: "2026-08-01T08:00:00.000Z", terminBis: null, betreff: "Montage", beschreibung: "Vor Ort", statusId: 5, typId: 2, privat: false },
|
||||
{ terminId: 2, terminVon: "2026-08-02T08:00:00.000Z", terminBis: null, betreff: "Privat", beschreibung: null, statusId: 5, typId: 2, privat: true },
|
||||
],
|
||||
}];
|
||||
}
|
||||
if (operationId === "aktivitaetenverwaltungLoadAktivitaetenByVorgang") {
|
||||
expect(operationInput.query).toMatchObject({ vorgangNr: "P-100", vorgangArt: 0, offset: 0, count: 100 });
|
||||
return [
|
||||
{ aktivitaetenId: 10, betreff: "Rückruf", status: 200, privat: false, datumZuErledigenBis: "2026-08-03T10:00:00.000Z" },
|
||||
{ aktivitaetenId: 11, betreff: "Nicht übernehmen", status: 100, privat: true },
|
||||
];
|
||||
}
|
||||
if (operationId === "vorgangAnzeigeLoadPositionen") {
|
||||
expect(operationInput.body).toMatchObject({ art: 1, vorgangNr: "P-100", offset: 0, count: 100, mitLangtext: true });
|
||||
return [{ positionNummer: "01.01", menge: 2, text: "Ventil", einheit: "Stk", positionKennzeichen: 0, einzelpreis: 12.5, gesamtpreis: 25, langtext: "DN 20" }];
|
||||
}
|
||||
if (operationId === "archivExternalLoadVerzeichnisse") {
|
||||
return { verzeichnisId: 0, benutzerOrdner: [], standardOrdner: [], anzahlEintraege: 1 };
|
||||
}
|
||||
if (operationId === "archivExternalLoadDateienByVerzeichnisId") {
|
||||
return [{
|
||||
betreff: "Plan",
|
||||
dokumenttyp: "ZEICHNUNG",
|
||||
letzteAenderungAm: "2026-08-01T12:00:00.000Z",
|
||||
headerId: 20,
|
||||
ordnerId: 0,
|
||||
files: [{ id: 21, revisionId: 22, revision: 1, dateityp: "PDF", dateiname: "plan.pdf", link: false, sizeInByte: 123 }],
|
||||
}];
|
||||
}
|
||||
throw new Error(`unexpected ${operationId}`);
|
||||
});
|
||||
|
||||
const { loadKwpProjectInboundSnapshot } = await import("./inbound-reader.js");
|
||||
const result = await loadKwpProjectInboundSnapshot({
|
||||
connectionId: "connection_1",
|
||||
externalProjectNumber: " P-100 ",
|
||||
now: new Date("2026-07-24T00:00:00.000Z"),
|
||||
});
|
||||
|
||||
expect(result.appointments).toEqual([{
|
||||
externalId: "1",
|
||||
title: "Montage",
|
||||
description: "Vor Ort",
|
||||
startsAt: "2026-08-01T08:00:00.000Z",
|
||||
endsAt: null,
|
||||
statusId: 5,
|
||||
typeId: 2,
|
||||
}]);
|
||||
expect(result.tasks).toEqual([{
|
||||
externalId: "10",
|
||||
title: "Rückruf",
|
||||
status: "in_progress",
|
||||
deadline: "2026-08-03T10:00:00.000Z",
|
||||
completedAt: null,
|
||||
}]);
|
||||
expect(result.materialPositions[0]).toMatchObject({ externalId: "P-100:01.01", text: "Ventil", totalPrice: 25 });
|
||||
expect(executeKwpReadOperation).not.toHaveBeenCalledWith(expect.objectContaining({
|
||||
operationId: "archivExternalLoadVerzeichnisse",
|
||||
}));
|
||||
});
|
||||
|
||||
it("discovers large archive trees in resumable bounded batches", async () => {
|
||||
executeKwpReadOperation.mockImplementation(async ({ operationId, operationInput }) => {
|
||||
const folderId = operationInput.query.verzeichnisId as number;
|
||||
if (operationId === "archivExternalLoadVerzeichnisse") {
|
||||
const childFolderIds = [-2, -1, 1, 2, 3, 4];
|
||||
return {
|
||||
verzeichnisId: folderId,
|
||||
benutzerOrdner: folderId === 0
|
||||
? childFolderIds.map((id) => ({ id, bezeichnung: `Ordner ${id}`, anzahlEintraege: 1, gesperrt: false }))
|
||||
: [],
|
||||
standardOrdner: [],
|
||||
anzahlEintraege: 1,
|
||||
};
|
||||
}
|
||||
if (operationId === "archivExternalLoadDateienByVerzeichnisId") {
|
||||
return [{
|
||||
betreff: `Plan ${folderId}`,
|
||||
dokumenttyp: "ZEICHNUNG",
|
||||
letzteAenderungAm: null,
|
||||
headerId: 100 + folderId,
|
||||
ordnerId: folderId,
|
||||
files: [{ id: 200 + folderId, revisionId: 300 + folderId, revision: 1, dateityp: "PDF", dateiname: `plan-${folderId}.pdf`, link: false, sizeInByte: 123 }],
|
||||
}];
|
||||
}
|
||||
throw new Error(`unexpected ${operationId}`);
|
||||
});
|
||||
|
||||
const { loadKwpArchiveDiscoveryBatch } = await import("./inbound-reader.js");
|
||||
const first = await loadKwpArchiveDiscoveryBatch({
|
||||
connectionId: "connection_1",
|
||||
externalProjectNumber: "P-100",
|
||||
});
|
||||
expect(first).toMatchObject({ processedFolders: 5 });
|
||||
expect(first.archiveFiles).toHaveLength(5);
|
||||
expect(first.cursor).toEqual({ pendingFolderIds: [3, 4], visitedFolderIds: [0, -2, -1, 1, 2] });
|
||||
|
||||
const second = await loadKwpArchiveDiscoveryBatch({
|
||||
connectionId: "connection_1",
|
||||
externalProjectNumber: "P-100",
|
||||
cursor: first.cursor!,
|
||||
});
|
||||
expect(second).toMatchObject({ processedFolders: 2, cursor: null });
|
||||
expect(second.archiveFiles.map((file) => file.externalId)).toEqual(["103:203:303", "104:204:304"]);
|
||||
await expect(loadKwpArchiveDiscoveryBatch({
|
||||
connectionId: "connection_1",
|
||||
externalProjectNumber: "P-100",
|
||||
cursor: { pendingFolderIds: [2_147_483_648], visitedFolderIds: [] },
|
||||
})).rejects.toThrow("KWP archive cursor is invalid.");
|
||||
});
|
||||
|
||||
it("pages with stable offsets and fails closed at the bounded ceiling", async () => {
|
||||
executeKwpReadOperation.mockImplementation(async ({ operationId, operationInput }) => {
|
||||
if (operationId === "monteursteuerungLoadTermineProjektplanung") return [];
|
||||
if (operationId === "vorgangAnzeigeLoadPositionen") return [];
|
||||
if (operationId === "archivExternalLoadVerzeichnisse") return { verzeichnisId: 0, benutzerOrdner: [], standardOrdner: [], anzahlEintraege: 0 };
|
||||
if (operationId === "archivExternalLoadDateienByVerzeichnisId") return [];
|
||||
if (operationId === "aktivitaetenverwaltungLoadAktivitaetenByVorgang") {
|
||||
const offset = operationInput.query.offset as number;
|
||||
return Array.from({ length: 100 }, (_, index) => ({
|
||||
aktivitaetenId: offset + index,
|
||||
betreff: "Aktivität",
|
||||
status: 100,
|
||||
privat: false,
|
||||
}));
|
||||
}
|
||||
throw new Error(`unexpected ${operationId}`);
|
||||
});
|
||||
const { loadKwpProjectInboundSnapshot } = await import("./inbound-reader.js");
|
||||
await expect(loadKwpProjectInboundSnapshot({
|
||||
connectionId: "connection_1",
|
||||
externalProjectNumber: "P-100",
|
||||
})).rejects.toEqual(expect.objectContaining({ area: "activity" }));
|
||||
const offsets = executeKwpReadOperation.mock.calls
|
||||
.filter(([input]) => input.operationId === "aktivitaetenverwaltungLoadAktivitaetenByVorgang")
|
||||
.map(([input]) => input.operationInput.query.offset);
|
||||
expect(offsets).toEqual([0, 100, 200, 300, 400]);
|
||||
});
|
||||
});
|
||||
+431
@@ -0,0 +1,431 @@
|
||||
import { z } from "zod";
|
||||
|
||||
import { executeKwpReadOperation } from "./resource-client.server.js";
|
||||
|
||||
const PAGE_SIZE = 100;
|
||||
const MAX_PAGED_ITEMS = 500;
|
||||
const ARCHIVE_FOLDER_BATCH_SIZE = 5;
|
||||
const MAX_ARCHIVE_FOLDERS = 1_000;
|
||||
const MAX_ARCHIVE_FILE_BYTES = 100 * 1024 * 1024;
|
||||
const MIN_KWP_FOLDER_ID = -2_147_483_648;
|
||||
const MAX_KWP_FOLDER_ID = 2_147_483_647;
|
||||
const PROJECT_RESULT_KIND = 1;
|
||||
const PROJECT_ARCHIVE_REFERENCE_KIND = 1;
|
||||
|
||||
const nullableText = z.string().nullable().optional();
|
||||
const nullableDate = z.string().datetime({ offset: true }).nullable().optional();
|
||||
|
||||
const appointmentSchema = z.object({
|
||||
terminId: z.number().int(),
|
||||
terminVon: nullableDate,
|
||||
terminBis: nullableDate,
|
||||
betreff: nullableText,
|
||||
beschreibung: nullableText,
|
||||
statusId: z.number().int(),
|
||||
typId: z.number().int(),
|
||||
privat: z.boolean(),
|
||||
}).passthrough();
|
||||
|
||||
const projectScheduleSchema = z.object({
|
||||
projektnummer: nullableText,
|
||||
termine: z.array(appointmentSchema).nullable().optional(),
|
||||
}).passthrough();
|
||||
|
||||
const activitySchema = z.object({
|
||||
aktivitaetenId: z.number().int(),
|
||||
betreff: nullableText,
|
||||
datumWiedervorlage: nullableDate,
|
||||
datumZuErledigenBis: nullableDate,
|
||||
datumErledigt: nullableDate,
|
||||
status: z.union([z.literal(100), z.literal(200), z.literal(210), z.literal(300)]),
|
||||
privat: z.boolean().nullable().optional(),
|
||||
}).passthrough();
|
||||
|
||||
const materialPositionSchema = z.object({
|
||||
positionNummer: nullableText,
|
||||
menge: z.number().finite().nullable().optional(),
|
||||
text: nullableText,
|
||||
einheit: nullableText,
|
||||
positionKennzeichen: z.number().int(),
|
||||
einzelpreis: z.number().finite().nullable().optional(),
|
||||
gesamtpreis: z.number().finite().nullable().optional(),
|
||||
langtext: nullableText,
|
||||
}).passthrough();
|
||||
|
||||
const archiveFolderSchema = z.object({
|
||||
id: z.number().int(),
|
||||
bezeichnung: nullableText,
|
||||
anzahlEintraege: z.number().int(),
|
||||
gesperrt: z.boolean(),
|
||||
}).passthrough();
|
||||
|
||||
const archiveDirectorySchema = z.object({
|
||||
verzeichnisId: z.number().int(),
|
||||
benutzerOrdner: z.array(archiveFolderSchema).nullable().optional(),
|
||||
standardOrdner: z.array(archiveFolderSchema).nullable().optional(),
|
||||
anzahlEintraege: z.number().int(),
|
||||
}).passthrough();
|
||||
|
||||
const archiveEntryFileSchema = z.object({
|
||||
id: z.number().int(),
|
||||
revisionId: z.number().int(),
|
||||
revision: z.number().int(),
|
||||
dateityp: nullableText,
|
||||
dateiname: nullableText,
|
||||
link: z.boolean(),
|
||||
sizeInByte: z.number().int().nullable().optional(),
|
||||
}).passthrough();
|
||||
|
||||
const archiveEntrySchema = z.object({
|
||||
betreff: nullableText,
|
||||
dokumenttyp: nullableText,
|
||||
letzteAenderungAm: nullableDate,
|
||||
headerId: z.number().int(),
|
||||
ordnerId: z.number().int(),
|
||||
files: z.array(archiveEntryFileSchema).nullable().optional(),
|
||||
}).passthrough();
|
||||
|
||||
export type KwpInboundAppointment = {
|
||||
readonly externalId: string;
|
||||
readonly title: string;
|
||||
readonly description: string | null;
|
||||
readonly startsAt: string;
|
||||
readonly endsAt: string | null;
|
||||
readonly statusId: number;
|
||||
readonly typeId: number;
|
||||
};
|
||||
|
||||
export type KwpInboundTask = {
|
||||
readonly externalId: string;
|
||||
readonly title: string;
|
||||
readonly status: "open" | "in_progress" | "blocked" | "done";
|
||||
readonly deadline: string | null;
|
||||
readonly completedAt: string | null;
|
||||
};
|
||||
|
||||
export type KwpInboundMaterialPosition = {
|
||||
readonly externalId: string;
|
||||
readonly positionNumber: string | null;
|
||||
readonly text: string;
|
||||
readonly longText: string | null;
|
||||
readonly quantity: number | null;
|
||||
readonly unit: string | null;
|
||||
readonly unitPrice: number | null;
|
||||
readonly totalPrice: number | null;
|
||||
readonly positionMarker: number;
|
||||
};
|
||||
|
||||
export type KwpInboundArchiveFile = {
|
||||
readonly externalId: string;
|
||||
readonly headerId: number;
|
||||
readonly revisionId: number;
|
||||
readonly revision: number;
|
||||
readonly folderId: number;
|
||||
readonly displayName: string;
|
||||
readonly documentType: string | null;
|
||||
readonly providerFileType: string | null;
|
||||
readonly providerSizeBytes: number | null;
|
||||
readonly lastModifiedAt: string | null;
|
||||
};
|
||||
|
||||
export type KwpProjectInboundSnapshot = {
|
||||
readonly appointments: readonly KwpInboundAppointment[];
|
||||
readonly tasks: readonly KwpInboundTask[];
|
||||
readonly materialPositions: readonly KwpInboundMaterialPosition[];
|
||||
};
|
||||
|
||||
export type KwpInboundArea = "appointments" | "tasks" | "material";
|
||||
|
||||
export type KwpArchiveDiscoveryCursor = {
|
||||
readonly pendingFolderIds: readonly number[];
|
||||
readonly visitedFolderIds: readonly number[];
|
||||
};
|
||||
|
||||
export type KwpArchiveDiscoveryBatch = {
|
||||
readonly archiveFiles: readonly KwpInboundArchiveFile[];
|
||||
readonly processedFolders: number;
|
||||
readonly cursor: KwpArchiveDiscoveryCursor | null;
|
||||
};
|
||||
|
||||
export class KwpInboundLimitError extends Error {
|
||||
constructor(readonly area: "activity" | "archive" | "material") {
|
||||
super(`KWP inbound ${area} result exceeded the bounded import window.`);
|
||||
this.name = "KwpInboundLimitError";
|
||||
}
|
||||
}
|
||||
|
||||
export async function loadKwpProjectInboundSnapshot(input: {
|
||||
readonly connectionId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpProjectInboundSnapshot> {
|
||||
const projectNumber = normalizeProjectNumber(input.externalProjectNumber);
|
||||
const now = input.now ?? new Date();
|
||||
const [appointments, tasks, materialPositions] = await Promise.all([
|
||||
loadAppointments(input.connectionId, projectNumber, now),
|
||||
loadTasks(input.connectionId, projectNumber),
|
||||
loadMaterialPositions(input.connectionId, projectNumber),
|
||||
]);
|
||||
return { appointments, tasks, materialPositions };
|
||||
}
|
||||
|
||||
export async function loadKwpProjectInboundArea(input: {
|
||||
readonly area: KwpInboundArea;
|
||||
readonly connectionId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpProjectInboundSnapshot> {
|
||||
const projectNumber = normalizeProjectNumber(input.externalProjectNumber);
|
||||
const empty = { appointments: [], tasks: [], materialPositions: [] } satisfies KwpProjectInboundSnapshot;
|
||||
if (input.area === "appointments") {
|
||||
return { ...empty, appointments: await loadAppointments(input.connectionId, projectNumber, input.now ?? new Date()) };
|
||||
}
|
||||
if (input.area === "tasks") {
|
||||
return { ...empty, tasks: await loadTasks(input.connectionId, projectNumber) };
|
||||
}
|
||||
return { ...empty, materialPositions: await loadMaterialPositions(input.connectionId, projectNumber) };
|
||||
}
|
||||
|
||||
export async function loadKwpArchiveDiscoveryBatch(input: {
|
||||
readonly connectionId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
readonly cursor?: KwpArchiveDiscoveryCursor;
|
||||
}): Promise<KwpArchiveDiscoveryBatch> {
|
||||
const projectNumber = normalizeProjectNumber(input.externalProjectNumber);
|
||||
const cursor = normalizeArchiveCursor(input.cursor);
|
||||
const pending = [...cursor.pendingFolderIds];
|
||||
const visited = new Set(cursor.visitedFolderIds);
|
||||
const files: KwpInboundArchiveFile[] = [];
|
||||
let processedFolders = 0;
|
||||
|
||||
while (pending.length > 0 && processedFolders < ARCHIVE_FOLDER_BATCH_SIZE) {
|
||||
const folderId = pending.shift()!;
|
||||
if (visited.has(folderId)) continue;
|
||||
if (visited.size >= MAX_ARCHIVE_FOLDERS) throw new KwpInboundLimitError("archive");
|
||||
visited.add(folderId);
|
||||
processedFolders += 1;
|
||||
const directory = archiveDirectorySchema.parse(await executeKwpReadOperation({
|
||||
connectionId: input.connectionId,
|
||||
operationId: "archivExternalLoadVerzeichnisse",
|
||||
operationInput: {
|
||||
query: {
|
||||
bezugsart: PROJECT_ARCHIVE_REFERENCE_KIND,
|
||||
bezugsnummer: projectNumber,
|
||||
verzeichnisId: folderId,
|
||||
},
|
||||
},
|
||||
}));
|
||||
for (const folder of [...(directory.benutzerOrdner ?? []), ...(directory.standardOrdner ?? [])]) {
|
||||
if (!folder.gesperrt && !visited.has(folder.id) && !pending.includes(folder.id)) pending.push(folder.id);
|
||||
}
|
||||
if (new Set([...visited, ...pending]).size > MAX_ARCHIVE_FOLDERS) throw new KwpInboundLimitError("archive");
|
||||
const entries = await loadPaged("archive", async (offset) => {
|
||||
const response = await executeKwpReadOperation({
|
||||
connectionId: input.connectionId,
|
||||
operationId: "archivExternalLoadDateienByVerzeichnisId",
|
||||
operationInput: {
|
||||
query: {
|
||||
bezugsart: PROJECT_ARCHIVE_REFERENCE_KIND,
|
||||
bezugsnummer: projectNumber,
|
||||
verzeichnisId: folderId,
|
||||
offset,
|
||||
count: PAGE_SIZE,
|
||||
},
|
||||
},
|
||||
});
|
||||
return z.array(archiveEntrySchema).parse(response);
|
||||
});
|
||||
files.push(...mapArchiveFiles(entries));
|
||||
}
|
||||
|
||||
return {
|
||||
archiveFiles: deduplicateByExternalId(files),
|
||||
processedFolders,
|
||||
cursor: pending.length > 0
|
||||
? { pendingFolderIds: pending, visitedFolderIds: [...visited] }
|
||||
: null,
|
||||
};
|
||||
}
|
||||
|
||||
async function loadAppointments(connectionId: string, projectNumber: string, now: Date): Promise<KwpInboundAppointment[]> {
|
||||
const from = new Date(now);
|
||||
from.setUTCMonth(from.getUTCMonth() - 3);
|
||||
const until = new Date(now);
|
||||
until.setUTCFullYear(until.getUTCFullYear() + 1);
|
||||
const response = await executeKwpReadOperation({
|
||||
connectionId,
|
||||
operationId: "monteursteuerungLoadTermineProjektplanung",
|
||||
operationInput: {
|
||||
body: {
|
||||
von: from.toISOString(),
|
||||
bis: until.toISOString(),
|
||||
nurProjekteMitTerminen: true,
|
||||
maxAnzahlProjekte: 1_000,
|
||||
},
|
||||
},
|
||||
});
|
||||
const projects = z.array(projectScheduleSchema).parse(response);
|
||||
const project = projects.find((entry) => entry.projektnummer?.trim() === projectNumber);
|
||||
return (project?.termine ?? [])
|
||||
.filter((entry) => entry.privat !== true && Boolean(entry.terminVon))
|
||||
.map((entry) => ({
|
||||
externalId: String(entry.terminId),
|
||||
title: normalizeText(entry.betreff, `KWP-Termin ${entry.terminId}`),
|
||||
description: normalizeOptionalText(entry.beschreibung),
|
||||
startsAt: entry.terminVon!,
|
||||
endsAt: entry.terminBis ?? null,
|
||||
statusId: entry.statusId,
|
||||
typeId: entry.typId,
|
||||
}));
|
||||
}
|
||||
|
||||
async function loadTasks(connectionId: string, projectNumber: string): Promise<KwpInboundTask[]> {
|
||||
const rows = await loadPaged("activity", async (offset) => {
|
||||
const response = await executeKwpReadOperation({
|
||||
connectionId,
|
||||
operationId: "aktivitaetenverwaltungLoadAktivitaetenByVorgang",
|
||||
operationInput: {
|
||||
query: {
|
||||
vorgangNr: projectNumber,
|
||||
vorgangArt: 0,
|
||||
offset,
|
||||
count: PAGE_SIZE,
|
||||
filterTyp: 0,
|
||||
},
|
||||
},
|
||||
});
|
||||
return z.array(activitySchema).parse(response);
|
||||
});
|
||||
return rows
|
||||
.filter((entry) => entry.privat !== true)
|
||||
.map((entry) => ({
|
||||
externalId: String(entry.aktivitaetenId),
|
||||
title: normalizeText(entry.betreff, `KWP-Aktivität ${entry.aktivitaetenId}`),
|
||||
status: mapActivityStatus(entry.status),
|
||||
deadline: entry.datumZuErledigenBis ?? entry.datumWiedervorlage ?? null,
|
||||
completedAt: entry.status === 300 ? (entry.datumErledigt ?? null) : null,
|
||||
}));
|
||||
}
|
||||
|
||||
async function loadMaterialPositions(connectionId: string, projectNumber: string): Promise<KwpInboundMaterialPosition[]> {
|
||||
const rows = await loadPaged("material", async (offset) => {
|
||||
const response = await executeKwpReadOperation({
|
||||
connectionId,
|
||||
operationId: "vorgangAnzeigeLoadPositionen",
|
||||
operationInput: {
|
||||
body: {
|
||||
art: PROJECT_RESULT_KIND,
|
||||
vorgangNr: projectNumber,
|
||||
count: PAGE_SIZE,
|
||||
offset,
|
||||
mitLangtext: true,
|
||||
},
|
||||
},
|
||||
});
|
||||
return z.array(materialPositionSchema).parse(response);
|
||||
});
|
||||
return rows.map((entry, index) => {
|
||||
const positionNumber = normalizeOptionalText(entry.positionNummer);
|
||||
const stablePart = positionNumber ?? `unnummeriert-${index + 1}`;
|
||||
return {
|
||||
externalId: `${projectNumber}:${stablePart}`,
|
||||
positionNumber,
|
||||
text: normalizeText(entry.text, `KWP-Position ${stablePart}`),
|
||||
longText: normalizeOptionalText(entry.langtext),
|
||||
quantity: entry.menge ?? null,
|
||||
unit: normalizeOptionalText(entry.einheit),
|
||||
unitPrice: entry.einzelpreis ?? null,
|
||||
totalPrice: entry.gesamtpreis ?? null,
|
||||
positionMarker: entry.positionKennzeichen,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
function mapArchiveFiles(entries: readonly z.infer<typeof archiveEntrySchema>[]): KwpInboundArchiveFile[] {
|
||||
const files: KwpInboundArchiveFile[] = [];
|
||||
for (const entry of entries) {
|
||||
for (const file of entry.files ?? []) {
|
||||
if (file.link || (file.sizeInByte ?? 0) > MAX_ARCHIVE_FILE_BYTES) continue;
|
||||
files.push({
|
||||
externalId: `${entry.headerId}:${file.id}:${file.revisionId}`,
|
||||
headerId: entry.headerId,
|
||||
revisionId: file.revisionId,
|
||||
revision: file.revision,
|
||||
folderId: entry.ordnerId,
|
||||
displayName: normalizeText(file.dateiname, normalizeText(entry.betreff, `KWP-Datei ${file.id}`)),
|
||||
documentType: normalizeOptionalText(entry.dokumenttyp),
|
||||
providerFileType: normalizeOptionalText(file.dateityp),
|
||||
providerSizeBytes: file.sizeInByte ?? null,
|
||||
lastModifiedAt: entry.letzteAenderungAm ?? null,
|
||||
});
|
||||
}
|
||||
}
|
||||
return files;
|
||||
}
|
||||
|
||||
function normalizeArchiveCursor(cursor: KwpArchiveDiscoveryCursor | undefined): KwpArchiveDiscoveryCursor {
|
||||
if (!cursor) return { pendingFolderIds: [0], visitedFolderIds: [] };
|
||||
const pendingFolderIds = normalizeFolderIds(cursor.pendingFolderIds);
|
||||
const visitedFolderIds = normalizeFolderIds(cursor.visitedFolderIds);
|
||||
if (pendingFolderIds.length === 0 || pendingFolderIds.length + visitedFolderIds.length > MAX_ARCHIVE_FOLDERS) {
|
||||
throw new KwpInboundLimitError("archive");
|
||||
}
|
||||
return { pendingFolderIds, visitedFolderIds };
|
||||
}
|
||||
|
||||
function normalizeFolderIds(values: readonly number[]): number[] {
|
||||
if (
|
||||
!Array.isArray(values)
|
||||
|| values.some((value) => !Number.isInteger(value) || value < MIN_KWP_FOLDER_ID || value > MAX_KWP_FOLDER_ID)
|
||||
) {
|
||||
throw new Error("KWP archive cursor is invalid.");
|
||||
}
|
||||
return [...new Set(values)];
|
||||
}
|
||||
|
||||
async function loadPaged<Row>(
|
||||
area: "activity" | "archive" | "material",
|
||||
loadPage: (offset: number) => Promise<readonly Row[]>,
|
||||
): Promise<Row[]> {
|
||||
const rows: Row[] = [];
|
||||
while (rows.length < MAX_PAGED_ITEMS) {
|
||||
const page = await loadPage(rows.length);
|
||||
rows.push(...page);
|
||||
if (page.length < PAGE_SIZE) return rows;
|
||||
}
|
||||
throw new KwpInboundLimitError(area);
|
||||
}
|
||||
|
||||
function mapActivityStatus(status: 100 | 200 | 210 | 300): KwpInboundTask["status"] {
|
||||
if (status === 200) return "in_progress";
|
||||
if (status === 210) return "blocked";
|
||||
if (status === 300) return "done";
|
||||
return "open";
|
||||
}
|
||||
|
||||
function normalizeProjectNumber(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!normalized || normalized.length > 191) throw new Error("KWP project number is invalid.");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeText(value: string | null | undefined, fallback: string): string {
|
||||
return normalizeOptionalText(value) ?? fallback;
|
||||
}
|
||||
|
||||
function normalizeOptionalText(value: string | null | undefined): string | null {
|
||||
const normalized = value?.trim();
|
||||
return normalized ? normalized.slice(0, 2_000) : null;
|
||||
}
|
||||
|
||||
function deduplicateByExternalId<Row extends { readonly externalId: string }>(rows: readonly Row[]): Row[] {
|
||||
return [...new Map(rows.map((row) => [row.externalId, row])).values()];
|
||||
}
|
||||
|
||||
export const KWP_INBOUND_BOUNDS = Object.freeze({
|
||||
archiveFolderBatchSize: ARCHIVE_FOLDER_BATCH_SIZE,
|
||||
maxArchiveFileBytes: MAX_ARCHIVE_FILE_BYTES,
|
||||
maxArchiveFolders: MAX_ARCHIVE_FOLDERS,
|
||||
maxPagedItems: MAX_PAGED_ITEMS,
|
||||
pageSize: PAGE_SIZE,
|
||||
});
|
||||
+601
@@ -0,0 +1,601 @@
|
||||
import { logActivity } from "@hivegrid/activity";
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import type { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
import { auditEvent } from "@hivegrid/foundation";
|
||||
|
||||
import {
|
||||
type KwpInboundAppointment,
|
||||
type KwpInboundArea,
|
||||
type KwpInboundMaterialPosition,
|
||||
type KwpInboundTask,
|
||||
type KwpProjectInboundSnapshot,
|
||||
loadKwpProjectInboundArea,
|
||||
} from "./inbound-reader.js";
|
||||
import { KwpProjectDomainError } from "./project-domain.server.js";
|
||||
import { fingerprintKwpSnapshot } from "./resource-client.js";
|
||||
|
||||
const APPOINTMENT_ENTITY_TYPE = "kwp_appointment";
|
||||
const TASK_ENTITY_TYPE = "kwp_activity";
|
||||
const MATERIAL_ENTITY_TYPE = "kwp_material_position";
|
||||
|
||||
type InboundBinding = {
|
||||
readonly id: string;
|
||||
readonly externalEntityType: string;
|
||||
readonly externalId: string;
|
||||
readonly localId: string;
|
||||
readonly fingerprint: string;
|
||||
readonly revision: number;
|
||||
};
|
||||
|
||||
type PreparedInboundSync = {
|
||||
readonly tenantId: string;
|
||||
readonly runId: string;
|
||||
readonly connectionId: string;
|
||||
readonly projectId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
readonly actorUserId: string;
|
||||
readonly bindings: readonly InboundBinding[];
|
||||
};
|
||||
|
||||
export type KwpInboundSyncResult = {
|
||||
readonly runId: string;
|
||||
readonly projectId: string;
|
||||
readonly appointments: number;
|
||||
readonly tasks: number;
|
||||
readonly materialPositions: number;
|
||||
readonly failedAreas: readonly KwpInboundArea[];
|
||||
readonly changed: boolean;
|
||||
};
|
||||
|
||||
const INBOUND_AREAS = ["appointments", "tasks", "material"] as const satisfies readonly KwpInboundArea[];
|
||||
|
||||
export async function syncKwpProjectInbound(input: {
|
||||
readonly bindingId: string;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpInboundSyncResult> {
|
||||
const now = input.now ?? new Date();
|
||||
const prepared = await prepareInboundSync(normalizeId(input.bindingId), now);
|
||||
try {
|
||||
const reads = await Promise.allSettled(INBOUND_AREAS.map(async (area) => ({
|
||||
area,
|
||||
snapshot: await loadKwpProjectInboundArea({
|
||||
area,
|
||||
connectionId: prepared.connectionId,
|
||||
externalProjectNumber: prepared.externalProjectNumber,
|
||||
now,
|
||||
}),
|
||||
})));
|
||||
const successful = reads.flatMap((read) => read.status === "fulfilled" ? [read.value] : []);
|
||||
if (successful.length === 0) {
|
||||
const failure = reads.find((read) => read.status === "rejected");
|
||||
throw failure?.status === "rejected" ? failure.reason : new Error("KWP inbound reads failed.");
|
||||
}
|
||||
const failedAreas = INBOUND_AREAS.filter((_, index) => reads[index]?.status === "rejected");
|
||||
const snapshot: KwpProjectInboundSnapshot = {
|
||||
appointments: successful.flatMap(({ snapshot: areaSnapshot }) => areaSnapshot.appointments),
|
||||
tasks: successful.flatMap(({ snapshot: areaSnapshot }) => areaSnapshot.tasks),
|
||||
materialPositions: successful.flatMap(({ snapshot: areaSnapshot }) => areaSnapshot.materialPositions),
|
||||
};
|
||||
const result = await applyInboundSnapshot(prepared, snapshot, new Set(successful.map(({ area }) => area)), failedAreas, now);
|
||||
await finishInboundRun(prepared, result, now);
|
||||
return result;
|
||||
} catch (error) {
|
||||
await failInboundRun(prepared, now);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function prepareInboundSync(bindingId: string, now: Date): Promise<PreparedInboundSync> {
|
||||
const tenantId = requireTenantContext();
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findFirst({
|
||||
where: {
|
||||
id: bindingId,
|
||||
tenantId,
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
state: "active",
|
||||
},
|
||||
select: { dataConnectionId: true, externalId: true, localId: true },
|
||||
});
|
||||
if (!binding) throw new KwpProjectDomainError("project_not_found");
|
||||
const [project, connection, bindings] = await Promise.all([
|
||||
tx.projekt.findFirst({
|
||||
where: { id: binding.localId, tenantId, archivedAt: null },
|
||||
select: { id: true, createdByUserId: true },
|
||||
}),
|
||||
tx.dataConnection.findFirst({
|
||||
where: {
|
||||
id: binding.dataConnectionId,
|
||||
tenantId,
|
||||
appId: "kwp",
|
||||
archivedAt: null,
|
||||
connectionStatus: { in: ["active", "degraded"] },
|
||||
},
|
||||
select: { createdByUserId: true },
|
||||
}),
|
||||
tx.appEntityBinding.findMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
externalEntityType: { in: [APPOINTMENT_ENTITY_TYPE, TASK_ENTITY_TYPE, MATERIAL_ENTITY_TYPE] },
|
||||
normalizedSnapshot: { path: ["projectId"], equals: binding.localId },
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
select: {
|
||||
id: true,
|
||||
externalEntityType: true,
|
||||
externalId: true,
|
||||
localId: true,
|
||||
fingerprint: true,
|
||||
revision: true,
|
||||
},
|
||||
}),
|
||||
]);
|
||||
if (!project || !connection) throw new KwpProjectDomainError("project_not_found");
|
||||
const actorUserId = await resolveActorUserId(tx, tenantId, connection.createdByUserId ?? project.createdByUserId);
|
||||
if (!actorUserId) throw new KwpProjectDomainError("project_not_found");
|
||||
const run = await tx.appSyncRun.create({
|
||||
data: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
kind: "scheduled",
|
||||
status: "running",
|
||||
summaryText: "integrations.sync.summary.kwpInboundSyncStarted",
|
||||
startedAt: now,
|
||||
},
|
||||
});
|
||||
return {
|
||||
tenantId,
|
||||
runId: run.id,
|
||||
connectionId: binding.dataConnectionId,
|
||||
projectId: project.id,
|
||||
externalProjectNumber: binding.externalId,
|
||||
actorUserId,
|
||||
bindings,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function applyInboundSnapshot(
|
||||
prepared: PreparedInboundSync,
|
||||
snapshot: KwpProjectInboundSnapshot,
|
||||
successfulAreas: ReadonlySet<KwpInboundArea>,
|
||||
failedAreas: readonly KwpInboundArea[],
|
||||
now: Date,
|
||||
): Promise<KwpInboundSyncResult> {
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const bindings = new Map(prepared.bindings.map((binding) => [bindingKey(binding.externalEntityType, binding.externalId), binding]));
|
||||
const seen = new Set<string>();
|
||||
let changed = false;
|
||||
for (const appointment of snapshot.appointments) {
|
||||
const result = await reconcileAppointment(tx, prepared, bindings.get(bindingKey(APPOINTMENT_ENTITY_TYPE, appointment.externalId)), appointment, now);
|
||||
seen.add(bindingKey(APPOINTMENT_ENTITY_TYPE, appointment.externalId));
|
||||
changed ||= result;
|
||||
}
|
||||
for (const task of snapshot.tasks) {
|
||||
const result = await reconcileTask(tx, prepared, bindings.get(bindingKey(TASK_ENTITY_TYPE, task.externalId)), task, now);
|
||||
seen.add(bindingKey(TASK_ENTITY_TYPE, task.externalId));
|
||||
changed ||= result;
|
||||
}
|
||||
for (const position of snapshot.materialPositions) {
|
||||
const result = await reconcileMaterialPosition(tx, prepared, bindings.get(bindingKey(MATERIAL_ENTITY_TYPE, position.externalId)), position, now);
|
||||
seen.add(bindingKey(MATERIAL_ENTITY_TYPE, position.externalId));
|
||||
changed ||= result;
|
||||
}
|
||||
for (const binding of prepared.bindings) {
|
||||
if (!successfulAreas.has(areaForEntityType(binding.externalEntityType))) continue;
|
||||
if (seen.has(bindingKey(binding.externalEntityType, binding.externalId))) continue;
|
||||
const updated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision, state: { in: ["active", "missing"] } },
|
||||
data: {
|
||||
state: "missing",
|
||||
revision: { increment: 1 },
|
||||
missingSince: now,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
await recordSyncItem(tx, prepared, binding.externalEntityType, binding.localId, binding.externalId, "skipped", "KWP-Datensatz wurde im aktuellen Abruffenster nicht gefunden.");
|
||||
changed = true;
|
||||
}
|
||||
if (changed) {
|
||||
await auditEvent({
|
||||
tenantId: prepared.tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_PROJECT_INBOUND_RECONCILED",
|
||||
targetType: "project",
|
||||
targetId: prepared.projectId,
|
||||
metadata: {
|
||||
source: "kwp",
|
||||
appointments: snapshot.appointments.length,
|
||||
tasks: snapshot.tasks.length,
|
||||
materialPositions: snapshot.materialPositions.length,
|
||||
},
|
||||
}, tx as never);
|
||||
await logActivity({
|
||||
tenantId: prepared.tenantId,
|
||||
actorKind: "system",
|
||||
activityType: "project_updated",
|
||||
subjectType: "project",
|
||||
subjectId: prepared.projectId,
|
||||
summaryText: "activity.runtime.kwp.inboundDataUpdated",
|
||||
metadata: { source: "kwp" },
|
||||
}, { client: tx });
|
||||
}
|
||||
return {
|
||||
runId: prepared.runId,
|
||||
projectId: prepared.projectId,
|
||||
appointments: snapshot.appointments.length,
|
||||
tasks: snapshot.tasks.length,
|
||||
materialPositions: snapshot.materialPositions.length,
|
||||
failedAreas,
|
||||
changed,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function reconcileAppointment(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
binding: InboundBinding | undefined,
|
||||
appointment: KwpInboundAppointment,
|
||||
now: Date,
|
||||
): Promise<boolean> {
|
||||
const normalizedSnapshot = { projectId: prepared.projectId, ...appointment };
|
||||
const fingerprint = fingerprintKwpSnapshot(normalizedSnapshot);
|
||||
if (!binding) {
|
||||
const local = await tx.projektTermin.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
projektId: prepared.projectId,
|
||||
createdByUserId: prepared.actorUserId,
|
||||
titel: appointment.title,
|
||||
beschreibung: appointment.description,
|
||||
startAt: new Date(appointment.startsAt),
|
||||
endAt: appointment.endsAt ? new Date(appointment.endsAt) : null,
|
||||
status: "geplant",
|
||||
},
|
||||
});
|
||||
await createBinding(tx, prepared, APPOINTMENT_ENTITY_TYPE, "project_appointment", appointment.externalId, local.id, normalizedSnapshot, fingerprint, now);
|
||||
await recordSyncItem(tx, prepared, APPOINTMENT_ENTITY_TYPE, local.id, appointment.externalId, "created");
|
||||
return true;
|
||||
}
|
||||
if (binding.fingerprint === fingerprint) {
|
||||
await touchBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, now);
|
||||
await recordSyncItem(tx, prepared, APPOINTMENT_ENTITY_TYPE, binding.localId, appointment.externalId, "skipped");
|
||||
return false;
|
||||
}
|
||||
const local = await tx.projektTermin.findFirst({ where: { id: binding.localId, tenantId: prepared.tenantId, projektId: prepared.projectId } });
|
||||
if (!local) throw new KwpProjectDomainError("project_not_found");
|
||||
await tx.projektTermin.update({
|
||||
where: { id: local.id },
|
||||
data: {
|
||||
titel: appointment.title,
|
||||
beschreibung: appointment.description,
|
||||
startAt: new Date(appointment.startsAt),
|
||||
endAt: appointment.endsAt ? new Date(appointment.endsAt) : null,
|
||||
archivedAt: null,
|
||||
},
|
||||
});
|
||||
await updateBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, {
|
||||
title: local.titel,
|
||||
description: local.beschreibung,
|
||||
startsAt: local.startAt.toISOString(),
|
||||
endsAt: local.endAt?.toISOString() ?? null,
|
||||
}, now);
|
||||
await recordSyncItem(tx, prepared, APPOINTMENT_ENTITY_TYPE, local.id, appointment.externalId, "updated");
|
||||
return true;
|
||||
}
|
||||
|
||||
async function reconcileTask(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
binding: InboundBinding | undefined,
|
||||
task: KwpInboundTask,
|
||||
now: Date,
|
||||
): Promise<boolean> {
|
||||
const normalizedSnapshot = { projectId: prepared.projectId, ...task };
|
||||
const fingerprint = fingerprintKwpSnapshot(normalizedSnapshot);
|
||||
if (!binding) {
|
||||
const local = await tx.task.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
createdByUserId: prepared.actorUserId,
|
||||
assignedToUserId: prepared.actorUserId,
|
||||
title: task.title,
|
||||
status: task.status,
|
||||
priority: "normal",
|
||||
deadline: task.deadline ? new Date(task.deadline) : null,
|
||||
linkedEntityType: "project",
|
||||
linkedEntityId: prepared.projectId,
|
||||
source: "api",
|
||||
sourceRef: `kwp:${prepared.connectionId}:${task.externalId}`,
|
||||
completedAt: task.completedAt ? new Date(task.completedAt) : null,
|
||||
},
|
||||
});
|
||||
await createBinding(tx, prepared, TASK_ENTITY_TYPE, "task", task.externalId, local.id, normalizedSnapshot, fingerprint, now);
|
||||
await recordSyncItem(tx, prepared, TASK_ENTITY_TYPE, local.id, task.externalId, "created");
|
||||
return true;
|
||||
}
|
||||
if (binding.fingerprint === fingerprint) {
|
||||
await touchBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, now);
|
||||
await recordSyncItem(tx, prepared, TASK_ENTITY_TYPE, binding.localId, task.externalId, "skipped");
|
||||
return false;
|
||||
}
|
||||
const local = await tx.task.findFirst({ where: { id: binding.localId, tenantId: prepared.tenantId, linkedEntityType: "project", linkedEntityId: prepared.projectId } });
|
||||
if (!local) throw new KwpProjectDomainError("project_not_found");
|
||||
await tx.task.update({
|
||||
where: { id: local.id },
|
||||
data: {
|
||||
title: task.title,
|
||||
status: task.status,
|
||||
deadline: task.deadline ? new Date(task.deadline) : null,
|
||||
completedAt: task.completedAt ? new Date(task.completedAt) : null,
|
||||
archivedAt: null,
|
||||
},
|
||||
});
|
||||
await updateBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, {
|
||||
title: local.title,
|
||||
status: local.status,
|
||||
deadline: local.deadline?.toISOString() ?? null,
|
||||
completedAt: local.completedAt?.toISOString() ?? null,
|
||||
}, now);
|
||||
await recordSyncItem(tx, prepared, TASK_ENTITY_TYPE, local.id, task.externalId, "updated");
|
||||
return true;
|
||||
}
|
||||
|
||||
async function reconcileMaterialPosition(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
binding: InboundBinding | undefined,
|
||||
position: KwpInboundMaterialPosition,
|
||||
now: Date,
|
||||
): Promise<boolean> {
|
||||
const normalizedSnapshot = { projectId: prepared.projectId, ...position };
|
||||
const fingerprint = fingerprintKwpSnapshot(normalizedSnapshot);
|
||||
if (!binding) {
|
||||
const local = await tx.kwpMaterialPosition.create({
|
||||
data: materialData(prepared, position, fingerprint, now),
|
||||
});
|
||||
await createBinding(tx, prepared, MATERIAL_ENTITY_TYPE, MATERIAL_ENTITY_TYPE, position.externalId, local.id, normalizedSnapshot, fingerprint, now);
|
||||
await recordSyncItem(tx, prepared, MATERIAL_ENTITY_TYPE, local.id, position.externalId, "created");
|
||||
return true;
|
||||
}
|
||||
if (binding.fingerprint === fingerprint) {
|
||||
await touchBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, now);
|
||||
await tx.kwpMaterialPosition.updateMany({
|
||||
where: { id: binding.localId, tenantId: prepared.tenantId, projektId: prepared.projectId },
|
||||
data: { lastSeenAt: now, lastSyncedAt: now, archivedAt: null },
|
||||
});
|
||||
await recordSyncItem(tx, prepared, MATERIAL_ENTITY_TYPE, binding.localId, position.externalId, "skipped");
|
||||
return false;
|
||||
}
|
||||
const local = await tx.kwpMaterialPosition.findFirst({
|
||||
where: { id: binding.localId, tenantId: prepared.tenantId, projektId: prepared.projectId },
|
||||
});
|
||||
if (!local) throw new KwpProjectDomainError("project_not_found");
|
||||
await tx.kwpMaterialPosition.update({
|
||||
where: { id: local.id },
|
||||
data: materialData(prepared, position, fingerprint, now),
|
||||
});
|
||||
await updateBinding(tx, prepared, binding, normalizedSnapshot, fingerprint, {
|
||||
positionNumber: local.positionNumber,
|
||||
text: local.text,
|
||||
longText: local.longText,
|
||||
quantity: decimalText(local.quantity),
|
||||
unit: local.unit,
|
||||
unitPrice: decimalText(local.unitPrice),
|
||||
totalPrice: decimalText(local.totalPrice),
|
||||
positionMarker: local.positionMarker,
|
||||
}, now);
|
||||
await recordSyncItem(tx, prepared, MATERIAL_ENTITY_TYPE, local.id, position.externalId, "updated");
|
||||
return true;
|
||||
}
|
||||
|
||||
function materialData(
|
||||
prepared: PreparedInboundSync,
|
||||
position: KwpInboundMaterialPosition,
|
||||
fingerprint: string,
|
||||
now: Date,
|
||||
) {
|
||||
return {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
projektId: prepared.projectId,
|
||||
externalId: position.externalId,
|
||||
positionNumber: position.positionNumber,
|
||||
text: position.text,
|
||||
longText: position.longText,
|
||||
quantity: position.quantity,
|
||||
unit: position.unit,
|
||||
unitPrice: position.unitPrice,
|
||||
totalPrice: position.totalPrice,
|
||||
positionMarker: position.positionMarker,
|
||||
normalizedFingerprint: fingerprint,
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
archivedAt: null,
|
||||
};
|
||||
}
|
||||
|
||||
async function createBinding(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
externalEntityType: string,
|
||||
localEntityType: string,
|
||||
externalId: string,
|
||||
localId: string,
|
||||
normalizedSnapshot: Record<string, unknown>,
|
||||
fingerprint: string,
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
await tx.appEntityBinding.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
externalEntityType,
|
||||
localEntityType,
|
||||
externalId,
|
||||
localId,
|
||||
state: "active",
|
||||
normalizedSnapshot: normalizedSnapshot as Prisma.InputJsonValue,
|
||||
fingerprint,
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async function touchBinding(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
binding: InboundBinding,
|
||||
normalizedSnapshot: Record<string, unknown>,
|
||||
fingerprint: string,
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
const updated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision, state: { in: ["active", "missing"] } },
|
||||
data: {
|
||||
state: "active",
|
||||
normalizedSnapshot: normalizedSnapshot as Prisma.InputJsonValue,
|
||||
fingerprint,
|
||||
revision: { increment: 1 },
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
missingSince: null,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
}
|
||||
|
||||
async function updateBinding(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
binding: InboundBinding,
|
||||
normalizedSnapshot: Record<string, unknown>,
|
||||
fingerprint: string,
|
||||
overwrittenLocalSnapshot: Record<string, unknown>,
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
const updated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision, state: { in: ["active", "missing"] } },
|
||||
data: {
|
||||
state: "active",
|
||||
normalizedSnapshot: normalizedSnapshot as Prisma.InputJsonValue,
|
||||
fingerprint,
|
||||
overwrittenLocalSnapshot: overwrittenLocalSnapshot as Prisma.InputJsonValue,
|
||||
revision: { increment: 1 },
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
missingSince: null,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
}
|
||||
|
||||
async function recordSyncItem(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedInboundSync,
|
||||
entityType: string,
|
||||
entityId: string,
|
||||
externalId: string,
|
||||
operation: "created" | "updated" | "skipped",
|
||||
errorText?: string,
|
||||
): Promise<void> {
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType,
|
||||
entityId,
|
||||
externalId,
|
||||
operation,
|
||||
status: errorText || operation === "skipped" ? "skipped" : "synced",
|
||||
errorText,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async function resolveActorUserId(
|
||||
tx: Prisma.TransactionClient,
|
||||
tenantId: string,
|
||||
preferredUserId: string | null | undefined,
|
||||
): Promise<string | null> {
|
||||
if (preferredUserId) {
|
||||
const membership = await tx.tenantUser.findFirst({
|
||||
where: { tenantId, userId: preferredUserId },
|
||||
select: { userId: true },
|
||||
});
|
||||
if (membership) return membership.userId;
|
||||
}
|
||||
const fallback = await tx.tenantUser.findFirst({
|
||||
where: { tenantId },
|
||||
select: { userId: true },
|
||||
orderBy: { createdAt: "asc" },
|
||||
});
|
||||
return fallback?.userId ?? null;
|
||||
}
|
||||
|
||||
async function finishInboundRun(
|
||||
prepared: PreparedInboundSync,
|
||||
result: KwpInboundSyncResult,
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
const itemsTotal = result.appointments + result.tasks + result.materialPositions;
|
||||
const successfulAreaCount = INBOUND_AREAS.length - result.failedAreas.length;
|
||||
await getDbClient().appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: result.failedAreas.length > 0 ? "partial" : "completed",
|
||||
itemsTotal: itemsTotal + INBOUND_AREAS.length,
|
||||
itemsSucceeded: itemsTotal + successfulAreaCount,
|
||||
itemsFailed: result.failedAreas.length,
|
||||
summaryText: result.failedAreas.length > 0
|
||||
? "integrations.sync.summary.kwpInboundPartial"
|
||||
: result.changed
|
||||
? "integrations.sync.summary.kwpInboundUpdated"
|
||||
: "integrations.sync.summary.kwpInboundUnchanged",
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function areaForEntityType(entityType: string): KwpInboundArea {
|
||||
if (entityType === APPOINTMENT_ENTITY_TYPE) return "appointments";
|
||||
if (entityType === TASK_ENTITY_TYPE) return "tasks";
|
||||
return "material";
|
||||
}
|
||||
|
||||
async function failInboundRun(prepared: PreparedInboundSync, now: Date): Promise<void> {
|
||||
await getDbClient().appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: "failed",
|
||||
itemsFailed: 1,
|
||||
summaryText: "integrations.sync.summary.kwpInboundFailed",
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function decimalText(value: unknown): string | null {
|
||||
return value === null || value === undefined ? null : String(value);
|
||||
}
|
||||
|
||||
function bindingKey(entityType: string, externalId: string): string {
|
||||
return `${entityType}:${externalId}`;
|
||||
}
|
||||
|
||||
function requireTenantContext(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpProjectDomainError("project_not_found");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function normalizeId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{3,191}$/u.test(normalized)) throw new KwpProjectDomainError("project_not_found");
|
||||
return normalized;
|
||||
}
|
||||
+263
@@ -0,0 +1,263 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
auditEvent: vi.fn(),
|
||||
logActivity: vi.fn(),
|
||||
loadArea: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
transaction: vi.fn(),
|
||||
runUpdateMany: vi.fn(),
|
||||
bindingFindFirst: vi.fn(),
|
||||
bindingFindMany: vi.fn(),
|
||||
bindingCreate: vi.fn(),
|
||||
bindingUpdateMany: vi.fn(),
|
||||
projectFindFirst: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
tenantUserFindFirst: vi.fn(),
|
||||
runCreate: vi.fn(),
|
||||
itemCreate: vi.fn(),
|
||||
appointmentCreate: vi.fn(),
|
||||
appointmentFindFirst: vi.fn(),
|
||||
appointmentUpdate: vi.fn(),
|
||||
taskCreate: vi.fn(),
|
||||
taskFindFirst: vi.fn(),
|
||||
taskUpdate: vi.fn(),
|
||||
materialCreate: vi.fn(),
|
||||
materialFindFirst: vi.fn(),
|
||||
materialUpdate: vi.fn(),
|
||||
materialUpdateMany: vi.fn(),
|
||||
events: [] as string[],
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/activity", () => ({ logActivity: mocks.logActivity }));
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({
|
||||
$transaction: mocks.transaction,
|
||||
appSyncRun: { updateMany: mocks.runUpdateMany },
|
||||
}),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({ getRlsExecutionContext: mocks.getRlsExecutionContext }));
|
||||
vi.mock("@hivegrid/foundation", () => ({ auditEvent: mocks.auditEvent }));
|
||||
vi.mock("./inbound-reader.js", () => ({ loadKwpProjectInboundArea: mocks.loadArea }));
|
||||
|
||||
import { syncKwpProjectInbound } from "./inbound-sync.server.js";
|
||||
|
||||
const now = new Date("2026-07-24T09:00:00.000Z");
|
||||
const projectBinding = {
|
||||
dataConnectionId: "connection-1",
|
||||
externalId: "P-100",
|
||||
localId: "project-1",
|
||||
};
|
||||
const snapshot = {
|
||||
appointments: [{
|
||||
externalId: "appointment-1",
|
||||
title: "Montage",
|
||||
description: null,
|
||||
startsAt: "2026-08-01T08:00:00.000Z",
|
||||
endsAt: null,
|
||||
statusId: 1,
|
||||
typeId: 2,
|
||||
}],
|
||||
tasks: [{
|
||||
externalId: "activity-1",
|
||||
title: "Rückruf",
|
||||
status: "open" as const,
|
||||
deadline: null,
|
||||
completedAt: null,
|
||||
}],
|
||||
materialPositions: [{
|
||||
externalId: "P-100:01",
|
||||
positionNumber: "01",
|
||||
text: "Ventil",
|
||||
longText: null,
|
||||
quantity: 2,
|
||||
unit: "Stk",
|
||||
unitPrice: 12.5,
|
||||
totalPrice: 25,
|
||||
positionMarker: 0,
|
||||
}],
|
||||
};
|
||||
|
||||
const tx = {
|
||||
appEntityBinding: {
|
||||
findFirst: mocks.bindingFindFirst,
|
||||
findMany: mocks.bindingFindMany,
|
||||
create: mocks.bindingCreate,
|
||||
updateMany: mocks.bindingUpdateMany,
|
||||
},
|
||||
projekt: { findFirst: mocks.projectFindFirst },
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
tenantUser: { findFirst: mocks.tenantUserFindFirst },
|
||||
appSyncRun: { create: mocks.runCreate },
|
||||
appSyncItem: { create: mocks.itemCreate },
|
||||
projektTermin: {
|
||||
create: mocks.appointmentCreate,
|
||||
findFirst: mocks.appointmentFindFirst,
|
||||
update: mocks.appointmentUpdate,
|
||||
},
|
||||
task: {
|
||||
create: mocks.taskCreate,
|
||||
findFirst: mocks.taskFindFirst,
|
||||
update: mocks.taskUpdate,
|
||||
},
|
||||
kwpMaterialPosition: {
|
||||
create: mocks.materialCreate,
|
||||
findFirst: mocks.materialFindFirst,
|
||||
update: mocks.materialUpdate,
|
||||
updateMany: mocks.materialUpdateMany,
|
||||
},
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.events.length = 0;
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1" });
|
||||
mocks.transaction.mockImplementation(async (callback) => {
|
||||
mocks.events.push("tx:start");
|
||||
const value = await callback(tx);
|
||||
mocks.events.push("tx:end");
|
||||
return value;
|
||||
});
|
||||
mocks.bindingFindFirst.mockResolvedValue(projectBinding);
|
||||
mocks.bindingFindMany.mockResolvedValue([]);
|
||||
mocks.bindingCreate.mockResolvedValue({});
|
||||
mocks.bindingUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.projectFindFirst.mockResolvedValue({ id: "project-1", createdByUserId: "user-1" });
|
||||
mocks.connectionFindFirst.mockResolvedValue({ createdByUserId: "user-1" });
|
||||
mocks.tenantUserFindFirst.mockResolvedValue({ userId: "user-1" });
|
||||
mocks.runCreate.mockResolvedValue({ id: "run-1" });
|
||||
mocks.runUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.itemCreate.mockResolvedValue({});
|
||||
mocks.appointmentCreate.mockResolvedValue({ id: "appointment-local-1" });
|
||||
mocks.taskCreate.mockResolvedValue({ id: "task-local-1" });
|
||||
mocks.materialCreate.mockResolvedValue({ id: "material-local-1" });
|
||||
mocks.loadArea.mockImplementation(async ({ area }) => {
|
||||
mocks.events.push(`provider:${area}`);
|
||||
return {
|
||||
appointments: area === "appointments" ? snapshot.appointments : [],
|
||||
tasks: area === "tasks" ? snapshot.tasks : [],
|
||||
materialPositions: area === "material" ? snapshot.materialPositions : [],
|
||||
};
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP project inbound sync", () => {
|
||||
it("performs all provider I/O before one atomic local reconciliation", async () => {
|
||||
await expect(syncKwpProjectInbound({ bindingId: "binding-1", now })).resolves.toMatchObject({
|
||||
runId: "run-1",
|
||||
projectId: "project-1",
|
||||
appointments: 1,
|
||||
tasks: 1,
|
||||
materialPositions: 1,
|
||||
failedAreas: [],
|
||||
changed: true,
|
||||
});
|
||||
expect(mocks.events).toEqual([
|
||||
"tx:start",
|
||||
"tx:end",
|
||||
"provider:appointments",
|
||||
"provider:tasks",
|
||||
"provider:material",
|
||||
"tx:start",
|
||||
"tx:end",
|
||||
]);
|
||||
expect(mocks.appointmentCreate).toHaveBeenCalledWith({ data: expect.objectContaining({ projektId: "project-1", titel: "Montage" }) });
|
||||
expect(mocks.taskCreate).toHaveBeenCalledWith({ data: expect.objectContaining({
|
||||
linkedEntityId: "project-1",
|
||||
source: "api",
|
||||
sourceRef: "kwp:connection-1:activity-1",
|
||||
}) });
|
||||
expect(mocks.materialCreate).toHaveBeenCalledWith({ data: expect.objectContaining({
|
||||
externalId: "P-100:01",
|
||||
totalPrice: 25,
|
||||
}) });
|
||||
expect(mocks.bindingCreate).toHaveBeenCalledTimes(3);
|
||||
expect(mocks.itemCreate).toHaveBeenCalledTimes(3);
|
||||
expect(mocks.itemCreate).toHaveBeenNthCalledWith(1, {
|
||||
data: expect.objectContaining({ operation: "created", status: "synced" }),
|
||||
});
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
status: "completed",
|
||||
itemsTotal: 6,
|
||||
itemsSucceeded: 6,
|
||||
}),
|
||||
}));
|
||||
expect(mocks.auditEvent).toHaveBeenCalledOnce();
|
||||
expect(mocks.logActivity).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("applies healthy areas and leaves failed-area bindings untouched", async () => {
|
||||
mocks.bindingFindMany.mockResolvedValueOnce([{
|
||||
id: "child-binding-1",
|
||||
externalEntityType: "kwp_appointment",
|
||||
externalId: "appointment-old",
|
||||
localId: "appointment-local-old",
|
||||
fingerprint: "old",
|
||||
revision: 2,
|
||||
}]);
|
||||
mocks.loadArea.mockImplementation(async ({ area }) => {
|
||||
mocks.events.push(`provider:${area}`);
|
||||
if (area === "appointments") throw Object.assign(new Error("KWP unavailable"), { code: "provider_outage" });
|
||||
return {
|
||||
appointments: [],
|
||||
tasks: area === "tasks" ? snapshot.tasks : [],
|
||||
materialPositions: area === "material" ? snapshot.materialPositions : [],
|
||||
};
|
||||
});
|
||||
await expect(syncKwpProjectInbound({ bindingId: "binding-1", now })).resolves.toMatchObject({
|
||||
appointments: 0,
|
||||
tasks: 1,
|
||||
materialPositions: 1,
|
||||
failedAreas: ["appointments"],
|
||||
});
|
||||
expect(mocks.appointmentCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.taskCreate).toHaveBeenCalledOnce();
|
||||
expect(mocks.materialCreate).toHaveBeenCalledOnce();
|
||||
expect(mocks.bindingUpdateMany).not.toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: expect.objectContaining({ id: "child-binding-1" }),
|
||||
}));
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({
|
||||
status: "partial",
|
||||
itemsFailed: 1,
|
||||
summaryText: "integrations.sync.summary.kwpInboundPartial",
|
||||
}),
|
||||
}));
|
||||
});
|
||||
|
||||
it("does not reconcile locally when every provider area fails", async () => {
|
||||
mocks.loadArea.mockRejectedValue(Object.assign(new Error("KWP unavailable"), { code: "provider_outage" }));
|
||||
await expect(syncKwpProjectInbound({ bindingId: "binding-1", now })).rejects.toThrow("KWP unavailable");
|
||||
expect(mocks.appointmentCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.taskCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.materialCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({ status: "failed", itemsFailed: 1 }),
|
||||
}));
|
||||
});
|
||||
|
||||
it("rejects a stale binding revision instead of accepting last-write-wins", async () => {
|
||||
mocks.bindingFindMany.mockResolvedValueOnce([{
|
||||
id: "child-binding-1",
|
||||
externalEntityType: "kwp_appointment",
|
||||
externalId: "appointment-1",
|
||||
localId: "appointment-local-1",
|
||||
fingerprint: "old",
|
||||
revision: 4,
|
||||
}]);
|
||||
mocks.appointmentFindFirst.mockResolvedValueOnce({
|
||||
id: "appointment-local-1",
|
||||
titel: "Alt",
|
||||
beschreibung: null,
|
||||
startAt: new Date("2026-07-01T08:00:00.000Z"),
|
||||
endAt: null,
|
||||
});
|
||||
mocks.appointmentUpdate.mockResolvedValueOnce({});
|
||||
mocks.bindingUpdateMany.mockResolvedValueOnce({ count: 0 });
|
||||
await expect(syncKwpProjectInbound({ bindingId: "binding-1", now })).rejects.toThrow("stale_write");
|
||||
expect(mocks.runUpdateMany).toHaveBeenLastCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({ status: "failed" }),
|
||||
}));
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,3 @@
|
||||
export * from "./client.js";
|
||||
export * from "./oauth-attempt.js";
|
||||
export { kwpAdapter } from "./adapter.js";
|
||||
+62
@@ -0,0 +1,62 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
KWP_LEGACY_MANDANT_SELECTION_KIND,
|
||||
KWP_MANDANT_SELECTION_KIND,
|
||||
KWP_OAUTH_RESERVATION_KIND,
|
||||
parseKwpOAuthReservationBundle,
|
||||
parseKwpPendingAttemptLifecycle,
|
||||
} from "./oauth-attempt.js";
|
||||
|
||||
const PREVIOUS = {
|
||||
credentialsCiphertext: "tenant-envelope-ciphertext",
|
||||
connectionStatus: "active",
|
||||
lastHealthCheck: "2026-07-20T11:00:00.000Z",
|
||||
healthMessageKey: "integrations.health.active",
|
||||
tokenExpiresAt: "2026-07-20T13:00:00.000Z",
|
||||
createdByUserId: "user_1",
|
||||
} as const;
|
||||
|
||||
describe("KWP pending OAuth-attempt codec", () => {
|
||||
it("keeps the previous stable connection opaque and restorable", () => {
|
||||
const encoded = JSON.stringify({
|
||||
kind: KWP_OAUTH_RESERVATION_KIND,
|
||||
customerCode: "geerkens2",
|
||||
previous: PREVIOUS,
|
||||
issuedAt: "2026-07-20T12:00:00.000Z",
|
||||
expiresAt: "2026-07-20T12:10:00.000Z",
|
||||
});
|
||||
|
||||
expect(parseKwpOAuthReservationBundle(encoded)).toEqual({
|
||||
kind: KWP_OAUTH_RESERVATION_KIND,
|
||||
customerCode: "geerkens2",
|
||||
previous: PREVIOUS,
|
||||
issuedAt: "2026-07-20T12:00:00.000Z",
|
||||
expiresAt: "2026-07-20T12:10:00.000Z",
|
||||
});
|
||||
expect(parseKwpPendingAttemptLifecycle(encoded)).toEqual({ phase: "oauth", previous: PREVIOUS });
|
||||
});
|
||||
|
||||
it("treats the legacy v1 selection envelope as a first-time attempt", () => {
|
||||
const encoded = JSON.stringify({
|
||||
kind: KWP_LEGACY_MANDANT_SELECTION_KIND,
|
||||
oauth: {},
|
||||
discovery: {},
|
||||
issuedAt: "2026-07-20T12:00:00.000Z",
|
||||
});
|
||||
|
||||
expect(parseKwpPendingAttemptLifecycle(encoded)).toEqual({ phase: "mandant", previous: null });
|
||||
});
|
||||
|
||||
it("rejects malformed restoration snapshots instead of applying them", () => {
|
||||
const encoded = JSON.stringify({
|
||||
kind: KWP_MANDANT_SELECTION_KIND,
|
||||
previous: { ...PREVIOUS, connectionStatus: "pending" },
|
||||
oauth: {},
|
||||
discovery: {},
|
||||
issuedAt: "2026-07-20T12:00:00.000Z",
|
||||
});
|
||||
|
||||
expect(parseKwpPendingAttemptLifecycle(encoded)).toBeNull();
|
||||
});
|
||||
});
|
||||
+156
@@ -0,0 +1,156 @@
|
||||
import { isValidKwpContextCode } from "./client.js";
|
||||
|
||||
export const KWP_OAUTH_RESERVATION_KIND = "kwp_oauth_reservation_v1" as const;
|
||||
export const KWP_MANDANT_SELECTION_KIND = "kwp_mandant_selection_v2" as const;
|
||||
export const KWP_LEGACY_MANDANT_SELECTION_KIND = "kwp_mandant_selection_v1" as const;
|
||||
export const KWP_OAUTH_PENDING_HEALTH_KEY = "integrations.kwp.health.oauthPending" as const;
|
||||
export const KWP_MANDANT_SELECTION_HEALTH_KEY = "integrations.kwp.health.mandantSelectionRequired" as const;
|
||||
|
||||
const MAX_CIPHERTEXT_LENGTH = 1_000_000;
|
||||
const MAX_CONTEXT_ID_LENGTH = 256;
|
||||
const MAX_HEALTH_KEY_LENGTH = 512;
|
||||
|
||||
export type KwpRestorableConnectionStatus = "active" | "degraded" | "broken" | "revoked";
|
||||
|
||||
/**
|
||||
* Opaque snapshot of the working connection that existed before reconnect.
|
||||
* The ciphertext remains tenant-envelope encrypted even inside the encrypted
|
||||
* pending envelope, so cleanup can restore it without ever exposing tokens.
|
||||
*/
|
||||
export type KwpRestorableConnectionSnapshot = {
|
||||
readonly credentialsCiphertext: string | null;
|
||||
readonly connectionStatus: KwpRestorableConnectionStatus;
|
||||
readonly lastHealthCheck: string | null;
|
||||
readonly healthMessageKey: string | null;
|
||||
readonly tokenExpiresAt: string | null;
|
||||
readonly createdByUserId: string | null;
|
||||
};
|
||||
|
||||
export type KwpOAuthReservationBundle = {
|
||||
readonly kind: typeof KWP_OAUTH_RESERVATION_KIND;
|
||||
readonly customerCode: string;
|
||||
readonly previous: KwpRestorableConnectionSnapshot | null;
|
||||
readonly issuedAt: string;
|
||||
readonly expiresAt: string;
|
||||
};
|
||||
|
||||
export type KwpPendingAttemptLifecycle = {
|
||||
readonly phase: "oauth" | "mandant";
|
||||
readonly previous: KwpRestorableConnectionSnapshot | null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Parse only the lifecycle portion shared by web and worker. The web service
|
||||
* performs the stricter OAuth/discovery validation before exposing a selection;
|
||||
* the worker needs only a trustworthy restoration snapshot for expired rows.
|
||||
*/
|
||||
export function parseKwpPendingAttemptLifecycle(plaintext: string): KwpPendingAttemptLifecycle | null {
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(plaintext);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!isRecord(value)) return null;
|
||||
|
||||
const previous = parsePreviousSnapshot(value.previous);
|
||||
|
||||
// Compatibility for pending rows written by the first Mandant-flow build.
|
||||
// That format could not preserve a previous active connection, so `null` is
|
||||
// the only safe restoration target.
|
||||
if (value.kind === KWP_LEGACY_MANDANT_SELECTION_KIND && value.previous === undefined) {
|
||||
if (!isCanonicalIsoTimestamp(value.issuedAt) || !isRecord(value.oauth) || !isRecord(value.discovery)) return null;
|
||||
return { phase: "mandant", previous: null };
|
||||
}
|
||||
|
||||
if (previous === undefined) return null;
|
||||
|
||||
if (value.kind === KWP_OAUTH_RESERVATION_KIND) {
|
||||
if (
|
||||
!isValidKwpContextCode(value.customerCode) ||
|
||||
!isCanonicalIsoTimestamp(value.issuedAt) ||
|
||||
!isCanonicalIsoTimestamp(value.expiresAt)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
return { phase: "oauth", previous };
|
||||
}
|
||||
|
||||
if (value.kind === KWP_MANDANT_SELECTION_KIND) {
|
||||
if (!isCanonicalIsoTimestamp(value.issuedAt) || !isRecord(value.oauth) || !isRecord(value.discovery)) return null;
|
||||
return { phase: "mandant", previous };
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
export function parseKwpOAuthReservationBundle(plaintext: string): KwpOAuthReservationBundle | null {
|
||||
let value: unknown;
|
||||
try {
|
||||
value = JSON.parse(plaintext);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!isRecord(value) || value.kind !== KWP_OAUTH_RESERVATION_KIND) return null;
|
||||
const previous = parsePreviousSnapshot(value.previous);
|
||||
if (
|
||||
previous === undefined ||
|
||||
!isValidKwpContextCode(value.customerCode) ||
|
||||
!isCanonicalIsoTimestamp(value.issuedAt) ||
|
||||
!isCanonicalIsoTimestamp(value.expiresAt)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
return {
|
||||
kind: KWP_OAUTH_RESERVATION_KIND,
|
||||
customerCode: value.customerCode,
|
||||
previous,
|
||||
issuedAt: value.issuedAt,
|
||||
expiresAt: value.expiresAt,
|
||||
};
|
||||
}
|
||||
|
||||
function parsePreviousSnapshot(value: unknown): KwpRestorableConnectionSnapshot | null | undefined {
|
||||
if (value === null) return null;
|
||||
if (!isRecord(value)) return undefined;
|
||||
if (
|
||||
!isNullableBoundedString(value.credentialsCiphertext, MAX_CIPHERTEXT_LENGTH, false) ||
|
||||
!isRestorableStatus(value.connectionStatus) ||
|
||||
!isNullableCanonicalIsoTimestamp(value.lastHealthCheck) ||
|
||||
!isNullableBoundedString(value.healthMessageKey, MAX_HEALTH_KEY_LENGTH, true) ||
|
||||
!isNullableCanonicalIsoTimestamp(value.tokenExpiresAt) ||
|
||||
!isNullableBoundedString(value.createdByUserId, MAX_CONTEXT_ID_LENGTH, false)
|
||||
) {
|
||||
return undefined;
|
||||
}
|
||||
return {
|
||||
credentialsCiphertext: value.credentialsCiphertext,
|
||||
connectionStatus: value.connectionStatus,
|
||||
lastHealthCheck: value.lastHealthCheck,
|
||||
healthMessageKey: value.healthMessageKey,
|
||||
tokenExpiresAt: value.tokenExpiresAt,
|
||||
createdByUserId: value.createdByUserId,
|
||||
};
|
||||
}
|
||||
|
||||
function isRestorableStatus(value: unknown): value is KwpRestorableConnectionStatus {
|
||||
return value === "active" || value === "degraded" || value === "broken" || value === "revoked";
|
||||
}
|
||||
|
||||
function isNullableCanonicalIsoTimestamp(value: unknown): value is string | null {
|
||||
return value === null || isCanonicalIsoTimestamp(value);
|
||||
}
|
||||
|
||||
function isCanonicalIsoTimestamp(value: unknown): value is string {
|
||||
if (typeof value !== "string") return false;
|
||||
const timestamp = Date.parse(value);
|
||||
return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
|
||||
}
|
||||
|
||||
function isNullableBoundedString(value: unknown, maxLength: number, allowEmpty: boolean): value is string | null {
|
||||
return value === null || (typeof value === "string" && value.length <= maxLength && (allowEmpty || value.length > 0));
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
+373
@@ -0,0 +1,373 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
|
||||
import { KwpError } from "./client.js";
|
||||
import { runKwpResourceSession, searchProjects } from "./resource-client.server.js";
|
||||
import {
|
||||
KWP_PROJECT_STATUS_LABELS,
|
||||
type KwpProjectDetails,
|
||||
type KwpProjectSearchResult,
|
||||
type KwpProjectStatus,
|
||||
} from "./resource-client.js";
|
||||
|
||||
const DISCOVERY_INTERVAL_MS = 6 * 60 * 60_000;
|
||||
const ACTIVE_REFRESH_INTERVAL_MS = 24 * 60 * 60_000;
|
||||
const MISSING_REFRESH_INTERVAL_MS = 6 * 60 * 60_000;
|
||||
const HYDRATION_BATCH_SIZE = 20;
|
||||
const DISCOVERY_WRITE_BATCH_SIZE = 1_000;
|
||||
const SEARCH_RESULT_LIMIT = 50;
|
||||
|
||||
export type KwpProjectCatalogSummary = {
|
||||
readonly status: "pending" | "syncing" | "ready" | "partial" | "paused";
|
||||
readonly discoveredCount: number;
|
||||
readonly hydratedCount: number;
|
||||
readonly lastDiscoveryAt: string | null;
|
||||
readonly lastCompletedAt: string | null;
|
||||
};
|
||||
|
||||
export type KwpProjectCatalogSyncResult = {
|
||||
readonly discoveredCount: number;
|
||||
readonly hydratedCount: number;
|
||||
readonly processed: number;
|
||||
readonly hasMore: boolean;
|
||||
readonly status: KwpProjectCatalogSummary["status"];
|
||||
};
|
||||
|
||||
export async function getKwpProjectCatalogSummary(input: {
|
||||
readonly connectionId: string;
|
||||
}): Promise<KwpProjectCatalogSummary> {
|
||||
const tenantId = requireTenantId();
|
||||
const state = await getDbClient().kwpProjectCatalogState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId: {
|
||||
tenantId,
|
||||
dataConnectionId: normalizeConnectionId(input.connectionId),
|
||||
},
|
||||
},
|
||||
});
|
||||
return {
|
||||
status: state?.status ?? "pending",
|
||||
discoveredCount: state?.discoveredCount ?? 0,
|
||||
hydratedCount: state?.hydratedCount ?? 0,
|
||||
lastDiscoveryAt: state?.lastDiscoveryAt?.toISOString() ?? null,
|
||||
lastCompletedAt: state?.lastCompletedAt?.toISOString() ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
export async function searchKwpProjectCatalog(input: {
|
||||
readonly connectionId: string;
|
||||
readonly query: string;
|
||||
readonly limit?: number;
|
||||
}): Promise<KwpProjectSearchResult[]> {
|
||||
const tenantId = requireTenantId();
|
||||
const dataConnectionId = normalizeConnectionId(input.connectionId);
|
||||
const normalizedQuery = normalizeSearchText(input.query);
|
||||
if (normalizedQuery.length < 2) return [];
|
||||
const take = Math.min(Math.max(input.limit ?? SEARCH_RESULT_LIMIT, 1), SEARCH_RESULT_LIMIT);
|
||||
const rows = await getDbClient().kwpProjectCatalogItem.findMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
state: "active",
|
||||
searchText: { contains: normalizedQuery },
|
||||
status: { not: null },
|
||||
},
|
||||
orderBy: [{ externalProjectNumber: "asc" }],
|
||||
take,
|
||||
});
|
||||
return rows
|
||||
.sort((left, right) => Number(right.externalProjectNumber === input.query.trim()) - Number(left.externalProjectNumber === input.query.trim()))
|
||||
.map((row) => {
|
||||
const status = row.status as KwpProjectStatus;
|
||||
return {
|
||||
externalProjectNumber: row.externalProjectNumber,
|
||||
name: row.name,
|
||||
projectAddressCode: row.projectAddressCode,
|
||||
invoiceAddressCode: row.invoiceAddressCode,
|
||||
clientAddressCode: row.clientAddressCode,
|
||||
status,
|
||||
statusLabel: KWP_PROJECT_STATUS_LABELS[status],
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/** Cache-first manual search. A targeted provider read keeps newly-created KWP
|
||||
* projects discoverable before the background catalog reaches them. Only
|
||||
* transient provider failures may fall back to an already-populated cache. */
|
||||
export async function searchAndCacheKwpProjects(input: {
|
||||
readonly connectionId: string;
|
||||
readonly query: string;
|
||||
}): Promise<KwpProjectSearchResult[]> {
|
||||
const cached = await searchKwpProjectCatalog(input);
|
||||
try {
|
||||
const live = await searchProjects(input);
|
||||
await cacheKwpProjectSearchResults({ connectionId: input.connectionId, results: live });
|
||||
return mergeSearchResults(live, cached);
|
||||
} catch (error) {
|
||||
if (cached.length > 0 && isTransientKwpError(error)) return cached;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
export async function cacheKwpProjectSearchResults(input: {
|
||||
readonly connectionId: string;
|
||||
readonly results: readonly KwpProjectSearchResult[];
|
||||
readonly now?: Date;
|
||||
}): Promise<void> {
|
||||
if (input.results.length === 0) return;
|
||||
const tenantId = requireTenantId();
|
||||
const dataConnectionId = normalizeConnectionId(input.connectionId);
|
||||
const now = input.now ?? new Date();
|
||||
const nextRefreshAt = new Date(now.getTime() + ACTIVE_REFRESH_INTERVAL_MS);
|
||||
await getDbClient().$transaction((tx) =>
|
||||
Promise.all(
|
||||
input.results.map((result) => {
|
||||
const normalized = normalizeSearchResult(result);
|
||||
return tx.kwpProjectCatalogItem.upsert({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalProjectNumber: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
externalProjectNumber: normalized.externalProjectNumber,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
...normalized,
|
||||
state: "active",
|
||||
discoveredAt: now,
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
nextRefreshAt,
|
||||
},
|
||||
update: {
|
||||
...normalized,
|
||||
state: "active",
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
nextRefreshAt,
|
||||
missingSince: null,
|
||||
refreshAttempts: 0,
|
||||
lastErrorCode: null,
|
||||
},
|
||||
});
|
||||
}),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
export async function cacheKwpProjectDetails(input: {
|
||||
readonly connectionId: string;
|
||||
readonly details: KwpProjectDetails;
|
||||
}): Promise<void> {
|
||||
const tenantId = requireTenantId();
|
||||
const dataConnectionId = normalizeConnectionId(input.connectionId);
|
||||
const now = new Date();
|
||||
await getDbClient().kwpProjectCatalogItem.updateMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
externalProjectNumber: input.details.externalProjectNumber,
|
||||
},
|
||||
data: {
|
||||
name: input.details.name,
|
||||
searchText: normalizeSearchText(`${input.details.externalProjectNumber} ${input.details.name}`),
|
||||
startDate: input.details.startDate ? new Date(input.details.startDate) : null,
|
||||
orderValue: input.details.orderValue,
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
/** Three-phase bounded catalog worker:
|
||||
* 1. short RLS state read,
|
||||
* 2. provider reads outside database transactions,
|
||||
* 3. short batched RLS writes.
|
||||
*
|
||||
* LoadProjekteNachFilter has no pagination and is explicitly treated as the
|
||||
* connection's setting-visible discovery set, not as a guaranteed full export.
|
||||
*/
|
||||
export async function syncKwpProjectCatalog(input: {
|
||||
readonly connectionId: string;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpProjectCatalogSyncResult> {
|
||||
const tenantId = requireTenantId();
|
||||
const dataConnectionId = normalizeConnectionId(input.connectionId);
|
||||
const now = input.now ?? new Date();
|
||||
const db = getDbClient();
|
||||
const initialState = await db.kwpProjectCatalogState.upsert({
|
||||
where: { tenantId_dataConnectionId: { tenantId, dataConnectionId } },
|
||||
create: { tenantId, dataConnectionId, status: "pending", nextDiscoveryAt: now },
|
||||
update: {},
|
||||
});
|
||||
|
||||
try {
|
||||
return await runKwpResourceSession({ connectionId: dataConnectionId }, async (resource) => {
|
||||
let discoveredCount = initialState.discoveredCount;
|
||||
if (initialState.nextDiscoveryAt <= now) {
|
||||
const projectNumbers = await resource.listProjectNumbers();
|
||||
for (let offset = 0; offset < projectNumbers.length; offset += DISCOVERY_WRITE_BATCH_SIZE) {
|
||||
const batch = projectNumbers.slice(offset, offset + DISCOVERY_WRITE_BATCH_SIZE);
|
||||
await db.kwpProjectCatalogItem.createMany({
|
||||
data: batch.map((externalProjectNumber) => ({
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
externalProjectNumber,
|
||||
name: externalProjectNumber,
|
||||
searchText: normalizeSearchText(externalProjectNumber),
|
||||
normalizedFingerprint: fingerprint({ externalProjectNumber }),
|
||||
state: "discovered" as const,
|
||||
discoveredAt: now,
|
||||
lastSeenAt: now,
|
||||
nextRefreshAt: now,
|
||||
})),
|
||||
skipDuplicates: true,
|
||||
});
|
||||
}
|
||||
discoveredCount = projectNumbers.length;
|
||||
await db.kwpProjectCatalogState.update({
|
||||
where: { tenantId_dataConnectionId: { tenantId, dataConnectionId } },
|
||||
data: {
|
||||
status: projectNumbers.length === 0 ? "ready" : "syncing",
|
||||
discoveredCount,
|
||||
lastDiscoveryAt: now,
|
||||
nextDiscoveryAt: new Date(now.getTime() + DISCOVERY_INTERVAL_MS),
|
||||
lastErrorCode: null,
|
||||
revision: { increment: 1 },
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
const due = await db.kwpProjectCatalogItem.findMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
state: { in: ["discovered", "active", "missing"] },
|
||||
nextRefreshAt: { lte: now },
|
||||
},
|
||||
orderBy: [{ state: "asc" }, { nextRefreshAt: "asc" }, { externalProjectNumber: "asc" }],
|
||||
take: HYDRATION_BATCH_SIZE,
|
||||
select: { externalProjectNumber: true },
|
||||
});
|
||||
let processed = 0;
|
||||
for (const item of due) {
|
||||
const matches = await resource.searchProjects(item.externalProjectNumber);
|
||||
const exact = matches.find((result) => result.externalProjectNumber === item.externalProjectNumber);
|
||||
if (exact) {
|
||||
await cacheKwpProjectSearchResults({ connectionId: dataConnectionId, results: [exact], now });
|
||||
} else {
|
||||
await db.kwpProjectCatalogItem.update({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalProjectNumber: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
externalProjectNumber: item.externalProjectNumber,
|
||||
},
|
||||
},
|
||||
data: {
|
||||
state: "missing",
|
||||
missingSince: now,
|
||||
lastSyncedAt: now,
|
||||
nextRefreshAt: new Date(now.getTime() + MISSING_REFRESH_INTERVAL_MS),
|
||||
refreshAttempts: { increment: 1 },
|
||||
lastErrorCode: "resource_not_found",
|
||||
},
|
||||
});
|
||||
}
|
||||
processed += 1;
|
||||
}
|
||||
|
||||
const [hydratedCount, remaining] = await Promise.all([
|
||||
db.kwpProjectCatalogItem.count({
|
||||
where: { tenantId, dataConnectionId, lastSyncedAt: { not: null } },
|
||||
}),
|
||||
db.kwpProjectCatalogItem.count({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId,
|
||||
state: { in: ["discovered", "active", "missing"] },
|
||||
nextRefreshAt: { lte: now },
|
||||
},
|
||||
}),
|
||||
]);
|
||||
const hasMore = remaining > 0;
|
||||
const status = hasMore ? "syncing" : "ready";
|
||||
await db.kwpProjectCatalogState.update({
|
||||
where: { tenantId_dataConnectionId: { tenantId, dataConnectionId } },
|
||||
data: {
|
||||
status,
|
||||
discoveredCount,
|
||||
hydratedCount,
|
||||
lastCompletedAt: hasMore ? undefined : now,
|
||||
lastErrorCode: null,
|
||||
revision: { increment: 1 },
|
||||
},
|
||||
});
|
||||
return { discoveredCount, hydratedCount, processed, hasMore, status };
|
||||
});
|
||||
} catch (error) {
|
||||
const paused = error instanceof KwpError && ["auth_scope_missing", "capability_paused", "contract_drift"].includes(error.code);
|
||||
await db.kwpProjectCatalogState.updateMany({
|
||||
where: { tenantId, dataConnectionId },
|
||||
data: {
|
||||
status: paused ? "paused" : "partial",
|
||||
lastErrorCode: error instanceof KwpError ? error.code : "provider_outage",
|
||||
revision: { increment: 1 },
|
||||
},
|
||||
});
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeSearchResult(result: KwpProjectSearchResult) {
|
||||
return {
|
||||
externalProjectNumber: result.externalProjectNumber,
|
||||
name: result.name,
|
||||
searchText: normalizeSearchText(`${result.externalProjectNumber} ${result.name}`),
|
||||
status: result.status,
|
||||
projectAddressCode: result.projectAddressCode,
|
||||
invoiceAddressCode: result.invoiceAddressCode,
|
||||
clientAddressCode: result.clientAddressCode,
|
||||
normalizedFingerprint: fingerprint(result),
|
||||
};
|
||||
}
|
||||
|
||||
function mergeSearchResults(
|
||||
primary: readonly KwpProjectSearchResult[],
|
||||
secondary: readonly KwpProjectSearchResult[],
|
||||
): KwpProjectSearchResult[] {
|
||||
return [...new Map([...primary, ...secondary].map((result) => [result.externalProjectNumber, result])).values()].slice(0, SEARCH_RESULT_LIMIT);
|
||||
}
|
||||
|
||||
function normalizeSearchText(value: string): string {
|
||||
return value
|
||||
.normalize("NFKD")
|
||||
.replace(/\p{Diacritic}/gu, "")
|
||||
.trim()
|
||||
.toLocaleLowerCase("de-DE")
|
||||
.slice(0, 1_024);
|
||||
}
|
||||
|
||||
function fingerprint(value: unknown): string {
|
||||
return createHash("sha256").update(JSON.stringify(value)).digest("hex");
|
||||
}
|
||||
|
||||
function isTransientKwpError(error: unknown): boolean {
|
||||
return error instanceof KwpError && ["auth_token_invalid", "provider_outage", "rate_limit_exceeded"].includes(error.code);
|
||||
}
|
||||
|
||||
function requireTenantId(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpError("invalid_credentials");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function normalizeConnectionId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{8,191}$/u.test(normalized)) throw new KwpError("invalid_credentials");
|
||||
return normalized;
|
||||
}
|
||||
+152
@@ -0,0 +1,152 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
db: {
|
||||
kwpProjectCatalogState: {
|
||||
findUnique: vi.fn(),
|
||||
upsert: vi.fn(),
|
||||
update: vi.fn(),
|
||||
updateMany: vi.fn(),
|
||||
},
|
||||
kwpProjectCatalogItem: {
|
||||
findMany: vi.fn(),
|
||||
createMany: vi.fn(),
|
||||
upsert: vi.fn(),
|
||||
update: vi.fn(),
|
||||
updateMany: vi.fn(),
|
||||
count: vi.fn(),
|
||||
},
|
||||
$transaction: vi.fn(),
|
||||
},
|
||||
resource: {
|
||||
listProjectNumbers: vi.fn(),
|
||||
searchProjects: vi.fn(),
|
||||
},
|
||||
searchProjects: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => mocks.db,
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({
|
||||
getRlsExecutionContext: () => ({ tenantId: "tenant_1" }),
|
||||
}));
|
||||
vi.mock("./resource-client.server.js", () => ({
|
||||
runKwpResourceSession: (_input: unknown, operation: (resource: typeof mocks.resource) => Promise<unknown>) =>
|
||||
operation(mocks.resource),
|
||||
searchProjects: mocks.searchProjects,
|
||||
}));
|
||||
|
||||
import { KwpError } from "./client.js";
|
||||
import {
|
||||
searchAndCacheKwpProjects,
|
||||
searchKwpProjectCatalog,
|
||||
syncKwpProjectCatalog,
|
||||
} from "./project-catalog.server.js";
|
||||
|
||||
const RESULT = {
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Heizung Schule",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8 as const,
|
||||
statusLabel: "Erhalten",
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.db.$transaction.mockImplementation((operation: (tx: typeof mocks.db) => Promise<unknown>) =>
|
||||
operation(mocks.db));
|
||||
mocks.db.kwpProjectCatalogItem.upsert.mockResolvedValue({});
|
||||
mocks.db.kwpProjectCatalogState.update.mockResolvedValue({});
|
||||
mocks.db.kwpProjectCatalogState.updateMany.mockResolvedValue({ count: 1 });
|
||||
});
|
||||
|
||||
describe("KWP project catalog", () => {
|
||||
it("searches the normalized local cache and maps stable KWP status labels", async () => {
|
||||
mocks.db.kwpProjectCatalogItem.findMany.mockResolvedValue([{
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Heizung Schule",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
}]);
|
||||
|
||||
await expect(searchKwpProjectCatalog({
|
||||
connectionId: "connection_1",
|
||||
query: " Heizung ",
|
||||
})).resolves.toEqual([RESULT]);
|
||||
expect(mocks.db.kwpProjectCatalogItem.findMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: expect.objectContaining({
|
||||
tenantId: "tenant_1",
|
||||
dataConnectionId: "connection_1",
|
||||
searchText: { contains: "heizung" },
|
||||
}),
|
||||
take: 50,
|
||||
}));
|
||||
});
|
||||
|
||||
it("returns cached results during a transient provider outage", async () => {
|
||||
mocks.db.kwpProjectCatalogItem.findMany.mockResolvedValue([{
|
||||
externalProjectNumber: RESULT.externalProjectNumber,
|
||||
name: RESULT.name,
|
||||
projectAddressCode: RESULT.projectAddressCode,
|
||||
invoiceAddressCode: RESULT.invoiceAddressCode,
|
||||
clientAddressCode: RESULT.clientAddressCode,
|
||||
status: RESULT.status,
|
||||
}]);
|
||||
mocks.searchProjects.mockRejectedValue(new KwpError("provider_outage", 503));
|
||||
|
||||
await expect(searchAndCacheKwpProjects({
|
||||
connectionId: "connection_1",
|
||||
query: "Heizung",
|
||||
})).resolves.toEqual([RESULT]);
|
||||
});
|
||||
|
||||
it("discovers and hydrates a bounded batch without provider I/O inside a database transaction", async () => {
|
||||
const now = new Date("2026-07-24T12:00:00.000Z");
|
||||
mocks.db.kwpProjectCatalogState.upsert.mockResolvedValue({
|
||||
discoveredCount: 0,
|
||||
nextDiscoveryAt: now,
|
||||
});
|
||||
mocks.resource.listProjectNumbers.mockResolvedValue(["P-100", "P-200"]);
|
||||
mocks.db.kwpProjectCatalogItem.createMany.mockResolvedValue({ count: 2 });
|
||||
mocks.db.kwpProjectCatalogItem.findMany.mockResolvedValue([
|
||||
{ externalProjectNumber: "P-100" },
|
||||
{ externalProjectNumber: "P-200" },
|
||||
]);
|
||||
mocks.resource.searchProjects.mockImplementation(async (query: string) => [{
|
||||
...RESULT,
|
||||
externalProjectNumber: query,
|
||||
name: `Projekt ${query}`,
|
||||
}]);
|
||||
mocks.db.kwpProjectCatalogItem.count
|
||||
.mockResolvedValueOnce(2)
|
||||
.mockResolvedValueOnce(0);
|
||||
|
||||
await expect(syncKwpProjectCatalog({
|
||||
connectionId: "connection_1",
|
||||
now,
|
||||
})).resolves.toEqual({
|
||||
discoveredCount: 2,
|
||||
hydratedCount: 2,
|
||||
processed: 2,
|
||||
hasMore: false,
|
||||
status: "ready",
|
||||
});
|
||||
|
||||
expect(mocks.resource.listProjectNumbers).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.resource.searchProjects).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.db.kwpProjectCatalogItem.createMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
skipDuplicates: true,
|
||||
data: expect.arrayContaining([
|
||||
expect.objectContaining({ externalProjectNumber: "P-100", state: "discovered" }),
|
||||
]),
|
||||
}));
|
||||
expect(mocks.db.$transaction).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.db.$transaction.mock.invocationCallOrder.every((order) =>
|
||||
mocks.resource.searchProjects.mock.invocationCallOrder.every((providerOrder) => providerOrder !== order))).toBe(true);
|
||||
});
|
||||
});
|
||||
+1736
File diff suppressed because it is too large.
Load diff
+637
@@ -0,0 +1,637 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
auditEvent: vi.fn(),
|
||||
logActivity: vi.fn(),
|
||||
publishOutboxEvent: vi.fn(),
|
||||
publishSearchUpsertEvent: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
transaction: vi.fn(),
|
||||
bindingFindFirst: vi.fn(),
|
||||
bindingFindUnique: vi.fn(),
|
||||
bindingFindUniqueOrThrow: vi.fn(),
|
||||
bindingCreate: vi.fn(),
|
||||
bindingUpdateMany: vi.fn(),
|
||||
bindingFindMany: vi.fn(),
|
||||
projectFindFirst: vi.fn(),
|
||||
projectCreate: vi.fn(),
|
||||
projectUpdateMany: vi.fn(),
|
||||
contactFindFirst: vi.fn(),
|
||||
contactFindMany: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
capabilityFindUnique: vi.fn(),
|
||||
capabilityUpsert: vi.fn(),
|
||||
routingFindUnique: vi.fn(),
|
||||
stageFindFirst: vi.fn(),
|
||||
sequenceUpdate: vi.fn(),
|
||||
syncRunCreate: vi.fn(),
|
||||
syncItemCreate: vi.fn(),
|
||||
executeRaw: vi.fn(),
|
||||
queryRaw: vi.fn(),
|
||||
searchUpsert: vi.fn(),
|
||||
searchProjects: vi.fn(),
|
||||
loadProjectDetails: vi.fn(),
|
||||
loadAddressDetails: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/activity", () => ({ logActivity: mocks.logActivity }));
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({
|
||||
$transaction: mocks.transaction,
|
||||
appEntityBinding: {
|
||||
findUnique: mocks.bindingFindUnique,
|
||||
},
|
||||
kontakt: {
|
||||
findFirst: mocks.contactFindFirst,
|
||||
findMany: mocks.contactFindMany,
|
||||
},
|
||||
kwpProjectRouting: {
|
||||
findUnique: mocks.routingFindUnique,
|
||||
},
|
||||
}),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/outbox", () => ({
|
||||
publishOutboxEvent: mocks.publishOutboxEvent,
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({
|
||||
getRlsExecutionContext: mocks.getRlsExecutionContext,
|
||||
}));
|
||||
vi.mock("@hivegrid/foundation", () => ({
|
||||
auditEvent: mocks.auditEvent,
|
||||
}));
|
||||
vi.mock("@hivegrid/search", () => ({
|
||||
crmContactsIndex: { name: "crm-contacts" },
|
||||
projectsIndex: { name: "projects" },
|
||||
publishSearchUpsertEvent: mocks.publishSearchUpsertEvent,
|
||||
}));
|
||||
vi.mock("./resource-client.server.js", () => ({
|
||||
loadAddressDetails: mocks.loadAddressDetails,
|
||||
loadProjectDetails: mocks.loadProjectDetails,
|
||||
searchProjects: mocks.searchProjects,
|
||||
}));
|
||||
|
||||
import {
|
||||
importKwpProject,
|
||||
previewKwpProjectImport,
|
||||
restoreAndUnlinkKwpProject,
|
||||
unlinkKwpProject,
|
||||
} from "./project-domain.server.js";
|
||||
|
||||
const beforeProject = {
|
||||
id: "project-1",
|
||||
tenantId: "tenant-1",
|
||||
projektNummer: "P-00042",
|
||||
projektname: "KWP name",
|
||||
beschreibung: "Local note",
|
||||
projekttyp: null,
|
||||
quelle: "kwp",
|
||||
pipelineId: "pipeline-kwp",
|
||||
stageId: "stage-kwp",
|
||||
startDatum: new Date("2026-07-01T00:00:00.000Z"),
|
||||
deadline: null,
|
||||
auftragsvolumen: 42_500,
|
||||
potenziellerAuftragswert: null,
|
||||
projektAdresseId: "address-kwp",
|
||||
rechnungsAdresseId: null,
|
||||
bauherrAdresseId: null,
|
||||
zustaendigePersonId: "user-1",
|
||||
projektleiterId: null,
|
||||
wonAt: null,
|
||||
lostAt: null,
|
||||
archivedAt: null,
|
||||
createdAt: new Date("2026-06-01T00:00:00.000Z"),
|
||||
updatedAt: new Date("2026-07-23T10:00:00.000Z"),
|
||||
};
|
||||
|
||||
const restoredProject = {
|
||||
...beforeProject,
|
||||
projektname: "Local name",
|
||||
pipelineId: "pipeline-local",
|
||||
stageId: "stage-local",
|
||||
startDatum: new Date("2026-05-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 12_000,
|
||||
projektAdresseId: "address-local",
|
||||
updatedAt: new Date("2026-07-23T10:01:00.000Z"),
|
||||
};
|
||||
|
||||
const binding = {
|
||||
id: "binding-1",
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-1",
|
||||
state: "active",
|
||||
revision: 4,
|
||||
normalizedSnapshot: {},
|
||||
overwrittenLocalSnapshot: {
|
||||
projektname: "Local name",
|
||||
pipelineId: "pipeline-local",
|
||||
stageId: "stage-local",
|
||||
startDatum: "2026-05-01T00:00:00.000Z",
|
||||
auftragsvolumen: 12_000,
|
||||
projektAdresseId: "address-local",
|
||||
rechnungsAdresseId: null,
|
||||
bauherrAdresseId: null,
|
||||
},
|
||||
};
|
||||
|
||||
const tx = {
|
||||
appEntityBinding: {
|
||||
findFirst: mocks.bindingFindFirst,
|
||||
findUnique: mocks.bindingFindUnique,
|
||||
findUniqueOrThrow: mocks.bindingFindUniqueOrThrow,
|
||||
create: mocks.bindingCreate,
|
||||
updateMany: mocks.bindingUpdateMany,
|
||||
findMany: mocks.bindingFindMany,
|
||||
},
|
||||
projekt: {
|
||||
findFirst: mocks.projectFindFirst,
|
||||
create: mocks.projectCreate,
|
||||
updateMany: mocks.projectUpdateMany,
|
||||
},
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
kwpCapabilityState: {
|
||||
findUnique: mocks.capabilityFindUnique,
|
||||
upsert: mocks.capabilityUpsert,
|
||||
},
|
||||
kwpProjectRouting: { findUnique: mocks.routingFindUnique },
|
||||
pipelineStage: { findFirst: mocks.stageFindFirst },
|
||||
hiveNumberSeq: { update: mocks.sequenceUpdate },
|
||||
appSyncRun: { create: mocks.syncRunCreate },
|
||||
appSyncItem: { create: mocks.syncItemCreate },
|
||||
$executeRaw: mocks.executeRaw,
|
||||
$queryRaw: mocks.queryRaw,
|
||||
searchIndexEntry: { upsert: mocks.searchUpsert },
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1", userId: "user-1" });
|
||||
mocks.transaction.mockImplementation((callback) => callback(tx));
|
||||
mocks.bindingFindFirst.mockResolvedValue(binding);
|
||||
mocks.bindingFindUnique.mockResolvedValue(null);
|
||||
mocks.bindingFindUniqueOrThrow.mockResolvedValue(binding);
|
||||
mocks.bindingCreate.mockResolvedValue({ id: "binding-created" });
|
||||
mocks.bindingUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.bindingFindMany.mockResolvedValue([]);
|
||||
mocks.projectFindFirst
|
||||
.mockResolvedValueOnce(beforeProject)
|
||||
.mockResolvedValueOnce(restoredProject);
|
||||
mocks.projectUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.contactFindFirst.mockResolvedValue(null);
|
||||
mocks.contactFindMany.mockResolvedValue([]);
|
||||
mocks.connectionFindFirst.mockResolvedValue({ id: "connection-1" });
|
||||
mocks.capabilityFindUnique.mockResolvedValue({ status: "active" });
|
||||
mocks.capabilityUpsert.mockResolvedValue({});
|
||||
mocks.routingFindUnique.mockResolvedValue({
|
||||
pipelineId: "pipeline-kwp",
|
||||
stageId: "stage-kwp",
|
||||
});
|
||||
mocks.stageFindFirst.mockResolvedValue({ id: "stage-kwp", stageKind: "neutral" });
|
||||
mocks.sequenceUpdate.mockResolvedValue({});
|
||||
mocks.syncRunCreate.mockResolvedValue({ id: "run-1" });
|
||||
mocks.syncItemCreate.mockResolvedValue({ id: "item-1" });
|
||||
mocks.executeRaw.mockResolvedValue(1);
|
||||
mocks.queryRaw.mockResolvedValue([{ nextNumber: 42, padding: 5, prefix: "P-" }]);
|
||||
mocks.searchProjects.mockResolvedValue([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP name",
|
||||
projectAddressCode: null,
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
}]);
|
||||
mocks.loadProjectDetails.mockResolvedValue({
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP name",
|
||||
startDate: "2026-07-01T00:00:00.000Z",
|
||||
orderValue: 42_500,
|
||||
addressCode: null,
|
||||
addressName: null,
|
||||
});
|
||||
mocks.searchUpsert.mockResolvedValue(undefined);
|
||||
mocks.publishSearchUpsertEvent.mockResolvedValue(undefined);
|
||||
mocks.auditEvent.mockResolvedValue(undefined);
|
||||
mocks.logActivity.mockResolvedValue(undefined);
|
||||
});
|
||||
|
||||
describe("KWP project ownership restore", () => {
|
||||
it("unlinks first and restores the captured local A state with optimistic locking", async () => {
|
||||
await restoreAndUnlinkKwpProject({
|
||||
tenantId: "tenant-1",
|
||||
projectId: "project-1",
|
||||
expectedBindingRevision: 4,
|
||||
expectedProjectUpdatedAt: beforeProject.updatedAt.toISOString(),
|
||||
actorUserId: "user-1",
|
||||
});
|
||||
|
||||
expect(mocks.bindingUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: { id: "binding-1", tenantId: "tenant-1", revision: 4 },
|
||||
data: expect.objectContaining({ state: "unlinked", revision: { increment: 1 } }),
|
||||
}));
|
||||
expect(mocks.projectUpdateMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
id: "project-1",
|
||||
tenantId: "tenant-1",
|
||||
updatedAt: beforeProject.updatedAt,
|
||||
archivedAt: null,
|
||||
},
|
||||
data: expect.objectContaining({
|
||||
projektname: "Local name",
|
||||
pipelineId: "pipeline-local",
|
||||
stageId: "stage-local",
|
||||
startDatum: new Date("2026-05-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 12_000,
|
||||
projektAdresseId: "address-local",
|
||||
}),
|
||||
});
|
||||
expect(mocks.bindingUpdateMany.mock.invocationCallOrder[0]).toBeLessThan(
|
||||
mocks.projectUpdateMany.mock.invocationCallOrder[0]!,
|
||||
);
|
||||
expect(mocks.auditEvent).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ action: "KWP_PROJECT_RESTORED_AND_UNLINKED" }),
|
||||
tx,
|
||||
);
|
||||
});
|
||||
|
||||
it("rejects a stale local entity instead of applying last-write-wins", async () => {
|
||||
mocks.projectUpdateMany.mockResolvedValueOnce({ count: 0 });
|
||||
await expect(restoreAndUnlinkKwpProject({
|
||||
tenantId: "tenant-1",
|
||||
projectId: "project-1",
|
||||
expectedBindingRevision: 4,
|
||||
expectedProjectUpdatedAt: beforeProject.updatedAt.toISOString(),
|
||||
actorUserId: "user-1",
|
||||
})).rejects.toEqual(expect.objectContaining({ code: "stale_write" }));
|
||||
expect(mocks.auditEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("plain unlink preserves every local project field", async () => {
|
||||
mocks.projectFindFirst.mockReset().mockResolvedValue(beforeProject);
|
||||
await unlinkKwpProject({
|
||||
tenantId: "tenant-1",
|
||||
projectId: "project-1",
|
||||
expectedBindingRevision: 4,
|
||||
actorUserId: "user-1",
|
||||
});
|
||||
expect(mocks.projectUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({ state: "unlinked" }),
|
||||
}));
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP project create and link", () => {
|
||||
const createdProject = {
|
||||
...beforeProject,
|
||||
id: "project-created",
|
||||
projektNummer: "P-00042",
|
||||
projektname: "KWP name",
|
||||
quelle: "kwp",
|
||||
pipelineId: "pipeline-kwp",
|
||||
stageId: "stage-kwp",
|
||||
startDatum: new Date("2026-07-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 42_500,
|
||||
createdAt: new Date("2026-07-23T10:00:00.000Z"),
|
||||
updatedAt: new Date("2026-07-23T10:00:00.000Z"),
|
||||
};
|
||||
|
||||
it("creates a local project number while retaining KWP projNr only as an external binding", async () => {
|
||||
mocks.bindingFindFirst.mockReset();
|
||||
mocks.projectFindFirst.mockReset().mockResolvedValue(createdProject);
|
||||
mocks.projectCreate.mockResolvedValue(createdProject);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: { kind: "create" },
|
||||
addressDecisions: [],
|
||||
})).resolves.toEqual({
|
||||
projectId: "project-created",
|
||||
created: true,
|
||||
bindingId: "binding-created",
|
||||
});
|
||||
|
||||
expect(mocks.projectCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
projektNummer: "P-00042",
|
||||
projektname: "KWP name",
|
||||
quelle: "kwp",
|
||||
}),
|
||||
});
|
||||
expect(mocks.bindingCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-created",
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
}),
|
||||
});
|
||||
expect(JSON.stringify(mocks.projectCreate.mock.calls)).not.toContain('"projektNummer":"KWP-4711"');
|
||||
expect(mocks.publishOutboxEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("links by explicit stale-safe diff and never overwrites the local project number", async () => {
|
||||
const localBefore = {
|
||||
...beforeProject,
|
||||
projektname: "Local name",
|
||||
pipelineId: "pipeline-local",
|
||||
stageId: "stage-local",
|
||||
startDatum: new Date("2026-05-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 12_000,
|
||||
};
|
||||
const linked = {
|
||||
...localBefore,
|
||||
projektname: "KWP name",
|
||||
pipelineId: "pipeline-kwp",
|
||||
stageId: "stage-kwp",
|
||||
startDatum: new Date("2026-07-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 42_500,
|
||||
updatedAt: new Date("2026-07-23T10:01:00.000Z"),
|
||||
};
|
||||
mocks.bindingFindFirst.mockReset();
|
||||
mocks.projectFindFirst
|
||||
.mockReset()
|
||||
.mockResolvedValueOnce(localBefore)
|
||||
.mockResolvedValueOnce(linked)
|
||||
.mockResolvedValueOnce(linked);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: {
|
||||
kind: "link",
|
||||
projectId: "project-1",
|
||||
expectedUpdatedAt: localBefore.updatedAt.toISOString(),
|
||||
},
|
||||
addressDecisions: [],
|
||||
})).resolves.toMatchObject({
|
||||
projectId: "project-1",
|
||||
created: false,
|
||||
});
|
||||
|
||||
expect(mocks.projectCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.projectUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: {
|
||||
id: "project-1",
|
||||
tenantId: "tenant-1",
|
||||
updatedAt: localBefore.updatedAt,
|
||||
archivedAt: null,
|
||||
},
|
||||
data: expect.not.objectContaining({ projektNummer: expect.anything() }),
|
||||
}));
|
||||
expect(mocks.bindingCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-1",
|
||||
overwrittenLocalSnapshot: expect.objectContaining({
|
||||
projektname: "Local name",
|
||||
pipelineId: "pipeline-local",
|
||||
stageId: "stage-local",
|
||||
}),
|
||||
}),
|
||||
});
|
||||
expect(mocks.publishOutboxEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("rejects a stale link diff before any local mutation", async () => {
|
||||
const local = {
|
||||
...beforeProject,
|
||||
updatedAt: new Date("2026-07-23T10:02:00.000Z"),
|
||||
};
|
||||
mocks.bindingFindFirst.mockReset();
|
||||
mocks.projectFindFirst.mockReset().mockResolvedValue(local);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: {
|
||||
kind: "link",
|
||||
projectId: "project-1",
|
||||
expectedUpdatedAt: "2026-07-23T10:00:00.000Z",
|
||||
},
|
||||
addressDecisions: [],
|
||||
})).rejects.toEqual(expect.objectContaining({ code: "stale_write" }));
|
||||
|
||||
expect(mocks.projectUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingCreate).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("replays an already bound import without creating a second project or binding", async () => {
|
||||
const activeBinding = {
|
||||
id: "binding-1",
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-1",
|
||||
state: "active",
|
||||
revision: 7,
|
||||
};
|
||||
const linked = {
|
||||
...beforeProject,
|
||||
projektname: "KWP name",
|
||||
pipelineId: "pipeline-kwp",
|
||||
stageId: "stage-kwp",
|
||||
updatedAt: new Date("2026-07-23T10:01:00.000Z"),
|
||||
};
|
||||
mocks.bindingFindFirst.mockReset();
|
||||
mocks.bindingFindUnique.mockResolvedValue(activeBinding);
|
||||
mocks.bindingFindUniqueOrThrow.mockResolvedValue({ ...activeBinding, revision: 8 });
|
||||
mocks.projectFindFirst
|
||||
.mockReset()
|
||||
.mockResolvedValueOnce(beforeProject)
|
||||
.mockResolvedValueOnce(linked)
|
||||
.mockResolvedValueOnce(linked);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: { kind: "create" },
|
||||
addressDecisions: [],
|
||||
})).resolves.toEqual({
|
||||
projectId: "project-1",
|
||||
created: false,
|
||||
bindingId: "binding-1",
|
||||
});
|
||||
|
||||
expect(mocks.projectCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: { id: "binding-1", tenantId: "tenant-1", revision: 7 },
|
||||
data: expect.objectContaining({
|
||||
state: "active",
|
||||
localId: "project-1",
|
||||
revision: { increment: 1 },
|
||||
}),
|
||||
}));
|
||||
});
|
||||
|
||||
it("turns a parallel replay into a stale write instead of duplicating data", async () => {
|
||||
mocks.bindingFindFirst.mockReset();
|
||||
mocks.bindingFindUnique.mockResolvedValue({
|
||||
id: "binding-1",
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
externalEntityType: "kwp_project",
|
||||
localEntityType: "project",
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-1",
|
||||
state: "active",
|
||||
revision: 7,
|
||||
});
|
||||
mocks.projectFindFirst
|
||||
.mockReset()
|
||||
.mockResolvedValueOnce(beforeProject)
|
||||
.mockResolvedValueOnce(beforeProject)
|
||||
.mockResolvedValueOnce(beforeProject);
|
||||
mocks.bindingUpdateMany.mockResolvedValueOnce({ count: 0 });
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: { kind: "create" },
|
||||
addressDecisions: [],
|
||||
})).rejects.toEqual(expect.objectContaining({ code: "stale_write" }));
|
||||
|
||||
expect(mocks.projectCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingCreate).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP project address preview", () => {
|
||||
const address = {
|
||||
externalAddressCode: "ADR-1",
|
||||
name: "Geerkens GmbH",
|
||||
firstName: null,
|
||||
addition: null,
|
||||
street: "Werkstraße 7",
|
||||
postalCode: "52511",
|
||||
city: "Geilenkirchen",
|
||||
country: "DE",
|
||||
invoiceEmail: "rechnung@example.test",
|
||||
email: "info@example.test",
|
||||
phone: "+49 2451 123",
|
||||
mobile: null,
|
||||
contactPeople: [{
|
||||
externalContactId: "person-1",
|
||||
firstName: "Maria",
|
||||
lastName: "Muster",
|
||||
addition: null,
|
||||
email: "maria@example.test",
|
||||
phone: null,
|
||||
mobile: "+49 170 123",
|
||||
}],
|
||||
};
|
||||
|
||||
it("loads a shared address code once and reuses its durable binding for all three roles", async () => {
|
||||
mocks.searchProjects.mockResolvedValueOnce([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP name",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: "ADR-1",
|
||||
clientAddressCode: "ADR-1",
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
}]);
|
||||
mocks.loadAddressDetails.mockResolvedValueOnce(address);
|
||||
mocks.bindingFindUnique.mockResolvedValue({
|
||||
id: "address-binding-1",
|
||||
localId: "contact-1",
|
||||
state: "active",
|
||||
});
|
||||
mocks.contactFindFirst.mockResolvedValue({
|
||||
id: "contact-1",
|
||||
kontaktTyp: "organisation",
|
||||
vorname: null,
|
||||
nachname: null,
|
||||
orgName: "Geerkens GmbH",
|
||||
primaerEmail: "info@example.test",
|
||||
adresse: {
|
||||
strasse: "Werkstraße 7",
|
||||
plz: "52511",
|
||||
ort: "Geilenkirchen",
|
||||
},
|
||||
});
|
||||
|
||||
const preview = await previewKwpProjectImport({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
});
|
||||
|
||||
expect(mocks.loadAddressDetails).toHaveBeenCalledOnce();
|
||||
expect(preview.addresses.map((entry) => entry.role)).toEqual(["project", "invoice", "client"]);
|
||||
for (const role of preview.addresses) {
|
||||
expect(role.address.externalAddressCode).toBe("ADR-1");
|
||||
expect(role.candidates).toEqual([expect.objectContaining({
|
||||
id: "contact-1",
|
||||
reason: "external_binding",
|
||||
})]);
|
||||
expect(role.address.contactPeople).toHaveLength(1);
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects duplicate role decisions before the local transaction", async () => {
|
||||
mocks.searchProjects.mockResolvedValueOnce([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP name",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
}]);
|
||||
mocks.loadAddressDetails.mockResolvedValueOnce(address);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: { kind: "create" },
|
||||
addressDecisions: [
|
||||
{ role: "project", addressCode: "ADR-1", addressContact: { kind: "create" }, primaryContact: null },
|
||||
{ role: "project", addressCode: "ADR-1", addressContact: { kind: "create" }, primaryContact: null },
|
||||
],
|
||||
})).rejects.toEqual(expect.objectContaining({ code: "address_decision_invalid" }));
|
||||
expect(mocks.transaction).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("accepts at most one selected person per role and rejects an unknown person", async () => {
|
||||
mocks.searchProjects.mockResolvedValueOnce([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP name",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
}]);
|
||||
mocks.loadAddressDetails.mockResolvedValueOnce(address);
|
||||
|
||||
await expect(importKwpProject({
|
||||
connectionId: "connection-1",
|
||||
externalProjectNumber: "KWP-4711",
|
||||
actorUserId: "user-1",
|
||||
target: { kind: "create" },
|
||||
addressDecisions: [{
|
||||
role: "project",
|
||||
addressCode: "ADR-1",
|
||||
addressContact: { kind: "create" },
|
||||
primaryContact: {
|
||||
externalContactId: "unknown-person",
|
||||
contact: { kind: "create" },
|
||||
},
|
||||
}],
|
||||
})).rejects.toEqual(expect.objectContaining({ code: "address_decision_invalid" }));
|
||||
expect(mocks.transaction).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
+645
@@ -0,0 +1,645 @@
|
||||
import { logActivity } from "@hivegrid/activity";
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import { publishOutboxEvent, type OutboxPublisherTransaction } from "@hivegrid/db/outbox";
|
||||
import type { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
import { auditEvent } from "@hivegrid/foundation";
|
||||
import { buildWorkflowTriggerOutboxEvent } from "@hivegrid/queue";
|
||||
|
||||
import {
|
||||
KwpProjectDomainError,
|
||||
loadKwpBoundProject,
|
||||
publishKwpContactSearch,
|
||||
publishKwpProjectSearch,
|
||||
syncKwpPrimaryContactChannels,
|
||||
} from "./project-domain.server.js";
|
||||
import { runKwpResourceSession } from "./resource-client.server.js";
|
||||
import {
|
||||
fingerprintKwpSnapshot,
|
||||
KWP_PROJECT_CAPABILITY,
|
||||
type KwpAddressDetails,
|
||||
type KwpProjectSearchResult,
|
||||
} from "./resource-client.js";
|
||||
|
||||
const PROJECT_ENTITY_TYPE = "kwp_project";
|
||||
const ADDRESS_ENTITY_TYPE = "kwp_address";
|
||||
const ADDRESS_CONTACT_ENTITY_TYPE = "kwp_address_contact";
|
||||
const ADDRESS_SYNC_INTERVAL_MS = 60 * 60_000;
|
||||
|
||||
type PreparedProjectSync = {
|
||||
tenantId: string;
|
||||
runId: string;
|
||||
connectionId: string;
|
||||
binding: {
|
||||
id: string;
|
||||
revision: number;
|
||||
externalId: string;
|
||||
fingerprint: string;
|
||||
missingSince: Date | null;
|
||||
};
|
||||
project: Awaited<ReturnType<typeof loadKwpBoundProject>>;
|
||||
addressBindings: Array<{
|
||||
id: string;
|
||||
revision: number;
|
||||
externalEntityType: string;
|
||||
externalId: string;
|
||||
localId: string;
|
||||
fingerprint: string;
|
||||
lastSyncedAt: Date | null;
|
||||
}>;
|
||||
};
|
||||
|
||||
type LoadedProviderSnapshot = {
|
||||
search: KwpProjectSearchResult;
|
||||
details: {
|
||||
externalProjectNumber: string;
|
||||
name: string;
|
||||
startDate: string | null;
|
||||
orderValue: number | null;
|
||||
};
|
||||
addresses: Map<string, KwpAddressDetails>;
|
||||
};
|
||||
|
||||
export type KwpProjectSyncResult = {
|
||||
readonly runId: string;
|
||||
readonly state: "synced" | "unchanged" | "missing" | "quarantined";
|
||||
readonly projectId: string;
|
||||
readonly stageChanged: boolean;
|
||||
};
|
||||
|
||||
export async function syncKwpProjectBinding(input: {
|
||||
readonly bindingId: string;
|
||||
readonly now?: Date;
|
||||
}): Promise<KwpProjectSyncResult> {
|
||||
const now = input.now ?? new Date();
|
||||
const prepared = await prepareProjectSync(normalizeId(input.bindingId), now);
|
||||
try {
|
||||
const loaded = await loadProviderSnapshot(prepared, now);
|
||||
if (!loaded) {
|
||||
const result = await markProjectMissing(prepared, now);
|
||||
await finishRun(prepared, result.state, now);
|
||||
return result;
|
||||
}
|
||||
const result = await applyProviderSnapshot(prepared, loaded, now);
|
||||
await finishRun(prepared, result.state, now);
|
||||
return result;
|
||||
} catch (error) {
|
||||
await failRun(prepared, error, now);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async function prepareProjectSync(bindingId: string, now: Date): Promise<PreparedProjectSync> {
|
||||
const tenantId = requireTenantContext();
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findFirst({
|
||||
where: {
|
||||
id: bindingId,
|
||||
tenantId,
|
||||
externalEntityType: PROJECT_ENTITY_TYPE,
|
||||
localEntityType: "project",
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
});
|
||||
if (!binding) throw new KwpProjectDomainError("project_not_found");
|
||||
const capability = await tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
},
|
||||
},
|
||||
select: { status: true },
|
||||
});
|
||||
if (capability?.status === "paused") throw new KwpProjectDomainError("capability_paused");
|
||||
const project = await loadKwpBoundProject(tx, tenantId, binding.localId);
|
||||
const addressBindings = await tx.appEntityBinding.findMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
externalEntityType: { in: [ADDRESS_ENTITY_TYPE, ADDRESS_CONTACT_ENTITY_TYPE] },
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
select: {
|
||||
id: true,
|
||||
revision: true,
|
||||
externalEntityType: true,
|
||||
externalId: true,
|
||||
localId: true,
|
||||
fingerprint: true,
|
||||
lastSyncedAt: true,
|
||||
},
|
||||
});
|
||||
const run = await tx.appSyncRun.create({
|
||||
data: {
|
||||
tenantId,
|
||||
dataConnectionId: binding.dataConnectionId,
|
||||
kind: "scheduled",
|
||||
status: "running",
|
||||
itemsTotal: 1,
|
||||
summaryText: "integrations.sync.summary.kwpProjectSyncStarted",
|
||||
startedAt: now,
|
||||
},
|
||||
});
|
||||
return {
|
||||
tenantId,
|
||||
runId: run.id,
|
||||
connectionId: binding.dataConnectionId,
|
||||
binding: {
|
||||
id: binding.id,
|
||||
revision: binding.revision,
|
||||
externalId: binding.externalId,
|
||||
fingerprint: binding.fingerprint,
|
||||
missingSince: binding.missingSince,
|
||||
},
|
||||
project,
|
||||
addressBindings,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function loadProviderSnapshot(prepared: PreparedProjectSync, now: Date): Promise<LoadedProviderSnapshot | null> {
|
||||
return runKwpResourceSession({ connectionId: prepared.connectionId }, async (resource) => {
|
||||
const matches = await resource.searchProjects(prepared.binding.externalId);
|
||||
const search = matches.find((entry) => entry.externalProjectNumber === prepared.binding.externalId);
|
||||
if (!search) return null;
|
||||
const details = await resource.loadProjectDetails(prepared.binding.externalId);
|
||||
const codes = [...new Set([
|
||||
search.projectAddressCode,
|
||||
search.invoiceAddressCode,
|
||||
search.clientAddressCode,
|
||||
].filter((value): value is string => Boolean(value)))];
|
||||
const mainBindings = new Map(
|
||||
prepared.addressBindings
|
||||
.filter((binding) => binding.externalEntityType === ADDRESS_ENTITY_TYPE)
|
||||
.map((binding) => [binding.externalId, binding]),
|
||||
);
|
||||
const addresses = new Map<string, KwpAddressDetails>();
|
||||
for (const code of codes) {
|
||||
const binding = mainBindings.get(code);
|
||||
const due = !binding?.lastSyncedAt || now.getTime() - binding.lastSyncedAt.getTime() >= ADDRESS_SYNC_INTERVAL_MS;
|
||||
if (due) addresses.set(code, await resource.loadAddressDetails(code));
|
||||
}
|
||||
return { search, details, addresses };
|
||||
});
|
||||
}
|
||||
|
||||
async function markProjectMissing(prepared: PreparedProjectSync, now: Date): Promise<KwpProjectSyncResult> {
|
||||
await getDbClient().$transaction(async (tx) => {
|
||||
const updated = await tx.appEntityBinding.updateMany({
|
||||
where: {
|
||||
id: prepared.binding.id,
|
||||
tenantId: prepared.tenantId,
|
||||
revision: prepared.binding.revision,
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
data: {
|
||||
state: "missing",
|
||||
revision: { increment: 1 },
|
||||
missingSince: prepared.binding.missingSince ?? now,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType: PROJECT_ENTITY_TYPE,
|
||||
entityId: prepared.project.id,
|
||||
externalId: prepared.binding.externalId,
|
||||
operation: "skipped",
|
||||
status: "skipped",
|
||||
errorText: "KWP-Projekt wurde nicht gefunden; lokale Daten bleiben erhalten.",
|
||||
},
|
||||
});
|
||||
await auditEvent({
|
||||
tenantId: prepared.tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_PROJECT_MARKED_MISSING",
|
||||
targetType: "project",
|
||||
targetId: prepared.project.id,
|
||||
metadata: { externalProjectNumber: prepared.binding.externalId },
|
||||
}, tx as never);
|
||||
await logActivity({
|
||||
tenantId: prepared.tenantId,
|
||||
actorKind: "system",
|
||||
activityType: "project_updated",
|
||||
subjectType: "project",
|
||||
subjectId: prepared.project.id,
|
||||
summaryText: "activity.runtime.kwp.projectMissing",
|
||||
metadata: { source: "kwp", state: "missing" },
|
||||
}, { client: tx });
|
||||
});
|
||||
return { runId: prepared.runId, state: "missing", projectId: prepared.project.id, stageChanged: false };
|
||||
}
|
||||
|
||||
async function applyProviderSnapshot(
|
||||
prepared: PreparedProjectSync,
|
||||
loaded: LoadedProviderSnapshot,
|
||||
now: Date,
|
||||
): Promise<KwpProjectSyncResult> {
|
||||
const projectSnapshot = {
|
||||
externalProjectNumber: loaded.search.externalProjectNumber,
|
||||
name: loaded.details.name,
|
||||
status: loaded.search.status,
|
||||
statusLabel: loaded.search.statusLabel,
|
||||
startDate: loaded.details.startDate,
|
||||
orderValue: loaded.details.orderValue,
|
||||
addressCodes: {
|
||||
project: loaded.search.projectAddressCode,
|
||||
invoice: loaded.search.invoiceAddressCode,
|
||||
client: loaded.search.clientAddressCode,
|
||||
},
|
||||
};
|
||||
const projectFingerprint = fingerprintKwpSnapshot(projectSnapshot);
|
||||
return getDbClient().$transaction(async (tx) => {
|
||||
const binding = await tx.appEntityBinding.findFirst({
|
||||
where: {
|
||||
id: prepared.binding.id,
|
||||
tenantId: prepared.tenantId,
|
||||
revision: prepared.binding.revision,
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
});
|
||||
if (!binding) throw new KwpProjectDomainError("stale_write");
|
||||
let project = await loadKwpBoundProject(tx, prepared.tenantId, prepared.project.id);
|
||||
if (project.updatedAt.getTime() !== prepared.project.updatedAt.getTime()) {
|
||||
throw new KwpProjectDomainError("stale_write");
|
||||
}
|
||||
|
||||
const routing = await tx.kwpProjectRouting.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_externalStatus: {
|
||||
tenantId: prepared.tenantId,
|
||||
dataConnectionId: prepared.connectionId,
|
||||
externalStatus: loaded.search.status,
|
||||
},
|
||||
},
|
||||
});
|
||||
const stage = routing
|
||||
? await tx.pipelineStage.findFirst({
|
||||
where: {
|
||||
id: routing.stageId,
|
||||
tenantId: prepared.tenantId,
|
||||
pipelineId: routing.pipelineId,
|
||||
archivedAt: null,
|
||||
pipeline: { tenantId: prepared.tenantId, archivedAt: null },
|
||||
},
|
||||
})
|
||||
: null;
|
||||
if (!routing || !stage) {
|
||||
await tx.appEntityBinding.update({
|
||||
where: { id: binding.id },
|
||||
data: { state: "quarantined", revision: { increment: 1 }, lastSeenAt: now },
|
||||
});
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType: PROJECT_ENTITY_TYPE,
|
||||
entityId: project.id,
|
||||
externalId: binding.externalId,
|
||||
operation: "skipped",
|
||||
status: "failed",
|
||||
errorText: "Für den KWP-Status fehlt eine gültige Pipeline-/Stage-Zuordnung.",
|
||||
},
|
||||
});
|
||||
return { runId: prepared.runId, state: "quarantined", projectId: project.id, stageChanged: false };
|
||||
}
|
||||
|
||||
const requiredCodes = [
|
||||
loaded.search.projectAddressCode,
|
||||
loaded.search.invoiceAddressCode,
|
||||
loaded.search.clientAddressCode,
|
||||
].filter((value): value is string => Boolean(value));
|
||||
const mainBindings = new Map(
|
||||
prepared.addressBindings
|
||||
.filter((entry) => entry.externalEntityType === ADDRESS_ENTITY_TYPE)
|
||||
.map((entry) => [entry.externalId, entry]),
|
||||
);
|
||||
if (requiredCodes.some((code) => !mainBindings.has(code))) {
|
||||
await tx.appEntityBinding.update({
|
||||
where: { id: binding.id },
|
||||
data: { state: "quarantined", revision: { increment: 1 }, lastSeenAt: now },
|
||||
});
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType: PROJECT_ENTITY_TYPE,
|
||||
entityId: project.id,
|
||||
externalId: binding.externalId,
|
||||
operation: "skipped",
|
||||
status: "failed",
|
||||
errorText: "Ein KWP-Adresscode hat sich geändert und muss bewusst zugeordnet werden.",
|
||||
},
|
||||
});
|
||||
return { runId: prepared.runId, state: "quarantined", projectId: project.id, stageChanged: false };
|
||||
}
|
||||
|
||||
for (const [code, address] of loaded.addresses) {
|
||||
const addressBinding = mainBindings.get(code);
|
||||
if (addressBinding) {
|
||||
await reconcileAddressBinding(tx, prepared, addressBinding, address, now);
|
||||
}
|
||||
const personBindings = prepared.addressBindings.filter(
|
||||
(entry) => entry.externalEntityType === ADDRESS_CONTACT_ENTITY_TYPE && entry.externalId.startsWith(`${code}:`),
|
||||
);
|
||||
for (const personBinding of personBindings) {
|
||||
const externalContactId = personBinding.externalId.slice(code.length + 1);
|
||||
const person = address.contactPeople.find((entry) => entry.externalContactId === externalContactId);
|
||||
if (!person) {
|
||||
await tx.appEntityBinding.updateMany({
|
||||
where: { id: personBinding.id, tenantId: prepared.tenantId, revision: personBinding.revision },
|
||||
data: { state: "missing", revision: { increment: 1 }, missingSince: now },
|
||||
});
|
||||
continue;
|
||||
}
|
||||
await reconcilePersonBinding(tx, prepared, personBinding, person, now);
|
||||
}
|
||||
}
|
||||
|
||||
const stageChanged = project.pipelineId !== routing.pipelineId || project.stageId !== routing.stageId;
|
||||
const projectChanged =
|
||||
projectFingerprint !== prepared.binding.fingerprint ||
|
||||
project.projektname !== loaded.details.name ||
|
||||
stageChanged ||
|
||||
project.startDatum?.toISOString() !== loaded.details.startDate ||
|
||||
decimalToNumber(project.auftragsvolumen) !== loaded.details.orderValue;
|
||||
if (projectChanged) {
|
||||
const updated = await tx.projekt.updateMany({
|
||||
where: { id: project.id, tenantId: prepared.tenantId, updatedAt: prepared.project.updatedAt, archivedAt: null },
|
||||
data: {
|
||||
projektname: loaded.details.name,
|
||||
pipelineId: routing.pipelineId,
|
||||
stageId: routing.stageId,
|
||||
startDatum: loaded.details.startDate ? new Date(loaded.details.startDate) : null,
|
||||
auftragsvolumen: loaded.details.orderValue,
|
||||
wonAt: stage.stageKind === "gewonnen" ? (project.wonAt ?? now) : null,
|
||||
lostAt: stage.stageKind === "verloren" ? (project.lostAt ?? now) : null,
|
||||
lostReasonId: null,
|
||||
undoStageChangeUntil: null,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
project = await loadKwpBoundProject(tx, prepared.tenantId, project.id);
|
||||
}
|
||||
|
||||
if (stageChanged) {
|
||||
const change = await tx.projektStageChange.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
projektId: project.id,
|
||||
fromStageId: prepared.project.stageId,
|
||||
toStageId: routing.stageId,
|
||||
changedByUserId: null,
|
||||
undoUntil: null,
|
||||
},
|
||||
});
|
||||
await publishOutboxEvent(
|
||||
tx as unknown as OutboxPublisherTransaction,
|
||||
buildWorkflowTriggerOutboxEvent({
|
||||
tenantId: prepared.tenantId,
|
||||
event: "project.stage_changed",
|
||||
data: {
|
||||
projectId: project.id,
|
||||
projectNumber: project.projektNummer,
|
||||
fromStageId: prepared.project.stageId,
|
||||
toStageId: routing.stageId,
|
||||
stageKind: stage.stageKind,
|
||||
source: "kwp",
|
||||
},
|
||||
userId: null,
|
||||
sourceId: `project:${project.id}:kwp-stage:${change.id}`,
|
||||
}),
|
||||
);
|
||||
await logActivity({
|
||||
tenantId: prepared.tenantId,
|
||||
actorKind: "system",
|
||||
activityType: "project_stage_changed",
|
||||
subjectType: "project",
|
||||
subjectId: project.id,
|
||||
summaryText: "activity.runtime.kwp.projectStageChanged",
|
||||
metadata: { source: "kwp", fromStageId: prepared.project.stageId, toStageId: routing.stageId },
|
||||
}, { client: tx });
|
||||
} else if (projectChanged || loaded.addresses.size > 0) {
|
||||
await logActivity({
|
||||
tenantId: prepared.tenantId,
|
||||
actorKind: "system",
|
||||
activityType: "project_updated",
|
||||
subjectType: "project",
|
||||
subjectId: project.id,
|
||||
summaryText: "activity.runtime.kwp.projectUpdated",
|
||||
metadata: { source: "kwp" },
|
||||
}, { client: tx });
|
||||
}
|
||||
|
||||
const bindingUpdated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision },
|
||||
data: {
|
||||
state: "active",
|
||||
normalizedSnapshot: projectSnapshot,
|
||||
fingerprint: projectFingerprint,
|
||||
revision: { increment: 1 },
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
missingSince: null,
|
||||
},
|
||||
});
|
||||
if (bindingUpdated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
await tx.appSyncItem.create({
|
||||
data: {
|
||||
tenantId: prepared.tenantId,
|
||||
syncRunId: prepared.runId,
|
||||
entityType: PROJECT_ENTITY_TYPE,
|
||||
entityId: project.id,
|
||||
externalId: binding.externalId,
|
||||
operation: projectChanged || loaded.addresses.size > 0 ? "updated" : "skipped",
|
||||
status: projectChanged || loaded.addresses.size > 0 ? "synced" : "skipped",
|
||||
},
|
||||
});
|
||||
if (projectChanged || loaded.addresses.size > 0) {
|
||||
await auditEvent({
|
||||
tenantId: prepared.tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_PROJECT_RECONCILED",
|
||||
targetType: "project",
|
||||
targetId: project.id,
|
||||
metadata: { source: "kwp", stageChanged },
|
||||
}, tx as never);
|
||||
await publishKwpProjectSearch(tx, project, binding.externalId);
|
||||
}
|
||||
return {
|
||||
runId: prepared.runId,
|
||||
state: projectChanged || loaded.addresses.size > 0 ? "synced" : "unchanged",
|
||||
projectId: project.id,
|
||||
stageChanged,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
async function reconcileAddressBinding(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedProjectSync,
|
||||
binding: PreparedProjectSync["addressBindings"][number],
|
||||
address: KwpAddressDetails,
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
const contact = await tx.kontakt.findFirst({
|
||||
where: { id: binding.localId, tenantId: prepared.tenantId, archivedAt: null },
|
||||
include: { adresse: true },
|
||||
});
|
||||
if (!contact) throw new KwpProjectDomainError("contact_not_found");
|
||||
const isPerson = Boolean(address.firstName);
|
||||
const primaryEmail = address.email ?? address.invoiceEmail;
|
||||
const primaryPhone = address.phone ?? address.mobile;
|
||||
const updated = await tx.kontakt.updateMany({
|
||||
where: { id: contact.id, tenantId: prepared.tenantId, updatedAt: contact.updatedAt },
|
||||
data: {
|
||||
kontaktTyp: isPerson ? "privatperson" : "organisation",
|
||||
vorname: isPerson ? address.firstName : null,
|
||||
nachname: isPerson ? (address.name ?? address.externalAddressCode) : null,
|
||||
orgName: isPerson ? null : (address.name ?? address.externalAddressCode),
|
||||
primaerEmail: primaryEmail,
|
||||
primaerTelefon: primaryPhone,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
await syncKwpPrimaryContactChannels(
|
||||
tx,
|
||||
prepared.tenantId,
|
||||
contact.id,
|
||||
primaryEmail,
|
||||
primaryPhone,
|
||||
);
|
||||
if (contact.adresseId) {
|
||||
const addressUpdated = await tx.adresse.updateMany({
|
||||
where: { id: contact.adresseId, tenantId: prepared.tenantId, updatedAt: contact.adresse?.updatedAt },
|
||||
data: {
|
||||
strasse: address.street,
|
||||
hausnummer: null,
|
||||
plz: address.postalCode,
|
||||
ort: address.city,
|
||||
land: address.country ?? "DE",
|
||||
},
|
||||
});
|
||||
if (addressUpdated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
}
|
||||
const bindingUpdated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision },
|
||||
data: {
|
||||
state: "active",
|
||||
normalizedSnapshot: address,
|
||||
fingerprint: fingerprintKwpSnapshot(address),
|
||||
revision: { increment: 1 },
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
missingSince: null,
|
||||
},
|
||||
});
|
||||
if (bindingUpdated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
const refreshed = await tx.kontakt.findUniqueOrThrow({ where: { id: contact.id }, include: { adresse: true } });
|
||||
await publishKwpContactSearch(tx, refreshed);
|
||||
}
|
||||
|
||||
async function reconcilePersonBinding(
|
||||
tx: Prisma.TransactionClient,
|
||||
prepared: PreparedProjectSync,
|
||||
binding: PreparedProjectSync["addressBindings"][number],
|
||||
person: KwpAddressDetails["contactPeople"][number],
|
||||
now: Date,
|
||||
): Promise<void> {
|
||||
const contact = await tx.kontakt.findFirst({
|
||||
where: { id: binding.localId, tenantId: prepared.tenantId, archivedAt: null },
|
||||
include: { adresse: true },
|
||||
});
|
||||
if (!contact) throw new KwpProjectDomainError("contact_not_found");
|
||||
const updated = await tx.kontakt.updateMany({
|
||||
where: { id: contact.id, tenantId: prepared.tenantId, updatedAt: contact.updatedAt },
|
||||
data: {
|
||||
kontaktTyp: "privatperson",
|
||||
vorname: person.firstName,
|
||||
nachname: person.lastName ?? person.externalContactId,
|
||||
orgName: null,
|
||||
primaerEmail: person.email,
|
||||
primaerTelefon: person.phone ?? person.mobile,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
await syncKwpPrimaryContactChannels(
|
||||
tx,
|
||||
prepared.tenantId,
|
||||
contact.id,
|
||||
person.email,
|
||||
person.phone ?? person.mobile,
|
||||
);
|
||||
const bindingUpdated = await tx.appEntityBinding.updateMany({
|
||||
where: { id: binding.id, tenantId: prepared.tenantId, revision: binding.revision },
|
||||
data: {
|
||||
state: "active",
|
||||
normalizedSnapshot: person,
|
||||
fingerprint: fingerprintKwpSnapshot(person),
|
||||
revision: { increment: 1 },
|
||||
lastSeenAt: now,
|
||||
lastSyncedAt: now,
|
||||
missingSince: null,
|
||||
},
|
||||
});
|
||||
if (bindingUpdated.count !== 1) throw new KwpProjectDomainError("stale_write");
|
||||
const refreshed = await tx.kontakt.findUniqueOrThrow({ where: { id: contact.id }, include: { adresse: true } });
|
||||
await publishKwpContactSearch(tx, refreshed);
|
||||
}
|
||||
|
||||
async function finishRun(prepared: PreparedProjectSync, state: KwpProjectSyncResult["state"], now: Date): Promise<void> {
|
||||
const failed = state === "quarantined" ? 1 : 0;
|
||||
await getDbClient().appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: failed ? "partial" : "completed",
|
||||
itemsTotal: 1,
|
||||
itemsSucceeded: failed ? 0 : 1,
|
||||
itemsFailed: failed,
|
||||
summaryText: runSummary(prepared.binding.externalId, state),
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
async function failRun(prepared: PreparedProjectSync, _error: unknown, now: Date): Promise<void> {
|
||||
await getDbClient().appSyncRun.updateMany({
|
||||
where: { id: prepared.runId, tenantId: prepared.tenantId, status: "running" },
|
||||
data: {
|
||||
status: "failed",
|
||||
itemsTotal: 1,
|
||||
itemsFailed: 1,
|
||||
summaryText: "integrations.sync.summary.kwpProjectFailed",
|
||||
completedAt: now,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
function runSummary(_externalId: string, state: KwpProjectSyncResult["state"]): string {
|
||||
if (state === "unchanged") return "integrations.sync.summary.kwpProjectUnchanged";
|
||||
if (state === "missing") return "integrations.sync.summary.kwpProjectMissing";
|
||||
if (state === "quarantined") return "integrations.sync.summary.kwpProjectQuarantined";
|
||||
return "integrations.sync.summary.kwpProjectUpdated";
|
||||
}
|
||||
|
||||
function decimalToNumber(value: unknown): number | null {
|
||||
if (value === null || value === undefined) return null;
|
||||
const parsed = Number(String(value));
|
||||
return Number.isFinite(parsed) ? parsed : null;
|
||||
}
|
||||
|
||||
function requireTenantContext(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpProjectDomainError("project_not_found");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
function normalizeId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{3,191}$/u.test(normalized)) throw new KwpProjectDomainError("project_not_found");
|
||||
return normalized;
|
||||
}
|
||||
+287
@@ -0,0 +1,287 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
KwpProjectDomainError: class KwpProjectDomainError extends Error {
|
||||
readonly code: string;
|
||||
constructor(code: string) {
|
||||
super(code);
|
||||
this.code = code;
|
||||
}
|
||||
},
|
||||
auditEvent: vi.fn(),
|
||||
logActivity: vi.fn(),
|
||||
publishOutboxEvent: vi.fn(),
|
||||
buildWorkflowTriggerOutboxEvent: vi.fn((input) => input),
|
||||
transaction: vi.fn(),
|
||||
runKwpResourceSession: vi.fn(),
|
||||
loadKwpBoundProject: vi.fn(),
|
||||
publishKwpContactSearch: vi.fn(),
|
||||
publishKwpProjectSearch: vi.fn(),
|
||||
bindingFindFirst: vi.fn(),
|
||||
bindingFindMany: vi.fn(),
|
||||
bindingUpdate: vi.fn(),
|
||||
bindingUpdateMany: vi.fn(),
|
||||
capabilityFindUnique: vi.fn(),
|
||||
routingFindUnique: vi.fn(),
|
||||
stageFindFirst: vi.fn(),
|
||||
stageChangeCreate: vi.fn(),
|
||||
runCreate: vi.fn(),
|
||||
runUpdateMany: vi.fn(),
|
||||
itemCreate: vi.fn(),
|
||||
projectUpdateMany: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
resourceSearch: vi.fn(),
|
||||
resourceLoadProjectDetails: vi.fn(),
|
||||
events: [] as string[],
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/activity", () => ({ logActivity: mocks.logActivity }));
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({
|
||||
$transaction: mocks.transaction,
|
||||
appSyncRun: { updateMany: mocks.runUpdateMany },
|
||||
}),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/outbox", () => ({ publishOutboxEvent: mocks.publishOutboxEvent }));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({
|
||||
getRlsExecutionContext: mocks.getRlsExecutionContext,
|
||||
}));
|
||||
vi.mock("@hivegrid/foundation", () => ({ auditEvent: mocks.auditEvent }));
|
||||
vi.mock("@hivegrid/queue", () => ({ buildWorkflowTriggerOutboxEvent: mocks.buildWorkflowTriggerOutboxEvent }));
|
||||
vi.mock("./project-domain.server.js", () => ({
|
||||
KwpProjectDomainError: mocks.KwpProjectDomainError,
|
||||
loadKwpBoundProject: mocks.loadKwpBoundProject,
|
||||
publishKwpContactSearch: mocks.publishKwpContactSearch,
|
||||
publishKwpProjectSearch: mocks.publishKwpProjectSearch,
|
||||
syncKwpPrimaryContactChannels: vi.fn(),
|
||||
}));
|
||||
vi.mock("./resource-client.server.js", () => ({
|
||||
runKwpResourceSession: mocks.runKwpResourceSession,
|
||||
}));
|
||||
|
||||
import { syncKwpProjectBinding } from "./project-sync.server.js";
|
||||
|
||||
const now = new Date("2026-07-23T13:00:00.000Z");
|
||||
const project = {
|
||||
id: "project-1",
|
||||
tenantId: "tenant-1",
|
||||
projektNummer: "P-00042",
|
||||
projektname: "Local",
|
||||
pipelineId: "pipeline-1",
|
||||
stageId: "stage-1",
|
||||
startDatum: null,
|
||||
auftragsvolumen: null,
|
||||
wonAt: null,
|
||||
lostAt: null,
|
||||
updatedAt: new Date("2026-07-23T12:00:00.000Z"),
|
||||
};
|
||||
const binding = {
|
||||
id: "binding-1",
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
externalId: "KWP-4711",
|
||||
localId: "project-1",
|
||||
revision: 7,
|
||||
fingerprint: "old",
|
||||
missingSince: null,
|
||||
};
|
||||
|
||||
const tx = {
|
||||
appEntityBinding: {
|
||||
findFirst: mocks.bindingFindFirst,
|
||||
findMany: mocks.bindingFindMany,
|
||||
update: mocks.bindingUpdate,
|
||||
updateMany: mocks.bindingUpdateMany,
|
||||
},
|
||||
kwpCapabilityState: { findUnique: mocks.capabilityFindUnique },
|
||||
kwpProjectRouting: { findUnique: mocks.routingFindUnique },
|
||||
pipelineStage: { findFirst: mocks.stageFindFirst },
|
||||
appSyncRun: { create: mocks.runCreate },
|
||||
appSyncItem: { create: mocks.itemCreate },
|
||||
projekt: { updateMany: mocks.projectUpdateMany },
|
||||
projektStageChange: { create: mocks.stageChangeCreate },
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.events.length = 0;
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1" });
|
||||
mocks.transaction.mockImplementation(async (callback) => {
|
||||
mocks.events.push("tx:start");
|
||||
const result = await callback(tx);
|
||||
mocks.events.push("tx:end");
|
||||
return result;
|
||||
});
|
||||
mocks.bindingFindFirst.mockResolvedValue(binding);
|
||||
mocks.bindingFindMany.mockResolvedValue([]);
|
||||
mocks.bindingUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.bindingUpdate.mockResolvedValue({});
|
||||
mocks.capabilityFindUnique.mockResolvedValue({ status: "active" });
|
||||
mocks.routingFindUnique.mockResolvedValue({
|
||||
pipelineId: "pipeline-2",
|
||||
stageId: "stage-2",
|
||||
});
|
||||
mocks.stageFindFirst.mockResolvedValue({
|
||||
id: "stage-2",
|
||||
name: "In Arbeit",
|
||||
stageKind: "neutral",
|
||||
});
|
||||
mocks.stageChangeCreate.mockResolvedValue({ id: "change-1" });
|
||||
mocks.loadKwpBoundProject.mockResolvedValue(project);
|
||||
mocks.runCreate.mockResolvedValue({ id: "run-1" });
|
||||
mocks.runUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.itemCreate.mockResolvedValue({ id: "item-1" });
|
||||
mocks.auditEvent.mockResolvedValue(undefined);
|
||||
mocks.logActivity.mockResolvedValue(undefined);
|
||||
mocks.resourceSearch.mockResolvedValue([]);
|
||||
mocks.resourceLoadProjectDetails.mockResolvedValue({
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP Project",
|
||||
startDate: "2026-07-01T00:00:00.000Z",
|
||||
orderValue: 42_500,
|
||||
});
|
||||
mocks.runKwpResourceSession.mockImplementation(async (_input, callback) => {
|
||||
mocks.events.push("provider");
|
||||
return callback({
|
||||
searchProjects: mocks.resourceSearch,
|
||||
loadProjectDetails: mocks.resourceLoadProjectDetails,
|
||||
loadAddressDetails: vi.fn(),
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("KWP three-phase project sync", () => {
|
||||
it("does provider I/O between short transactions and marks a missing project without deleting local data", async () => {
|
||||
const result = await syncKwpProjectBinding({ bindingId: "binding-1", now });
|
||||
|
||||
expect(result).toEqual({
|
||||
runId: "run-1",
|
||||
state: "missing",
|
||||
projectId: "project-1",
|
||||
stageChanged: false,
|
||||
});
|
||||
expect(mocks.events).toEqual([
|
||||
"tx:start",
|
||||
"tx:end",
|
||||
"provider",
|
||||
"tx:start",
|
||||
"tx:end",
|
||||
]);
|
||||
expect(mocks.bindingUpdateMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
id: "binding-1",
|
||||
tenantId: "tenant-1",
|
||||
revision: 7,
|
||||
state: { in: ["active", "missing"] },
|
||||
},
|
||||
data: {
|
||||
state: "missing",
|
||||
revision: { increment: 1 },
|
||||
missingSince: now,
|
||||
},
|
||||
});
|
||||
expect(mocks.projectUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.itemCreate).toHaveBeenCalledWith({
|
||||
data: expect.objectContaining({ operation: "skipped", status: "skipped" }),
|
||||
});
|
||||
expect(mocks.runUpdateMany).toHaveBeenLastCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({ status: "completed", itemsSucceeded: 1 }),
|
||||
}));
|
||||
});
|
||||
|
||||
it("records a failed run but performs no local partial mutation on network failure", async () => {
|
||||
mocks.runKwpResourceSession.mockImplementationOnce(async () => {
|
||||
mocks.events.push("provider");
|
||||
throw new Error("provider unavailable");
|
||||
});
|
||||
|
||||
await expect(syncKwpProjectBinding({ bindingId: "binding-1", now }))
|
||||
.rejects.toThrow("provider unavailable");
|
||||
expect(mocks.bindingUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.projectUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.itemCreate).not.toHaveBeenCalled();
|
||||
expect(mocks.runUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
data: expect.objectContaining({ status: "failed", itemsFailed: 1 }),
|
||||
}));
|
||||
});
|
||||
|
||||
it("atomically reconciles a later stage change and emits the existing event with source=kwp", async () => {
|
||||
mocks.resourceSearch.mockResolvedValueOnce([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP Project",
|
||||
projectAddressCode: null,
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
}]);
|
||||
mocks.projectUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.loadKwpBoundProject
|
||||
.mockResolvedValueOnce(project)
|
||||
.mockResolvedValueOnce(project)
|
||||
.mockResolvedValueOnce({
|
||||
...project,
|
||||
projektname: "KWP Project",
|
||||
pipelineId: "pipeline-2",
|
||||
stageId: "stage-2",
|
||||
startDatum: new Date("2026-07-01T00:00:00.000Z"),
|
||||
auftragsvolumen: 42_500,
|
||||
updatedAt: new Date("2026-07-23T13:00:00.000Z"),
|
||||
});
|
||||
|
||||
await expect(syncKwpProjectBinding({ bindingId: "binding-1", now })).resolves.toEqual({
|
||||
runId: "run-1",
|
||||
state: "synced",
|
||||
projectId: "project-1",
|
||||
stageChanged: true,
|
||||
});
|
||||
|
||||
expect(mocks.events).toEqual(["tx:start", "tx:end", "provider", "tx:start", "tx:end"]);
|
||||
expect(mocks.projectUpdateMany).toHaveBeenCalledWith(expect.objectContaining({
|
||||
where: expect.objectContaining({
|
||||
id: "project-1",
|
||||
tenantId: "tenant-1",
|
||||
updatedAt: project.updatedAt,
|
||||
}),
|
||||
data: expect.objectContaining({
|
||||
projektname: "KWP Project",
|
||||
pipelineId: "pipeline-2",
|
||||
stageId: "stage-2",
|
||||
}),
|
||||
}));
|
||||
expect(mocks.buildWorkflowTriggerOutboxEvent).toHaveBeenCalledWith(expect.objectContaining({
|
||||
event: "project.stage_changed",
|
||||
data: expect.objectContaining({
|
||||
projectId: "project-1",
|
||||
fromStageId: "stage-1",
|
||||
toStageId: "stage-2",
|
||||
source: "kwp",
|
||||
}),
|
||||
}));
|
||||
expect(mocks.publishOutboxEvent).toHaveBeenCalledOnce();
|
||||
expect(mocks.publishKwpProjectSearch).toHaveBeenCalledOnce();
|
||||
});
|
||||
|
||||
it("quarantines an unknown status without mutating the project", async () => {
|
||||
mocks.resourceSearch.mockResolvedValueOnce([{
|
||||
externalProjectNumber: "KWP-4711",
|
||||
name: "KWP Project",
|
||||
projectAddressCode: null,
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 99,
|
||||
statusLabel: "Unbekannt",
|
||||
}]);
|
||||
mocks.routingFindUnique.mockResolvedValueOnce(null);
|
||||
|
||||
await expect(syncKwpProjectBinding({ bindingId: "binding-1", now })).resolves.toEqual({
|
||||
runId: "run-1",
|
||||
state: "quarantined",
|
||||
projectId: "project-1",
|
||||
stageChanged: false,
|
||||
});
|
||||
expect(mocks.projectUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.publishOutboxEvent).not.toHaveBeenCalled();
|
||||
expect(mocks.bindingUpdateMany).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
+666
@@ -0,0 +1,666 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { createSharedStore, MemoryAdapter } from "@hivegrid/shared-store";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
transaction: vi.fn(),
|
||||
connectionFindFirst: vi.fn(),
|
||||
capabilityFindUnique: vi.fn(),
|
||||
capabilityUpsert: vi.fn(),
|
||||
capabilityUpdateMany: vi.fn(),
|
||||
reportCreate: vi.fn(),
|
||||
reportUpdateMany: vi.fn(),
|
||||
auditEvent: vi.fn(),
|
||||
decryptTenantField: vi.fn(),
|
||||
getRlsExecutionContext: vi.fn(),
|
||||
executeReadOperation: vi.fn(),
|
||||
searchProjects: vi.fn(),
|
||||
createKwpResourceTransport: vi.fn(),
|
||||
claimExpiringTokenRefreshForConnection: vi.fn(),
|
||||
executeClaimedTokenRefresh: vi.fn(),
|
||||
persistClaimedTokenRefresh: vi.fn(),
|
||||
loggerInfo: vi.fn(),
|
||||
loggerError: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@hivegrid/db/client.server", () => ({
|
||||
getDbClient: () => ({
|
||||
$transaction: mocks.transaction,
|
||||
}),
|
||||
}));
|
||||
vi.mock("@hivegrid/db/crypto/tenant-envelope.server", () => ({
|
||||
decryptTenantField: mocks.decryptTenantField,
|
||||
}));
|
||||
vi.mock("@hivegrid/db/rls-context.server", () => ({
|
||||
getRlsExecutionContext: mocks.getRlsExecutionContext,
|
||||
}));
|
||||
vi.mock("@hivegrid/foundation", () => ({
|
||||
auditEvent: mocks.auditEvent,
|
||||
}));
|
||||
vi.mock("@hivegrid/logger", () => ({
|
||||
defaultLogger: {},
|
||||
createChildLogger: () => ({
|
||||
info: mocks.loggerInfo,
|
||||
error: mocks.loggerError,
|
||||
}),
|
||||
}));
|
||||
vi.mock("../worker-tasks.server.js", () => ({
|
||||
KWP_TOKEN_REFRESH_WINDOW_MS: 2 * 60_000,
|
||||
TOKEN_REFRESH_CLAIM_MESSAGE_KEY: "integrations.health.refreshInProgress",
|
||||
TOKEN_REFRESH_RETRY_MESSAGE_KEY: "integrations.health.refreshRetryPending",
|
||||
claimExpiringTokenRefreshForConnection: mocks.claimExpiringTokenRefreshForConnection,
|
||||
executeClaimedTokenRefresh: mocks.executeClaimedTokenRefresh,
|
||||
persistClaimedTokenRefresh: mocks.persistClaimedTokenRefresh,
|
||||
}));
|
||||
vi.mock("./resource-client.js", async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import("./resource-client.js")>();
|
||||
return {
|
||||
...actual,
|
||||
createKwpResourceTransport: mocks.createKwpResourceTransport,
|
||||
};
|
||||
});
|
||||
|
||||
import {
|
||||
__resetKwpResourceSharedStoreForTests,
|
||||
__setKwpResourceSharedStoreForTests,
|
||||
executeKwpReadOperation,
|
||||
readKwpProjectCapabilityFailureCode,
|
||||
revalidateAndRecoverKwpProjectSearch,
|
||||
searchProjects,
|
||||
} from "./resource-client.server.js";
|
||||
import { KWP_PROJECT_ADAPTER_REVISION } from "./resource-client.js";
|
||||
import { KwpError } from "./client.js";
|
||||
|
||||
const credentials = {
|
||||
accessToken: "access-secret",
|
||||
refreshToken: "refresh-secret",
|
||||
expiresAt: "2099-07-23T12:00:00.000Z",
|
||||
issuer: "https://idp4.kwp-online.de/realms/kwp",
|
||||
clientId: "_extern-geerkens2",
|
||||
clientSecret: "client-secret",
|
||||
customerCode: "geerkens2",
|
||||
scopes: ["offline_access"],
|
||||
mandantBinding: { kind: "selected", code: "mandant1" },
|
||||
};
|
||||
|
||||
const tx = {
|
||||
dataConnection: { findFirst: mocks.connectionFindFirst },
|
||||
kwpCapabilityState: {
|
||||
findUnique: mocks.capabilityFindUnique,
|
||||
upsert: mocks.capabilityUpsert,
|
||||
updateMany: mocks.capabilityUpdateMany,
|
||||
},
|
||||
kwpErrorReport: {
|
||||
create: mocks.reportCreate,
|
||||
updateMany: mocks.reportUpdateMany,
|
||||
},
|
||||
};
|
||||
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
__resetKwpResourceSharedStoreForTests();
|
||||
mocks.getRlsExecutionContext.mockReturnValue({ tenantId: "tenant-1" });
|
||||
mocks.connectionFindFirst.mockResolvedValue({
|
||||
id: "connection-1",
|
||||
credentialsCiphertext: "encrypted",
|
||||
connectionStatus: "active",
|
||||
tokenExpiresAt: new Date(credentials.expiresAt),
|
||||
healthMessageKey: "integrations.kwp.health.active",
|
||||
});
|
||||
mocks.capabilityFindUnique.mockResolvedValue({ status: "active" });
|
||||
mocks.capabilityUpsert.mockResolvedValue({});
|
||||
mocks.capabilityUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.reportCreate.mockResolvedValue({});
|
||||
mocks.reportUpdateMany.mockResolvedValue({ count: 1 });
|
||||
mocks.auditEvent.mockResolvedValue(undefined);
|
||||
mocks.decryptTenantField.mockResolvedValue(JSON.stringify(credentials));
|
||||
mocks.transaction.mockImplementation((callback) => callback(tx));
|
||||
mocks.searchProjects.mockResolvedValue([]);
|
||||
mocks.executeReadOperation.mockResolvedValue({});
|
||||
mocks.claimExpiringTokenRefreshForConnection.mockResolvedValue({ state: "skipped" });
|
||||
mocks.persistClaimedTokenRefresh.mockResolvedValue({ refreshed: 1, failed: 0, retryScheduled: 0 });
|
||||
mocks.createKwpResourceTransport.mockImplementation((_credentials, options) => ({
|
||||
executeReadOperation: async (operationId: string, input: unknown) => {
|
||||
await options.consumeBudget();
|
||||
return mocks.executeReadOperation(operationId, input);
|
||||
},
|
||||
searchProjects: async (query: string) => {
|
||||
await options.consumeBudget();
|
||||
return mocks.searchProjects(query);
|
||||
},
|
||||
}));
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllEnvs();
|
||||
vi.useRealTimers();
|
||||
});
|
||||
|
||||
describe("KWP resource server boundary", () => {
|
||||
it("reuses a fresh access token without rotating KWP's one-time refresh token", async () => {
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-fresh-token", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(searchProjects({ connectionId: "connection-1", query: "Projekt" })).resolves.toEqual([]);
|
||||
|
||||
expect(mocks.claimExpiringTokenRefreshForConnection).not.toHaveBeenCalled();
|
||||
expect(mocks.createKwpResourceTransport).toHaveBeenCalledWith(credentials, expect.any(Object));
|
||||
});
|
||||
|
||||
it("rotates and persists an expiring token exactly before the resource window", async () => {
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date("2026-07-31T18:00:00.000Z"));
|
||||
vi.stubEnv("KWP_HIVEGRID_TENANT_ID", "tenant-1");
|
||||
const expiringCredentials = { ...credentials, expiresAt: "2026-07-31T18:01:00.000Z", refreshToken: "refresh-1" };
|
||||
const rotatedCredentials = { ...credentials, expiresAt: "2026-07-31T18:05:00.000Z", accessToken: "access-2", refreshToken: "refresh-2" };
|
||||
const expiringRow = {
|
||||
id: "connection-1",
|
||||
credentialsCiphertext: "encrypted-1",
|
||||
connectionStatus: "active",
|
||||
tokenExpiresAt: new Date(expiringCredentials.expiresAt),
|
||||
healthMessageKey: "integrations.kwp.health.active",
|
||||
};
|
||||
const refreshedRow = {
|
||||
...expiringRow,
|
||||
credentialsCiphertext: "encrypted-2",
|
||||
tokenExpiresAt: new Date(rotatedCredentials.expiresAt),
|
||||
};
|
||||
const claim = {
|
||||
tenantId: "tenant-1",
|
||||
connectionId: "connection-1",
|
||||
appId: "kwp",
|
||||
ownerUserId: "user-1",
|
||||
credentials: expiringCredentials,
|
||||
credentialsCiphertext: expiringRow.credentialsCiphertext,
|
||||
tokenExpiresAt: expiringRow.tokenExpiresAt,
|
||||
claimedAt: new Date("2026-07-31T18:00:00.000Z"),
|
||||
previousConnectionStatus: "active",
|
||||
previousHealthMessageKey: "integrations.kwp.health.active",
|
||||
previousLastHealthCheck: new Date("2026-07-31T17:55:00.000Z"),
|
||||
} as const;
|
||||
mocks.connectionFindFirst.mockResolvedValueOnce(expiringRow).mockResolvedValueOnce(refreshedRow);
|
||||
mocks.decryptTenantField
|
||||
.mockResolvedValueOnce(JSON.stringify(expiringCredentials))
|
||||
.mockResolvedValueOnce(JSON.stringify(rotatedCredentials));
|
||||
mocks.claimExpiringTokenRefreshForConnection.mockResolvedValueOnce({ state: "claimed", claim });
|
||||
mocks.executeClaimedTokenRefresh.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
creds: rotatedCredentials,
|
||||
expiresAt: refreshedRow.tokenExpiresAt,
|
||||
});
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-demand-token", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(searchProjects({ connectionId: "connection-1", query: "Projekt" })).resolves.toEqual([]);
|
||||
|
||||
expect(mocks.claimExpiringTokenRefreshForConnection).toHaveBeenCalledWith(
|
||||
tx,
|
||||
"tenant-1",
|
||||
"connection-1",
|
||||
expect.objectContaining({
|
||||
windowMs: 2 * 60_000,
|
||||
kwpHiveGridTenantId: "tenant-1",
|
||||
}),
|
||||
);
|
||||
expect(mocks.executeClaimedTokenRefresh).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.persistClaimedTokenRefresh).toHaveBeenCalledWith(tx, claim, {
|
||||
ok: true,
|
||||
creds: rotatedCredentials,
|
||||
expiresAt: refreshedRow.tokenExpiresAt,
|
||||
});
|
||||
expect(mocks.createKwpResourceTransport).toHaveBeenCalledWith(rotatedCredentials, expect.any(Object));
|
||||
});
|
||||
|
||||
it("makes a parallel resource caller follow the same durable rotation instead of refreshing twice", async () => {
|
||||
vi.stubEnv("KWP_HIVEGRID_TENANT_ID", "tenant-1");
|
||||
const now = Date.now();
|
||||
const expiringCredentials = { ...credentials, expiresAt: new Date(now + 60_000).toISOString(), refreshToken: "refresh-parallel-1" };
|
||||
const rotatedCredentials = {
|
||||
...credentials,
|
||||
expiresAt: new Date(now + 5 * 60_000).toISOString(),
|
||||
accessToken: "access-parallel-2",
|
||||
refreshToken: "refresh-parallel-2",
|
||||
};
|
||||
const claimedAt = new Date(now);
|
||||
const claim = {
|
||||
tenantId: "tenant-1",
|
||||
connectionId: "connection-1",
|
||||
appId: "kwp",
|
||||
ownerUserId: "user-1",
|
||||
credentials: expiringCredentials,
|
||||
credentialsCiphertext: "encrypted-parallel-1",
|
||||
tokenExpiresAt: new Date(expiringCredentials.expiresAt),
|
||||
claimedAt,
|
||||
previousConnectionStatus: "active",
|
||||
previousHealthMessageKey: "integrations.kwp.health.active",
|
||||
previousLastHealthCheck: new Date(now - 5 * 60_000),
|
||||
} as const;
|
||||
let state: "expired" | "claimed" | "fresh" = "expired";
|
||||
mocks.connectionFindFirst.mockImplementation(async () => ({
|
||||
id: "connection-1",
|
||||
credentialsCiphertext: state === "fresh" ? "encrypted-parallel-2" : "encrypted-parallel-1",
|
||||
connectionStatus: state === "claimed" ? "degraded" : "active",
|
||||
tokenExpiresAt: new Date(state === "fresh" ? rotatedCredentials.expiresAt : expiringCredentials.expiresAt),
|
||||
healthMessageKey: state === "claimed" ? "integrations.health.refreshInProgress" : "integrations.kwp.health.active",
|
||||
}));
|
||||
mocks.decryptTenantField.mockImplementation(async () => JSON.stringify(state === "fresh" ? rotatedCredentials : expiringCredentials));
|
||||
mocks.claimExpiringTokenRefreshForConnection.mockImplementation(async () => {
|
||||
if (state !== "expired") return { state: "skipped" } as const;
|
||||
state = "claimed";
|
||||
return { state: "claimed", claim } as const;
|
||||
});
|
||||
let releaseProvider!: () => void;
|
||||
const providerBarrier = new Promise<void>((resolve) => {
|
||||
releaseProvider = resolve;
|
||||
});
|
||||
mocks.executeClaimedTokenRefresh.mockImplementation(async () => {
|
||||
await providerBarrier;
|
||||
return { ok: true, creds: rotatedCredentials, expiresAt: new Date(rotatedCredentials.expiresAt) } as const;
|
||||
});
|
||||
mocks.persistClaimedTokenRefresh.mockImplementation(async () => {
|
||||
state = "fresh";
|
||||
return { refreshed: 1, failed: 0, retryScheduled: 0 };
|
||||
});
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-parallel-token", adapter: new MemoryAdapter() }));
|
||||
|
||||
const leader = searchProjects({ connectionId: "connection-1", query: "Projekt" });
|
||||
await vi.waitFor(() => expect(mocks.executeClaimedTokenRefresh).toHaveBeenCalledTimes(1));
|
||||
const follower = searchProjects({ connectionId: "connection-1", query: "Projekt" });
|
||||
await vi.waitFor(() => expect(mocks.claimExpiringTokenRefreshForConnection).toHaveBeenCalledTimes(2));
|
||||
releaseProvider();
|
||||
|
||||
await expect(Promise.all([leader, follower])).resolves.toEqual([[], []]);
|
||||
expect(mocks.executeClaimedTokenRefresh).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.persistClaimedTokenRefresh).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.createKwpResourceTransport).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.createKwpResourceTransport).toHaveBeenNthCalledWith(1, rotatedCredentials, expect.any(Object));
|
||||
expect(mocks.createKwpResourceTransport).toHaveBeenNthCalledWith(2, rotatedCredentials, expect.any(Object));
|
||||
});
|
||||
|
||||
it("retries only local persistence after KWP returned the one surviving successor", async () => {
|
||||
vi.stubEnv("KWP_HIVEGRID_TENANT_ID", "tenant-1");
|
||||
const now = Date.now();
|
||||
const expiringCredentials = { ...credentials, expiresAt: new Date(now + 60_000).toISOString(), refreshToken: "refresh-retry-1" };
|
||||
const rotatedCredentials = {
|
||||
...credentials,
|
||||
expiresAt: new Date(now + 5 * 60_000).toISOString(),
|
||||
accessToken: "access-retry-2",
|
||||
refreshToken: "refresh-retry-2",
|
||||
};
|
||||
const claim = {
|
||||
tenantId: "tenant-1",
|
||||
connectionId: "connection-1",
|
||||
appId: "kwp",
|
||||
ownerUserId: "user-1",
|
||||
credentials: expiringCredentials,
|
||||
credentialsCiphertext: "encrypted-retry-1",
|
||||
tokenExpiresAt: new Date(expiringCredentials.expiresAt),
|
||||
claimedAt: new Date(now),
|
||||
previousConnectionStatus: "active",
|
||||
previousHealthMessageKey: "integrations.kwp.health.active",
|
||||
previousLastHealthCheck: new Date(now - 5 * 60_000),
|
||||
} as const;
|
||||
let persisted = false;
|
||||
mocks.connectionFindFirst.mockImplementation(async () => ({
|
||||
id: "connection-1",
|
||||
credentialsCiphertext: persisted ? "encrypted-retry-2" : "encrypted-retry-1",
|
||||
connectionStatus: persisted ? "active" : "degraded",
|
||||
tokenExpiresAt: new Date(persisted ? rotatedCredentials.expiresAt : expiringCredentials.expiresAt),
|
||||
healthMessageKey: persisted ? "integrations.kwp.health.active" : "integrations.health.refreshInProgress",
|
||||
}));
|
||||
mocks.decryptTenantField.mockImplementation(async () => JSON.stringify(persisted ? rotatedCredentials : expiringCredentials));
|
||||
mocks.claimExpiringTokenRefreshForConnection.mockResolvedValueOnce({ state: "claimed", claim });
|
||||
mocks.executeClaimedTokenRefresh.mockResolvedValueOnce({
|
||||
ok: true,
|
||||
creds: rotatedCredentials,
|
||||
expiresAt: new Date(rotatedCredentials.expiresAt),
|
||||
});
|
||||
mocks.persistClaimedTokenRefresh
|
||||
.mockRejectedValueOnce(Object.assign(new Error(`temporary ${expiringCredentials.refreshToken}`), { code: "P2010" }))
|
||||
.mockImplementationOnce(async () => {
|
||||
persisted = true;
|
||||
return { refreshed: 1, failed: 0, retryScheduled: 0 };
|
||||
});
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-persist-retry", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(searchProjects({ connectionId: "connection-1", query: "Projekt" })).resolves.toEqual([]);
|
||||
|
||||
expect(mocks.executeClaimedTokenRefresh).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.persistClaimedTokenRefresh).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.loggerError).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ attempt: 1, maxAttempts: 6, failureClass: "database_known", errorCode: "P2010", delayMs: 250 }),
|
||||
"integrations.kwp-token-demand.persistence-failed",
|
||||
);
|
||||
expect(JSON.stringify(mocks.loggerError.mock.calls)).not.toContain(expiringCredentials.refreshToken);
|
||||
});
|
||||
|
||||
it("exposes only stable capability failure codes to route loaders", () => {
|
||||
expect(readKwpProjectCapabilityFailureCode(new KwpError("contract_drift"))).toBe("contract_drift");
|
||||
expect(readKwpProjectCapabilityFailureCode(new KwpError("capability_paused"))).toBe("capability_paused");
|
||||
expect(readKwpProjectCapabilityFailureCode(new KwpError("auth_scope_missing", 403))).toBe("auth_scope_missing");
|
||||
expect(readKwpProjectCapabilityFailureCode(new KwpError("provider_outage", 503))).toBeNull();
|
||||
expect(readKwpProjectCapabilityFailureCode(new Error("contract_drift"))).toBeNull();
|
||||
});
|
||||
|
||||
it("blocks a paused capability before constructing a provider transport", async () => {
|
||||
mocks.capabilityFindUnique.mockResolvedValueOnce({ status: "paused" });
|
||||
|
||||
await expect(
|
||||
searchProjects({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "capability_paused" });
|
||||
|
||||
expect(mocks.createKwpResourceTransport).not.toHaveBeenCalled();
|
||||
expect(mocks.decryptTenantField).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("recovers a sticky response-schema pause only after the current search response validates", async () => {
|
||||
const fingerprint = "a".repeat(64);
|
||||
const result = {
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Projekt 100",
|
||||
projectAddressCode: null,
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
};
|
||||
mocks.capabilityFindUnique
|
||||
.mockResolvedValueOnce({ status: "paused" })
|
||||
.mockResolvedValueOnce({
|
||||
id: "capability-1",
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
approvedFingerprint: fingerprint,
|
||||
observedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 7,
|
||||
});
|
||||
mocks.searchProjects.mockResolvedValueOnce([result]);
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-recovery", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
revalidateAndRecoverKwpProjectSearch({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).resolves.toEqual([result]);
|
||||
|
||||
expect(mocks.capabilityUpdateMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
id: "capability-1",
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
approvedFingerprint: fingerprint,
|
||||
observedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 7,
|
||||
},
|
||||
data: {
|
||||
status: "active",
|
||||
reasonCode: null,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: null,
|
||||
lastCheckedAt: expect.any(Date),
|
||||
},
|
||||
});
|
||||
expect(mocks.reportUpdateMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
code: "kwp.project.contract_drift",
|
||||
resolvedAt: null,
|
||||
},
|
||||
data: { resolvedAt: expect.any(Date) },
|
||||
});
|
||||
expect(mocks.auditEvent).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
action: "KWP_RESPONSE_SCHEMA_RECOVERED",
|
||||
metadata: {
|
||||
capability: "project-import",
|
||||
approvedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
}),
|
||||
tx
|
||||
);
|
||||
});
|
||||
|
||||
it.each([
|
||||
{
|
||||
name: "semantic fingerprint drift",
|
||||
namespace: "semantic-drift",
|
||||
state: {
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
approvedFingerprint: "a".repeat(64),
|
||||
observedFingerprint: "b".repeat(64),
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "provider permission failure",
|
||||
namespace: "provider-permission",
|
||||
state: {
|
||||
reasonCode: "kwp.project.missing_provider_permission",
|
||||
approvedFingerprint: "a".repeat(64),
|
||||
observedFingerprint: "a".repeat(64),
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
},
|
||||
])("keeps $name paused after a valid reprobe", async ({ namespace, state }) => {
|
||||
mocks.capabilityFindUnique
|
||||
.mockResolvedValueOnce({ status: "paused" })
|
||||
.mockResolvedValueOnce({
|
||||
id: "capability-1",
|
||||
status: "paused",
|
||||
revision: 7,
|
||||
...state,
|
||||
});
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: `kwp-resource-server-no-recovery-${namespace}`, adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
revalidateAndRecoverKwpProjectSearch({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "capability_paused" });
|
||||
|
||||
expect(mocks.capabilityUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.reportUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.auditEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does not recover when the response still fails current adapter validation", async () => {
|
||||
mocks.capabilityFindUnique.mockResolvedValueOnce({ status: "paused" });
|
||||
mocks.searchProjects.mockRejectedValueOnce(new KwpError("contract_drift"));
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-invalid-reprobe", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
revalidateAndRecoverKwpProjectSearch({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "contract_drift" });
|
||||
|
||||
expect(mocks.capabilityUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.reportUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.auditEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("keeps the capability paused when the optimistic recovery write is stale", async () => {
|
||||
const fingerprint = "a".repeat(64);
|
||||
mocks.capabilityFindUnique
|
||||
.mockResolvedValueOnce({ status: "paused" })
|
||||
.mockResolvedValueOnce({
|
||||
id: "capability-1",
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
approvedFingerprint: fingerprint,
|
||||
observedFingerprint: fingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 7,
|
||||
});
|
||||
mocks.capabilityUpdateMany.mockResolvedValueOnce({ count: 0 });
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-stale-recovery", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
revalidateAndRecoverKwpProjectSearch({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "capability_paused" });
|
||||
|
||||
expect(mocks.reportUpdateMany).not.toHaveBeenCalled();
|
||||
expect(mocks.auditEvent).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("pauses only project import on 403 and persists a token-free diagnostic", async () => {
|
||||
mocks.searchProjects.mockRejectedValueOnce(new KwpError("auth_scope_missing", 403));
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-403", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
searchProjects({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "auth_scope_missing", httpStatus: 403 });
|
||||
|
||||
expect(mocks.capabilityUpsert).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
},
|
||||
},
|
||||
update: expect.objectContaining({
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.missing_provider_permission",
|
||||
}),
|
||||
})
|
||||
);
|
||||
const report = mocks.reportCreate.mock.calls[0]?.[0];
|
||||
expect(report).toEqual({
|
||||
data: expect.objectContaining({
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "project-import",
|
||||
code: "kwp.project.missing_provider_permission",
|
||||
redactedDetails: {
|
||||
adapterRevision: expect.any(String),
|
||||
httpClass: "forbidden",
|
||||
},
|
||||
}),
|
||||
});
|
||||
expect(JSON.stringify(report)).not.toContain(credentials.accessToken);
|
||||
expect(JSON.stringify(report)).not.toContain(credentials.refreshToken);
|
||||
});
|
||||
|
||||
it("gates and pauses only the exact scoped capability selected by an operation id", async () => {
|
||||
mocks.executeReadOperation.mockRejectedValueOnce(new KwpError("auth_scope_missing", 403));
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-scoped-403", adapter: new MemoryAdapter() }));
|
||||
|
||||
await expect(
|
||||
executeKwpReadOperation({
|
||||
connectionId: "connection-1",
|
||||
operationId: "archivExternalGetSetup",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "auth_scope_missing", httpStatus: 403 });
|
||||
|
||||
expect(mocks.capabilityFindUnique).toHaveBeenCalledWith({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "kwp-scoped-archive",
|
||||
},
|
||||
},
|
||||
select: { status: true },
|
||||
});
|
||||
expect(mocks.capabilityUpsert).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: "tenant-1",
|
||||
dataConnectionId: "connection-1",
|
||||
capability: "kwp-scoped-archive",
|
||||
},
|
||||
},
|
||||
update: expect.objectContaining({
|
||||
status: "paused",
|
||||
reasonCode: "kwp.archive.missing_provider_permission",
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("shares one OAuth-client budget across connections and waits for reset without provider retry loops", async () => {
|
||||
vi.useFakeTimers();
|
||||
vi.setSystemTime(new Date("2026-08-01T12:00:00.000Z"));
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-budget", adapter: new MemoryAdapter() }));
|
||||
mocks.connectionFindFirst.mockImplementation(async (args: { where: { id: string } }) => ({
|
||||
id: args.where.id,
|
||||
credentialsCiphertext: `encrypted-${args.where.id}`,
|
||||
connectionStatus: "active",
|
||||
tokenExpiresAt: new Date(credentials.expiresAt),
|
||||
healthMessageKey: "integrations.kwp.health.active",
|
||||
}));
|
||||
mocks.decryptTenantField.mockImplementation(async (_tenantId: string, ciphertext: string) =>
|
||||
JSON.stringify({
|
||||
...credentials,
|
||||
clientId: "shared-oauth-client",
|
||||
customerCode: ciphertext.endsWith("connection-2") ? "customer-two" : "customer-one",
|
||||
})
|
||||
);
|
||||
|
||||
for (let request = 0; request < 50; request += 1) {
|
||||
await expect(
|
||||
searchProjects({
|
||||
connectionId: request % 2 === 0 ? "connection-1" : "connection-2",
|
||||
query: "Projekt",
|
||||
})
|
||||
).resolves.toEqual([]);
|
||||
}
|
||||
let settled = false;
|
||||
const waitingRequest = searchProjects({
|
||||
connectionId: "connection-2",
|
||||
query: "Projekt",
|
||||
}).then((result) => {
|
||||
settled = true;
|
||||
return result;
|
||||
});
|
||||
await vi.advanceTimersByTimeAsync(0);
|
||||
|
||||
expect(settled).toBe(false);
|
||||
expect(mocks.searchProjects).toHaveBeenCalledTimes(50);
|
||||
expect(mocks.loggerInfo).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ delayMs: 60_100, waitCycle: 1, budgetPerMinute: 50 }),
|
||||
"integrations.kwp-resource-budget.waiting"
|
||||
);
|
||||
|
||||
await vi.advanceTimersByTimeAsync(60_100);
|
||||
await expect(waitingRequest).resolves.toEqual([]);
|
||||
|
||||
expect(mocks.searchProjects).toHaveBeenCalledTimes(51);
|
||||
expect(mocks.capabilityUpsert).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fails closed before provider I/O when the shared budget store is unavailable", async () => {
|
||||
const adapter = new MemoryAdapter();
|
||||
vi.spyOn(adapter, "eval").mockRejectedValueOnce(new Error("redis unavailable"));
|
||||
__setKwpResourceSharedStoreForTests(createSharedStore({ namespace: "kwp-resource-server-budget-outage", adapter }));
|
||||
|
||||
await expect(
|
||||
searchProjects({
|
||||
connectionId: "connection-1",
|
||||
query: "Projekt",
|
||||
})
|
||||
).rejects.toMatchObject({ code: "rate_limit_exceeded", httpStatus: 429 });
|
||||
|
||||
expect(mocks.searchProjects).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
+621
@@ -0,0 +1,621 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { resolveKwpRuntimeEnv, resolveSharedRedisUrl } from "@hivegrid/config";
|
||||
import { getDbClient } from "@hivegrid/db/client.server";
|
||||
import { decryptTenantField } from "@hivegrid/db/crypto/tenant-envelope.server";
|
||||
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
|
||||
import { auditEvent } from "@hivegrid/foundation";
|
||||
import { createChildLogger, defaultLogger } from "@hivegrid/logger";
|
||||
import {
|
||||
createFixedWindowRateLimiter,
|
||||
createSharedStore,
|
||||
type FixedWindowDecision,
|
||||
type FixedWindowRateLimiter,
|
||||
type SharedStore,
|
||||
} from "@hivegrid/shared-store";
|
||||
|
||||
import {
|
||||
KWP_TOKEN_REFRESH_WINDOW_MS,
|
||||
TOKEN_REFRESH_CLAIM_MESSAGE_KEY,
|
||||
TOKEN_REFRESH_RETRY_MESSAGE_KEY,
|
||||
claimExpiringTokenRefreshForConnection,
|
||||
executeClaimedTokenRefresh,
|
||||
persistClaimedTokenRefresh,
|
||||
type TokenRefreshProviderResult,
|
||||
} from "../worker-tasks.server.js";
|
||||
|
||||
import {
|
||||
createKwpResourceTransport,
|
||||
getKwpScopedCapabilityKey,
|
||||
KWP_PROJECT_ADAPTER_REVISION,
|
||||
KWP_PROJECT_CAPABILITY,
|
||||
KWP_RESOURCE_BUDGET_PER_MINUTE,
|
||||
type KwpAddressDetails,
|
||||
type KwpProjectDetails,
|
||||
type KwpProjectSearchResult,
|
||||
type KwpSemanticContract,
|
||||
} from "./resource-client.js";
|
||||
import { getKwpScopedOperation, type KwpCapabilitySemanticContract, type KwpOperationInput, type KwpReadOperationId } from "./scoped-contract.js";
|
||||
|
||||
export { KWP_PROJECT_CAPABILITY } from "./resource-client.js";
|
||||
import { KWP_APP_ID, KwpError, type KwpCredentials } from "./client.js";
|
||||
|
||||
type CredentialSnapshot = {
|
||||
readonly tenantId: string;
|
||||
readonly connectionId: string;
|
||||
readonly credentials: KwpCredentials;
|
||||
readonly connectionStatus: string;
|
||||
readonly tokenExpiresAt: Date;
|
||||
readonly healthMessageKey: string | null;
|
||||
};
|
||||
|
||||
let sharedStore: SharedStore | null = null;
|
||||
const kwpTokenLogger = createChildLogger(defaultLogger, { component: "integrations", scope: "kwp-token-demand" });
|
||||
const kwpResourceBudgetLogger = createChildLogger(defaultLogger, { component: "integrations", scope: "kwp-resource-budget" });
|
||||
const KWP_REFRESH_PERSIST_RETRY_DELAYS_MS = [250, 1_000, 5_000, 15_000, 30_000] as const;
|
||||
const KWP_REFRESH_FOLLOWER_POLL_DELAYS_MS = [50, 100, 250, 500, 1_000, 2_000, 3_000, 5_000] as const;
|
||||
const KWP_RESOURCE_BUDGET_WINDOW_SECONDS = 60;
|
||||
const KWP_RESOURCE_BUDGET_RESET_PADDING_MS = 100;
|
||||
|
||||
export type KwpProjectCapabilityFailureCode = "auth_scope_missing" | "capability_paused" | "contract_drift";
|
||||
|
||||
/** Exposes only the stable, redacted capability state needed by route loaders.
|
||||
* Provider payloads and credential material never cross this boundary. */
|
||||
export function readKwpProjectCapabilityFailureCode(error: unknown): KwpProjectCapabilityFailureCode | null {
|
||||
if (!(error instanceof KwpError)) return null;
|
||||
if (error.code === "auth_scope_missing" || error.code === "capability_paused" || error.code === "contract_drift") {
|
||||
return error.code;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export async function searchProjects(input: { readonly connectionId: string; readonly query: string }): Promise<KwpProjectSearchResult[]> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.searchProjects(input.query));
|
||||
}
|
||||
|
||||
export async function listProjectNumbers(input: { readonly connectionId: string }): Promise<string[]> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.listProjectNumbers());
|
||||
}
|
||||
|
||||
/** Reprobes a response-schema pause through the current adapter. Recovery is
|
||||
* allowed only while OpenAPI still matches the approved fingerprint; genuine
|
||||
* semantic drift and provider-permission failures remain paused. */
|
||||
export async function revalidateAndRecoverKwpProjectSearch(input: {
|
||||
readonly connectionId: string;
|
||||
readonly query: string;
|
||||
}): Promise<KwpProjectSearchResult[]> {
|
||||
const connectionId = normalizeConnectionId(input.connectionId);
|
||||
const tenantId = requireTenantId();
|
||||
const results = await withKwpResource(connectionId, (resource) => resource.searchProjects(input.query), {
|
||||
allowPaused: true,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
});
|
||||
const now = new Date();
|
||||
const recovered = await getDbClient().$transaction(async (tx) => {
|
||||
const state = await tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
},
|
||||
},
|
||||
});
|
||||
if (state?.status === "active") return true;
|
||||
if (
|
||||
!state ||
|
||||
state.reasonCode !== "kwp.project.contract_drift" ||
|
||||
!state.approvedFingerprint ||
|
||||
state.observedFingerprint !== state.approvedFingerprint ||
|
||||
state.adapterRevision !== KWP_PROJECT_ADAPTER_REVISION
|
||||
) {
|
||||
return false;
|
||||
}
|
||||
const updated = await tx.kwpCapabilityState.updateMany({
|
||||
where: {
|
||||
id: state.id,
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
status: "paused",
|
||||
reasonCode: "kwp.project.contract_drift",
|
||||
approvedFingerprint: state.approvedFingerprint,
|
||||
observedFingerprint: state.approvedFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: state.revision,
|
||||
},
|
||||
data: {
|
||||
status: "active",
|
||||
reasonCode: null,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: null,
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
});
|
||||
if (updated.count !== 1) return false;
|
||||
await tx.kwpErrorReport.updateMany({
|
||||
where: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
code: "kwp.project.contract_drift",
|
||||
resolvedAt: null,
|
||||
},
|
||||
data: { resolvedAt: now },
|
||||
});
|
||||
await auditEvent(
|
||||
{
|
||||
tenantId,
|
||||
actorType: "system",
|
||||
action: "KWP_RESPONSE_SCHEMA_RECOVERED",
|
||||
targetType: "DataConnection",
|
||||
targetId: connectionId,
|
||||
metadata: {
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
approvedFingerprint: state.approvedFingerprint,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
},
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
return true;
|
||||
});
|
||||
if (!recovered) throw new KwpError("capability_paused");
|
||||
return results;
|
||||
}
|
||||
|
||||
/** One short credential-snapshot transaction followed by typed provider I/O.
|
||||
* The callback never receives URL, token, mandant or raw credential material. */
|
||||
export async function runKwpResourceSession<T>(
|
||||
input: { readonly connectionId: string; readonly allowPaused?: boolean },
|
||||
operation: (resource: ReturnType<typeof createKwpResourceTransport>) => Promise<T>
|
||||
): Promise<T> {
|
||||
return withKwpResource(input.connectionId, operation, {
|
||||
allowPaused: input.allowPaused,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
});
|
||||
}
|
||||
|
||||
/** Exact operation-id boundary for the complete licensed read surface. Fachcode
|
||||
* cannot provide a provider URL, path, token, mandant or mutation id. */
|
||||
export async function executeKwpReadOperation<T = unknown>(input: {
|
||||
readonly connectionId: string;
|
||||
readonly operationId: KwpReadOperationId;
|
||||
readonly operationInput?: KwpOperationInput;
|
||||
}): Promise<T> {
|
||||
const operation = getKwpScopedOperation(input.operationId);
|
||||
return withKwpResource(input.connectionId, (resource) => resource.executeReadOperation<T>(input.operationId, input.operationInput), {
|
||||
capability: getKwpScopedCapabilityKey(operation.capability),
|
||||
});
|
||||
}
|
||||
|
||||
export async function loadProjectDetails(input: { readonly connectionId: string; readonly projectNumber: string }): Promise<KwpProjectDetails> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.loadProjectDetails(input.projectNumber));
|
||||
}
|
||||
|
||||
export async function loadAddressDetails(input: { readonly connectionId: string; readonly addressCode: string }): Promise<KwpAddressDetails> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.loadAddressDetails(input.addressCode));
|
||||
}
|
||||
|
||||
export async function loadProjectSemanticContract(input: { readonly connectionId: string }): Promise<KwpSemanticContract> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.loadSemanticContract(), { allowPaused: true });
|
||||
}
|
||||
|
||||
export async function loadScopedSemanticContracts(input: { readonly connectionId: string }): Promise<readonly KwpCapabilitySemanticContract[]> {
|
||||
return withKwpResource(input.connectionId, (resource) => resource.loadScopedSemanticContracts(), { allowPaused: true, capability: KWP_PROJECT_CAPABILITY });
|
||||
}
|
||||
|
||||
/** Operator/tenant-admin approval proof: the current adapter must validate a
|
||||
* real, explicitly selected read-only response while the capability is paused. */
|
||||
export async function validateProjectAdapterAgainstCurrentContract(input: {
|
||||
readonly connectionId: string;
|
||||
readonly externalProjectNumber: string;
|
||||
}): Promise<void> {
|
||||
await withKwpResource(
|
||||
input.connectionId,
|
||||
async (resource) => {
|
||||
const matches = await resource.searchProjects(input.externalProjectNumber);
|
||||
const selected = matches.find((entry) => entry.externalProjectNumber === input.externalProjectNumber.trim());
|
||||
if (!selected) throw new KwpError("resource_not_found", 404);
|
||||
await resource.loadProjectDetails(selected.externalProjectNumber);
|
||||
const addressCodes = [
|
||||
...new Set([selected.projectAddressCode, selected.invoiceAddressCode, selected.clientAddressCode].filter((value): value is string => Boolean(value))),
|
||||
];
|
||||
for (const addressCode of addressCodes) await resource.loadAddressDetails(addressCode);
|
||||
},
|
||||
{ allowPaused: true }
|
||||
);
|
||||
}
|
||||
|
||||
async function withKwpResource<T>(
|
||||
connectionId: string,
|
||||
operation: (resource: ReturnType<typeof createKwpResourceTransport>) => Promise<T>,
|
||||
options: { allowPaused?: boolean; capability?: string } = {}
|
||||
): Promise<T> {
|
||||
const capability = options.capability ?? KWP_PROJECT_CAPABILITY;
|
||||
const snapshot = await ensureKwpCredentialSnapshot({
|
||||
connectionId: normalizeConnectionId(connectionId),
|
||||
capability,
|
||||
...(options.allowPaused === undefined ? {} : { allowPaused: options.allowPaused }),
|
||||
});
|
||||
const resource = createKwpResourceTransport(snapshot.credentials, {
|
||||
consumeBudget: () => consumeKwpResourceBudget(snapshot.credentials.clientId),
|
||||
});
|
||||
try {
|
||||
return await operation(resource);
|
||||
} catch (error) {
|
||||
if (error instanceof KwpError && (error.code === "contract_drift" || error.code === "auth_scope_missing")) {
|
||||
await pauseCapability(snapshot, capability, error.code);
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Demand-driven KWP access-token gate. Every real resource session and the
|
||||
* scheduled health probe passes through this boundary. The durable claim in
|
||||
* worker-tasks serializes web and worker replicas before KWP's one-time
|
||||
* refresh token is consumed; followers wait for the persisted successor
|
||||
* instead of starting a second rotation.
|
||||
*/
|
||||
export async function ensureKwpAccessTokenForConnection(input: {
|
||||
readonly connectionId: string;
|
||||
readonly allowPaused?: boolean;
|
||||
readonly capability?: string;
|
||||
}): Promise<void> {
|
||||
await ensureKwpCredentialSnapshot(input);
|
||||
}
|
||||
|
||||
async function ensureKwpCredentialSnapshot(input: {
|
||||
readonly connectionId: string;
|
||||
readonly allowPaused?: boolean;
|
||||
readonly capability?: string;
|
||||
}): Promise<CredentialSnapshot> {
|
||||
const connectionId = normalizeConnectionId(input.connectionId);
|
||||
const options = {
|
||||
...(input.allowPaused === undefined ? {} : { allowPaused: input.allowPaused }),
|
||||
...(input.capability === undefined ? {} : { capability: input.capability }),
|
||||
};
|
||||
const initial = await loadCredentialSnapshot(connectionId, options);
|
||||
if (isKwpAccessTokenFresh(initial, new Date())) return initial;
|
||||
|
||||
const db = getDbClient();
|
||||
const claimAt = new Date();
|
||||
const { hiveGridTenantId } = resolveKwpRuntimeEnv();
|
||||
const claimResult = await db.$transaction((tx) =>
|
||||
claimExpiringTokenRefreshForConnection(
|
||||
tx as unknown as Parameters<typeof claimExpiringTokenRefreshForConnection>[0],
|
||||
initial.tenantId,
|
||||
connectionId,
|
||||
{
|
||||
now: claimAt,
|
||||
claimAt,
|
||||
windowMs: KWP_TOKEN_REFRESH_WINDOW_MS,
|
||||
// Preserve the process-wide Geerkens pilot boundary in addition to
|
||||
// the caller's exact RLS tenant context and entitlement check.
|
||||
...(hiveGridTenantId ? { kwpHiveGridTenantId: hiveGridTenantId } : {}),
|
||||
},
|
||||
),
|
||||
);
|
||||
|
||||
if (claimResult.state === "failed") {
|
||||
kwpTokenLogger.info(
|
||||
{ tenantId: initial.tenantId, connectionId, reason: claimResult.reason },
|
||||
"integrations.kwp-token-demand.claim-failed",
|
||||
);
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
if (claimResult.state === "claimed") {
|
||||
const providerResult = await executeClaimedTokenRefresh(claimResult.claim);
|
||||
if (!providerResult.ok) {
|
||||
kwpTokenLogger.info(
|
||||
{
|
||||
tenantId: initial.tenantId,
|
||||
connectionId,
|
||||
reason: providerResult.reason,
|
||||
disposition: providerResult.disposition,
|
||||
httpStatus: providerResult.httpStatus ?? null,
|
||||
diagnosticCode: providerResult.diagnosticCode ?? null,
|
||||
},
|
||||
"integrations.kwp-token-demand.provider-failed",
|
||||
);
|
||||
}
|
||||
const persisted = await persistDemandRefreshWithRetry({
|
||||
tenantId: initial.tenantId,
|
||||
connectionId,
|
||||
claim: claimResult.claim,
|
||||
providerResult,
|
||||
});
|
||||
kwpTokenLogger.info(
|
||||
{
|
||||
tenantId: initial.tenantId,
|
||||
connectionId,
|
||||
outcome:
|
||||
persisted.refreshed === 1
|
||||
? "refreshed"
|
||||
: persisted.retryScheduled === 1
|
||||
? "retry_scheduled"
|
||||
: persisted.failed === 1
|
||||
? "reconnect_required"
|
||||
: "already_resolved_or_raced",
|
||||
...(providerResult.ok ? { tokenExpiresAt: providerResult.expiresAt.toISOString() } : {}),
|
||||
},
|
||||
"integrations.kwp-token-demand.connection-completed",
|
||||
);
|
||||
if (!providerResult.ok) {
|
||||
throw new KwpError(
|
||||
providerResult.reason === "unexpected" ? "unknown" : providerResult.reason,
|
||||
providerResult.httpStatus,
|
||||
providerResult.diagnosticCode,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
return waitForDemandRefreshFollower(connectionId, options);
|
||||
}
|
||||
|
||||
function isKwpAccessTokenFresh(snapshot: CredentialSnapshot, now: Date): boolean {
|
||||
return (
|
||||
snapshot.healthMessageKey !== TOKEN_REFRESH_CLAIM_MESSAGE_KEY &&
|
||||
snapshot.healthMessageKey !== TOKEN_REFRESH_RETRY_MESSAGE_KEY &&
|
||||
snapshot.tokenExpiresAt.getTime() > now.getTime() + KWP_TOKEN_REFRESH_WINDOW_MS
|
||||
);
|
||||
}
|
||||
|
||||
async function waitForDemandRefreshFollower(
|
||||
connectionId: string,
|
||||
options: { allowPaused?: boolean; capability?: string },
|
||||
): Promise<CredentialSnapshot> {
|
||||
for (const delayMs of KWP_REFRESH_FOLLOWER_POLL_DELAYS_MS) {
|
||||
const snapshot = await loadCredentialSnapshot(connectionId, options);
|
||||
if (isKwpAccessTokenFresh(snapshot, new Date())) return snapshot;
|
||||
if (snapshot.healthMessageKey === TOKEN_REFRESH_RETRY_MESSAGE_KEY) {
|
||||
throw new KwpError("provider_outage");
|
||||
}
|
||||
if (snapshot.healthMessageKey !== TOKEN_REFRESH_CLAIM_MESSAGE_KEY) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
await wait(delayMs);
|
||||
}
|
||||
throw new KwpError("provider_outage");
|
||||
}
|
||||
|
||||
async function persistDemandRefreshWithRetry(input: {
|
||||
readonly tenantId: string;
|
||||
readonly connectionId: string;
|
||||
readonly claim: Parameters<typeof persistClaimedTokenRefresh>[1];
|
||||
readonly providerResult: TokenRefreshProviderResult;
|
||||
}): Promise<Awaited<ReturnType<typeof persistClaimedTokenRefresh>>> {
|
||||
const db = getDbClient();
|
||||
const maxAttempts = KWP_REFRESH_PERSIST_RETRY_DELAYS_MS.length + 1;
|
||||
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
|
||||
try {
|
||||
return await db.$transaction((tx) =>
|
||||
persistClaimedTokenRefresh(
|
||||
tx as unknown as Parameters<typeof persistClaimedTokenRefresh>[0],
|
||||
input.claim,
|
||||
input.providerResult,
|
||||
),
|
||||
);
|
||||
} catch (error) {
|
||||
const delayMs = KWP_REFRESH_PERSIST_RETRY_DELAYS_MS[attempt - 1];
|
||||
kwpTokenLogger.error(
|
||||
{
|
||||
tenantId: input.tenantId,
|
||||
connectionId: input.connectionId,
|
||||
stage: "persist",
|
||||
attempt,
|
||||
maxAttempts,
|
||||
retryScheduled: delayMs !== undefined,
|
||||
...classifyKwpRefreshPersistenceFailure(error),
|
||||
...(delayMs === undefined ? {} : { delayMs }),
|
||||
},
|
||||
"integrations.kwp-token-demand.persistence-failed",
|
||||
);
|
||||
if (delayMs === undefined) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
await wait(delayMs);
|
||||
}
|
||||
}
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
function classifyKwpRefreshPersistenceFailure(error: unknown): {
|
||||
failureClass: "database_known" | "database_unavailable" | "database_validation" | "timeout" | "unknown";
|
||||
errorCode?: string;
|
||||
} {
|
||||
if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && /^P\d{4}$/u.test(error.code)) {
|
||||
return { failureClass: "database_known", errorCode: error.code };
|
||||
}
|
||||
const errorName = error instanceof Error ? error.name : null;
|
||||
if (errorName === "PrismaClientInitializationError" || errorName === "PrismaClientRustPanicError") {
|
||||
return { failureClass: "database_unavailable" };
|
||||
}
|
||||
if (errorName === "PrismaClientValidationError") return { failureClass: "database_validation" };
|
||||
if (errorName === "AbortError" || errorName === "TimeoutError") return { failureClass: "timeout" };
|
||||
return { failureClass: "unknown" };
|
||||
}
|
||||
|
||||
function wait(delayMs: number): Promise<void> {
|
||||
return new Promise((resolve) => setTimeout(resolve, delayMs));
|
||||
}
|
||||
|
||||
async function loadCredentialSnapshot(connectionId: string, options: { allowPaused?: boolean; capability?: string } = {}): Promise<CredentialSnapshot> {
|
||||
const capabilityKey = options.capability ?? KWP_PROJECT_CAPABILITY;
|
||||
const tenantId = requireTenantId();
|
||||
|
||||
const db = getDbClient();
|
||||
return db.$transaction(async (tx) => {
|
||||
const [connection, capability] = await Promise.all([
|
||||
tx.dataConnection.findFirst({
|
||||
where: {
|
||||
id: connectionId,
|
||||
tenantId,
|
||||
appId: KWP_APP_ID,
|
||||
archivedAt: null,
|
||||
connectionStatus: { in: ["active", "degraded"] },
|
||||
},
|
||||
select: {
|
||||
id: true,
|
||||
credentialsCiphertext: true,
|
||||
connectionStatus: true,
|
||||
tokenExpiresAt: true,
|
||||
healthMessageKey: true,
|
||||
},
|
||||
}),
|
||||
tx.kwpCapabilityState.findUnique({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId,
|
||||
dataConnectionId: connectionId,
|
||||
capability: capabilityKey,
|
||||
},
|
||||
},
|
||||
select: { status: true },
|
||||
}),
|
||||
]);
|
||||
if (!connection?.credentialsCiphertext || !connection.tokenExpiresAt) throw new KwpError("invalid_credentials");
|
||||
if (!options.allowPaused && capability?.status === "paused") throw new KwpError("capability_paused");
|
||||
|
||||
let credentials: unknown;
|
||||
try {
|
||||
credentials = JSON.parse(await decryptTenantField(tenantId, connection.credentialsCiphertext, { client: tx as never }));
|
||||
} catch {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return {
|
||||
tenantId,
|
||||
connectionId: connection.id,
|
||||
credentials: credentials as KwpCredentials,
|
||||
connectionStatus: connection.connectionStatus,
|
||||
tokenExpiresAt: connection.tokenExpiresAt,
|
||||
healthMessageKey: connection.healthMessageKey,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
function requireTenantId(): string {
|
||||
const tenantId = getRlsExecutionContext()?.tenantId?.trim();
|
||||
if (!tenantId) throw new KwpError("invalid_credentials");
|
||||
return tenantId;
|
||||
}
|
||||
|
||||
async function pauseCapability(snapshot: CredentialSnapshot, capability: string, failureCode: "contract_drift" | "auth_scope_missing"): Promise<void> {
|
||||
const reasonPrefix = capability === KWP_PROJECT_CAPABILITY ? "kwp.project" : capability.replace("kwp-scoped-", "kwp.");
|
||||
const reasonCode = failureCode === "auth_scope_missing" ? `${reasonPrefix}.missing_provider_permission` : `${reasonPrefix}.contract_drift`;
|
||||
const now = new Date();
|
||||
const db = getDbClient();
|
||||
await db.$transaction(async (tx) => {
|
||||
await tx.kwpCapabilityState.upsert({
|
||||
where: {
|
||||
tenantId_dataConnectionId_capability: {
|
||||
tenantId: snapshot.tenantId,
|
||||
dataConnectionId: snapshot.connectionId,
|
||||
capability,
|
||||
},
|
||||
},
|
||||
create: {
|
||||
tenantId: snapshot.tenantId,
|
||||
dataConnectionId: snapshot.connectionId,
|
||||
capability,
|
||||
status: "paused",
|
||||
reasonCode,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: 1,
|
||||
pausedAt: now,
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
update: {
|
||||
status: "paused",
|
||||
reasonCode,
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
revision: { increment: 1 },
|
||||
pausedAt: now,
|
||||
lastCheckedAt: now,
|
||||
},
|
||||
});
|
||||
await tx.kwpErrorReport.create({
|
||||
data: {
|
||||
tenantId: snapshot.tenantId,
|
||||
dataConnectionId: snapshot.connectionId,
|
||||
capability: KWP_PROJECT_CAPABILITY,
|
||||
code: reasonCode,
|
||||
redactedDetails: {
|
||||
adapterRevision: KWP_PROJECT_ADAPTER_REVISION,
|
||||
httpClass: failureCode === "auth_scope_missing" ? "forbidden" : "schema",
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
async function consumeKwpResourceBudget(clientId: string): Promise<void> {
|
||||
const key = createHash("sha256").update(clientId.trim()).digest("hex");
|
||||
let limiter: FixedWindowRateLimiter;
|
||||
try {
|
||||
limiter = createFixedWindowRateLimiter({
|
||||
store: getKwpResourceStore(),
|
||||
prefix: "oauth-client-v2",
|
||||
windowSeconds: KWP_RESOURCE_BUDGET_WINDOW_SECONDS,
|
||||
max: KWP_RESOURCE_BUDGET_PER_MINUTE,
|
||||
});
|
||||
} catch {
|
||||
throw new KwpError("rate_limit_exceeded", 429);
|
||||
}
|
||||
let waitCycle = 0;
|
||||
|
||||
while (true) {
|
||||
let decision: FixedWindowDecision;
|
||||
try {
|
||||
decision = await limiter.consume(key);
|
||||
} catch {
|
||||
// A shared-budget outage must fail closed; a replica-local fallback
|
||||
// could breach KWP's provider-wide hard cap.
|
||||
throw new KwpError("rate_limit_exceeded", 429);
|
||||
}
|
||||
if (decision.allowed) return;
|
||||
|
||||
waitCycle += 1;
|
||||
const untilResetMs = decision.resetAt.getTime() - Date.now();
|
||||
const delayMs = Math.min(
|
||||
KWP_RESOURCE_BUDGET_WINDOW_SECONDS * 1_000 + KWP_RESOURCE_BUDGET_RESET_PADDING_MS,
|
||||
Math.max(KWP_RESOURCE_BUDGET_RESET_PADDING_MS, untilResetMs + KWP_RESOURCE_BUDGET_RESET_PADDING_MS)
|
||||
);
|
||||
kwpResourceBudgetLogger.info(
|
||||
{
|
||||
delayMs,
|
||||
waitCycle,
|
||||
budgetPerMinute: KWP_RESOURCE_BUDGET_PER_MINUTE,
|
||||
},
|
||||
"integrations.kwp-resource-budget.waiting"
|
||||
);
|
||||
await wait(delayMs);
|
||||
}
|
||||
}
|
||||
|
||||
function getKwpResourceStore(): SharedStore {
|
||||
sharedStore ??= createSharedStore({
|
||||
namespace: "kwp-resource-budget",
|
||||
redisUrl: resolveSharedRedisUrl(),
|
||||
});
|
||||
return sharedStore;
|
||||
}
|
||||
|
||||
function normalizeConnectionId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!/^[A-Za-z0-9_-]{8,191}$/u.test(normalized)) throw new KwpError("invalid_credentials");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
export function __setKwpResourceSharedStoreForTests(store: SharedStore): void {
|
||||
sharedStore = store;
|
||||
}
|
||||
|
||||
export function __resetKwpResourceSharedStoreForTests(): void {
|
||||
sharedStore = null;
|
||||
}
|
||||
|
||||
export type { KwpAddressDetails, KwpProjectDetails, KwpProjectSearchResult, KwpSemanticContract } from "./resource-client.js";
|
||||
export type { KwpCapabilitySemanticContract, KwpOperationInput, KwpReadOperationId } from "./scoped-contract.js";
|
||||
+662
@@ -0,0 +1,662 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import {
|
||||
assertKwpReadOperationAllowed,
|
||||
buildKwpSemanticContract,
|
||||
createKwpResourceTransport,
|
||||
KWP_ADDRESS_DETAILS_PATH,
|
||||
KWP_PROJECT_CATALOG_PATH,
|
||||
KWP_PROJECT_DETAILS_PATH,
|
||||
KWP_PROJECT_SEARCH_PATH,
|
||||
} from "./resource-client.js";
|
||||
import { KWP_OIDC_ISSUER, KWP_REQUIRED_OAUTH_SCOPES, type KwpCredentials, type KwpOutboundRequestOptions } from "./client.js";
|
||||
import { KWP_SCOPED_OPERATIONS } from "./scoped-contract.js";
|
||||
|
||||
const CREDENTIALS: KwpCredentials = {
|
||||
accessToken: "access-secret",
|
||||
refreshToken: "refresh-secret",
|
||||
expiresAt: "2026-07-23T12:00:00.000Z",
|
||||
issuer: KWP_OIDC_ISSUER,
|
||||
clientId: "_extern-geerkens2",
|
||||
clientSecret: "client-secret",
|
||||
customerCode: "geerkens2",
|
||||
scopes: [...KWP_REQUIRED_OAUTH_SCOPES],
|
||||
mandantBinding: { kind: "selected", code: "mandant1" },
|
||||
};
|
||||
|
||||
const PUBLIC_ADDRESS_RESOLVER = async (): Promise<readonly string[]> => ["93.184.216.34"];
|
||||
|
||||
describe("KWP project resource transport", () => {
|
||||
it("executes only targeted search and normalizes the consumed fields", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse([
|
||||
{
|
||||
projNr: " P-100 ",
|
||||
projBezeichnung: " Heizung Schule ",
|
||||
projAdr: "ADR-1",
|
||||
rechAdr: "ADR-2",
|
||||
bauHrAdr: "ADR-3",
|
||||
auftragStatus: 8,
|
||||
},
|
||||
])
|
||||
);
|
||||
const consumeBudget = vi.fn().mockResolvedValue(undefined);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.searchProjects(" Schule ")).resolves.toEqual([
|
||||
{
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Heizung Schule",
|
||||
projectAddressCode: "ADR-1",
|
||||
invoiceAddressCode: "ADR-2",
|
||||
clientAddressCode: "ADR-3",
|
||||
status: 8,
|
||||
statusLabel: "Erhalten",
|
||||
},
|
||||
]);
|
||||
|
||||
expect(consumeBudget).toHaveBeenCalledTimes(2);
|
||||
const [url, init] = fetchMock.mock.calls[1] as [string, RequestInit];
|
||||
expect(new URL(url).pathname).toBe(`/relay/geerkens2/pwa${KWP_PROJECT_SEARCH_PATH}`);
|
||||
expect(new URL(url).searchParams.get("mandant")).toBe("mandant1");
|
||||
expect(init.method).toBe("POST");
|
||||
expect(JSON.parse(String(init.body))).toEqual({ value: "Schule" });
|
||||
});
|
||||
|
||||
it("skips search rows without the optional routing status while keeping routable results available", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse([
|
||||
{
|
||||
projNr: "P-NO-STATUS",
|
||||
projBezeichnung: "Noch nicht routbar",
|
||||
},
|
||||
{
|
||||
projNr: "P-ROUTABLE",
|
||||
projBezeichnung: "Routbares Projekt",
|
||||
auftragStatus: 7,
|
||||
},
|
||||
])
|
||||
);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.searchProjects("Projekt")).resolves.toEqual([
|
||||
{
|
||||
externalProjectNumber: "P-ROUTABLE",
|
||||
name: "Routbares Projekt",
|
||||
projectAddressCode: null,
|
||||
invoiceAddressCode: null,
|
||||
clientAddressCode: null,
|
||||
status: 7,
|
||||
statusLabel: "Zugesagt",
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it("discovers the setting-visible project catalog without an empty search", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse([
|
||||
{ projNr: " P-100 ", anzahlAktivitaeten: 3 },
|
||||
{ projNr: "P-200", anzahlAktivitaeten: 0 },
|
||||
{ projNr: "P-100", anzahlAktivitaeten: 4 },
|
||||
{ projNr: null, anzahlAktivitaeten: 0 },
|
||||
])
|
||||
);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.listProjectNumbers()).resolves.toEqual(["P-100", "P-200"]);
|
||||
const [url, init] = fetchMock.mock.calls[1] as [string, RequestInit];
|
||||
expect(new URL(url).pathname).toBe(`/relay/geerkens2/pwa${KWP_PROJECT_CATALOG_PATH}`);
|
||||
expect(new URL(url).searchParams.get("mandant")).toBe("mandant1");
|
||||
expect(init.method).toBe("GET");
|
||||
expect(init.body).toBeUndefined();
|
||||
});
|
||||
|
||||
it("still rejects a present search status outside the consumed KWP enum", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse([
|
||||
{
|
||||
projNr: "P-INVALID-STATUS",
|
||||
projBezeichnung: "Ungültiger Status",
|
||||
auftragStatus: 10,
|
||||
},
|
||||
])
|
||||
);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.searchProjects("Projekt")).rejects.toMatchObject({
|
||||
code: "contract_drift",
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts omitted optional fields from live project and address responses", async () => {
|
||||
const detailsFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
projNr: "P-100",
|
||||
projBezeichnung: "Heizung Schule",
|
||||
adresse: {
|
||||
adrNrGes: "ADR-1",
|
||||
name: "Schule",
|
||||
zusatz: "Altbau",
|
||||
strasse: "Dorfstraße 1",
|
||||
ort: { ortId: 1, plz: "12345", ort: "Berlin" },
|
||||
},
|
||||
auftragssumme: 42_500,
|
||||
})
|
||||
);
|
||||
const detailsResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(detailsFetch),
|
||||
});
|
||||
|
||||
await expect(detailsResource.loadProjectDetails("P-100")).resolves.toEqual({
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Heizung Schule",
|
||||
startDate: null,
|
||||
orderValue: 42_500,
|
||||
addressCode: "ADR-1",
|
||||
addressName: "Schule",
|
||||
});
|
||||
|
||||
const addressFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
adrNrGes: "ADR-1",
|
||||
name: "Schule",
|
||||
zusatz: "Altbau",
|
||||
strasse: "Dorfstraße 1",
|
||||
ort: { ortId: 1, plz: "12345", ort: "Berlin" },
|
||||
// Real KWP tenants return null for these documented object fields.
|
||||
// They are not consumed by project import and must not create a
|
||||
// capability-wide false-positive contract pause.
|
||||
ortPstf: null,
|
||||
briefanrede: null,
|
||||
selekt1: null,
|
||||
selekt2: null,
|
||||
bank: null,
|
||||
kontakte: [
|
||||
{
|
||||
kontaktId: 1,
|
||||
kontaktart: 2,
|
||||
kontakt: "info@example.test",
|
||||
kontaktartTyp: 0,
|
||||
kontaktName: "E-Mail",
|
||||
ansprechpartnerId: null,
|
||||
},
|
||||
],
|
||||
ansprechpartner: [],
|
||||
})
|
||||
);
|
||||
const addressResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(addressFetch),
|
||||
});
|
||||
|
||||
await expect(addressResource.loadAddressDetails("ADR-1")).resolves.toMatchObject({
|
||||
externalAddressCode: "ADR-1",
|
||||
firstName: null,
|
||||
country: null,
|
||||
invoiceEmail: null,
|
||||
email: "info@example.test",
|
||||
contactPeople: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("still rejects an invalid consumed address field while ignoring unconsumed nullable drift", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
adrNrGes: "ADR-1",
|
||||
name: "Schule",
|
||||
ortPstf: null,
|
||||
briefanrede: null,
|
||||
selekt1: null,
|
||||
selekt2: null,
|
||||
bank: null,
|
||||
kontakte: [{ kontaktart: 99, kontakt: "invalid@example.test", ansprechpartnerId: null }],
|
||||
})
|
||||
);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.loadAddressDetails("ADR-1")).rejects.toMatchObject({
|
||||
code: "contract_drift",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects empty or one-character search without provider I/O", async () => {
|
||||
const fetchMock = vi.fn();
|
||||
const consumeBudget = vi.fn();
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.searchProjects(" ")).rejects.toMatchObject({ code: "invalid_credentials" });
|
||||
await expect(resource.searchProjects("x")).rejects.toMatchObject({ code: "invalid_credentials" });
|
||||
expect(consumeBudget).not.toHaveBeenCalled();
|
||||
expect(fetchMock).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("loads project details by GET and detects a renamed consumed field", async () => {
|
||||
const validFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
projNr: "P-100",
|
||||
projBezeichnung: "Heizung Schule",
|
||||
beginn: "2026-07-01T00:00:00+02:00",
|
||||
adresse: {
|
||||
adrNrGes: "ADR-1",
|
||||
name: "Schule",
|
||||
vorname: null,
|
||||
zusatz: null,
|
||||
strasse: "Dorfstraße 1",
|
||||
ort: { ortId: 1, land: "DE", plz: "12345", ort: "Berlin" },
|
||||
debitKreditNr: 987654,
|
||||
},
|
||||
sachBearb: null,
|
||||
vertrieb: null,
|
||||
auftragssumme: 42_500,
|
||||
})
|
||||
);
|
||||
const validResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(validFetch),
|
||||
});
|
||||
|
||||
await expect(validResource.loadProjectDetails("P-100")).resolves.toEqual({
|
||||
externalProjectNumber: "P-100",
|
||||
name: "Heizung Schule",
|
||||
startDate: "2026-06-30T22:00:00.000Z",
|
||||
orderValue: 42_500,
|
||||
addressCode: "ADR-1",
|
||||
addressName: "Schule",
|
||||
});
|
||||
const [url, init] = validFetch.mock.calls[1] as [string, RequestInit];
|
||||
expect(new URL(url).pathname).toBe(`/relay/geerkens2/pwa${KWP_PROJECT_DETAILS_PATH}`);
|
||||
expect(new URL(url).searchParams.get("projNr")).toBe("P-100");
|
||||
expect(init.method).toBe("GET");
|
||||
expect(init.body).toBeUndefined();
|
||||
|
||||
const driftFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
projektNummer: "P-100",
|
||||
projBezeichnung: "Heizung Schule",
|
||||
beginn: null,
|
||||
adresse: { adrNrGes: null, name: null, vorname: null, zusatz: null, strasse: null, ort: { ortId: 1, land: null, plz: null, ort: null } },
|
||||
sachBearb: null,
|
||||
vertrieb: null,
|
||||
auftragssumme: null,
|
||||
})
|
||||
);
|
||||
const driftResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(driftFetch),
|
||||
});
|
||||
await expect(driftResource.loadProjectDetails("P-100")).rejects.toMatchObject({ code: "contract_drift" });
|
||||
});
|
||||
|
||||
it("discards prohibited financial, tax, birthday, note and user fields", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(
|
||||
jsonResponse({
|
||||
adrNrGes: "ADR-1",
|
||||
name: "Geerkens GmbH",
|
||||
vorname: null,
|
||||
zusatz: "Niederlassung",
|
||||
strasse: "Werkstraße 7",
|
||||
ort: { ortId: 1, land: "DE", plz: "52511", ort: "Geilenkirchen" },
|
||||
rechnungsmailadresse: "rechnung@example.test",
|
||||
kontakte: [
|
||||
{ kontaktId: 1, kontaktart: 2, kontakt: "info@example.test", kontaktName: "E-Mail", bemerkung: "secret", ansprechpartnerId: null },
|
||||
{ kontaktId: 2, kontaktart: 0, kontakt: "+49 123", kontaktName: "Telefon", bemerkung: null, ansprechpartnerId: null },
|
||||
],
|
||||
ansprechpartner: [
|
||||
{
|
||||
nachname: "Muster",
|
||||
vorname: "Maria",
|
||||
ansprechpartnerId: 99,
|
||||
zusatz: null,
|
||||
geburtstag: "1980-01-01T00:00:00Z",
|
||||
benutzerFeld1: "never-store",
|
||||
bemerkung: "internal",
|
||||
kontakte: [{ kontaktId: 3, kontaktart: 2, kontakt: "maria@example.test", kontaktName: "E-Mail", bemerkung: null, ansprechpartnerId: 99 }],
|
||||
},
|
||||
],
|
||||
iban: "DE001234",
|
||||
bank: { bezeichnung: "Secret Bank" },
|
||||
kreditLimit: 100_000,
|
||||
ustId: "DE123",
|
||||
hinweis: "internal",
|
||||
benutzerFeld1: "never-store",
|
||||
})
|
||||
);
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
const address = await resource.loadAddressDetails("ADR-1");
|
||||
expect(address).toMatchObject({
|
||||
externalAddressCode: "ADR-1",
|
||||
name: "Geerkens GmbH",
|
||||
invoiceEmail: "rechnung@example.test",
|
||||
email: "info@example.test",
|
||||
phone: "+49 123",
|
||||
contactPeople: [
|
||||
{
|
||||
externalContactId: "99",
|
||||
firstName: "Maria",
|
||||
lastName: "Muster",
|
||||
email: "maria@example.test",
|
||||
},
|
||||
],
|
||||
});
|
||||
const persisted = JSON.stringify(address).toLowerCase();
|
||||
for (const prohibited of [
|
||||
'"iban"',
|
||||
'"bank"',
|
||||
'"kreditlimit"',
|
||||
'"ustid"',
|
||||
'"geburtstag"',
|
||||
'"hinweis"',
|
||||
'"benutzerfeld1"',
|
||||
'"bemerkung"',
|
||||
"de001234",
|
||||
"never-store",
|
||||
]) {
|
||||
expect(persisted).not.toContain(prohibited.toLowerCase());
|
||||
}
|
||||
expect(new URL(String(fetchMock.mock.calls[1]?.[0])).pathname).toBe(`/relay/geerkens2/pwa${KWP_ADDRESS_DETAILS_PATH}`);
|
||||
});
|
||||
|
||||
it("blocks every KWP write or non-allowlisted read before transport", () => {
|
||||
for (const operation of KWP_SCOPED_OPERATIONS) {
|
||||
const assertion = () => assertKwpReadOperationAllowed(operation.method, operation.path);
|
||||
if (operation.mode === "read") expect(assertion).not.toThrow();
|
||||
else expect(assertion).toThrow();
|
||||
}
|
||||
expect(() => assertKwpReadOperationAllowed("GET", "/api/Core/GetApiVersion")).toThrow();
|
||||
expect(() => assertKwpReadOperationAllowed("GET", KWP_PROJECT_DETAILS_PATH)).not.toThrow();
|
||||
});
|
||||
|
||||
it("executes exact generic GET and read-POST operation ids without exposing a free path", async () => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse({}))
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse([]));
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.executeReadOperation("monteursteuerungGetSetup")).resolves.toEqual({});
|
||||
await expect(resource.executeReadOperation("vorgangAnzeigeLoadPositionen", { body: {} })).resolves.toEqual([]);
|
||||
|
||||
const getUrl = new URL(String(fetchMock.mock.calls[1]?.[0]));
|
||||
expect(getUrl.pathname).toBe("/relay/geerkens2/pwa/api/Monteursteuerung/GetSetup");
|
||||
expect(getUrl.searchParams.get("mandant")).toBe("mandant1");
|
||||
expect((fetchMock.mock.calls[1]?.[1] as RequestInit).method).toBe("GET");
|
||||
const postUrl = new URL(String(fetchMock.mock.calls[3]?.[0]));
|
||||
expect(postUrl.pathname).toBe("/relay/geerkens2/pwa/api/VorgangAnzeige/LoadPositionen");
|
||||
expect(postUrl.searchParams.get("mandant")).toBe("mandant1");
|
||||
expect((fetchMock.mock.calls[3]?.[1] as RequestInit).method).toBe("POST");
|
||||
expect(JSON.parse(String((fetchMock.mock.calls[3]?.[1] as RequestInit).body))).toEqual({});
|
||||
});
|
||||
|
||||
it("fails closed for an unconfirmed mandant and classifies 403 without exposing the provider body", async () => {
|
||||
const { mandantBinding: _binding, ...unconfirmed } = CREDENTIALS;
|
||||
expect(() =>
|
||||
createKwpResourceTransport(unconfirmed, {
|
||||
consumeBudget: async () => undefined,
|
||||
})
|
||||
).toThrowError(expect.objectContaining({ code: "mandant_unconfirmed" }));
|
||||
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse({ token: CREDENTIALS.accessToken }, 403));
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
const error = await resource.searchProjects("Projekt").catch((caught: unknown) => caught);
|
||||
expect(error).toMatchObject({ code: "auth_scope_missing", httpStatus: 403 });
|
||||
expect(JSON.stringify(error)).not.toContain(CREDENTIALS.accessToken);
|
||||
});
|
||||
|
||||
it.each([
|
||||
[401, "auth_token_invalid"],
|
||||
[429, "rate_limit_exceeded"],
|
||||
[503, "provider_outage"],
|
||||
])("classifies HTTP %i without hidden refresh or request retry", async (status, code) => {
|
||||
const fetchMock = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse({ token: CREDENTIALS.accessToken }, status));
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.searchProjects("Projekt")).rejects.toMatchObject({
|
||||
code,
|
||||
httpStatus: status,
|
||||
});
|
||||
expect(fetchMock).toHaveBeenCalledTimes(2);
|
||||
expect(JSON.stringify(fetchMock.mock.results)).not.toContain(CREDENTIALS.refreshToken);
|
||||
});
|
||||
|
||||
it("fingerprints only the consumed semantic OpenAPI slice", () => {
|
||||
const base = openApiFixture();
|
||||
const first = buildKwpSemanticContract(base);
|
||||
const unrelated = structuredClone(base);
|
||||
unrelated.paths["/api/Unrelated/Save"] = { post: { responses: { 200: {} } } };
|
||||
unrelated.components.schemas.Unrelated = { type: "object", properties: { value: { type: "string" } } };
|
||||
expect(buildKwpSemanticContract(unrelated).semanticFingerprint).toBe(first.semanticFingerprint);
|
||||
|
||||
const architectOnly = structuredClone(base);
|
||||
architectOnly.components.schemas["Kwp.Api.Service.Dto.Projekte.DtoSearchResultProjekt"].properties.archAdr = {
|
||||
type: "integer",
|
||||
};
|
||||
expect(buildKwpSemanticContract(architectOnly).semanticFingerprint).toBe(first.semanticFingerprint);
|
||||
|
||||
const changed = structuredClone(base);
|
||||
changed.components.schemas["Kwp.Api.Model.Values.ProjektHauptstatus"].enum.push(10);
|
||||
expect(buildKwpSemanticContract(changed).semanticFingerprint).not.toBe(first.semanticFingerprint);
|
||||
|
||||
const renamed = structuredClone(base);
|
||||
delete renamed.components.schemas["Kwp.Api.Service.Dto.Projekte.DtoSearchResultProjekt"].properties.projNr;
|
||||
expect(() => buildKwpSemanticContract(renamed)).toThrowError(expect.objectContaining({ code: "contract_drift" }));
|
||||
});
|
||||
|
||||
it("accepts the larger tenant OpenAPI while keeping business responses capped at one MiB", async () => {
|
||||
const openApi = openApiFixture();
|
||||
openApi.paths["/api/Unrelated/Large"] = {
|
||||
get: {
|
||||
description: "x".repeat(2 * 1024 * 1024),
|
||||
responses: { 200: {} },
|
||||
},
|
||||
};
|
||||
const openApiFetch = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(openApi));
|
||||
const openApiResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(openApiFetch),
|
||||
});
|
||||
|
||||
await expect(openApiResource.loadSemanticContract()).resolves.toMatchObject({
|
||||
apiVersion: "v1",
|
||||
});
|
||||
|
||||
const oversizedBusinessResponse = [
|
||||
{
|
||||
projNr: "P-100",
|
||||
projBezeichnung: "Heizung Schule",
|
||||
auftragStatus: 8,
|
||||
ignored: "x".repeat(1024 * 1024),
|
||||
},
|
||||
];
|
||||
const searchFetch = vi
|
||||
.fn()
|
||||
.mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de"))
|
||||
.mockResolvedValueOnce(jsonResponse(oversizedBusinessResponse));
|
||||
const searchResource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(searchFetch),
|
||||
});
|
||||
|
||||
await expect(searchResource.searchProjects("Projekt")).rejects.toMatchObject({
|
||||
code: "contract_drift",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects an OpenAPI response above the dedicated eight MiB ceiling", async () => {
|
||||
const openApi = openApiFixture();
|
||||
openApi.paths["/api/Unrelated/Oversized"] = {
|
||||
get: {
|
||||
description: "x".repeat(8 * 1024 * 1024),
|
||||
responses: { 200: {} },
|
||||
},
|
||||
};
|
||||
const fetchMock = vi.fn().mockResolvedValueOnce(new Response("https://geerkens2.app04.kwp-online.de")).mockResolvedValueOnce(jsonResponse(openApi));
|
||||
const resource = createKwpResourceTransport(CREDENTIALS, {
|
||||
consumeBudget: async () => undefined,
|
||||
outboundOptions: outboundOptions(fetchMock),
|
||||
});
|
||||
|
||||
await expect(resource.loadSemanticContract()).rejects.toMatchObject({
|
||||
code: "contract_drift",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
function outboundOptions(fetchImpl: typeof fetch): KwpOutboundRequestOptions {
|
||||
return { fetchImpl, addressResolver: PUBLIC_ADDRESS_RESOLVER };
|
||||
}
|
||||
|
||||
function jsonResponse(body: unknown, status = 200): Response {
|
||||
return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
|
||||
}
|
||||
|
||||
function openApiFixture(): {
|
||||
info: { version: string };
|
||||
paths: Record<string, any>;
|
||||
components: { schemas: Record<string, any> };
|
||||
} {
|
||||
const response = (schema: string) => ({
|
||||
"200": { content: { "application/json": { schema: { $ref: `#/components/schemas/${schema}` } } } },
|
||||
});
|
||||
const property = (type: string) => ({ type, nullable: true });
|
||||
return {
|
||||
info: { version: "v1" },
|
||||
paths: {
|
||||
[KWP_PROJECT_SEARCH_PATH]: {
|
||||
post: {
|
||||
parameters: [{ name: "mandant", in: "query", schema: { type: "string" } }],
|
||||
requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Kwp.Api.Service.Dto.DtoValue" } } } },
|
||||
responses: response("Kwp.Api.Service.Dto.Projekte.DtoSearchResultProjekt"),
|
||||
},
|
||||
},
|
||||
[KWP_PROJECT_DETAILS_PATH]: {
|
||||
get: {
|
||||
parameters: [{ name: "projNr", in: "query", schema: { type: "string" } }],
|
||||
responses: response("Kwp.Api.Service.Dto.Projektampel.DtoProjektampelProjekt"),
|
||||
},
|
||||
},
|
||||
[KWP_ADDRESS_DETAILS_PATH]: {
|
||||
get: {
|
||||
parameters: [{ name: "adresskuerzel", in: "query", schema: { type: "string" } }],
|
||||
responses: response("Kwp.Api.Service.Dto.Adressen.DtoAdresseKomplett"),
|
||||
},
|
||||
},
|
||||
},
|
||||
components: {
|
||||
schemas: {
|
||||
"Kwp.Api.Service.Dto.DtoValue": { type: "object", properties: { value: property("string") } },
|
||||
"Kwp.Api.Service.Dto.Projekte.DtoSearchResultProjekt": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(
|
||||
["projNr", "projBezeichnung", "projAdr", "rechAdr", "archAdr", "bauHrAdr", "auftragStatus"].map((name) => [
|
||||
name,
|
||||
property(name === "auftragStatus" ? "integer" : "string"),
|
||||
])
|
||||
),
|
||||
},
|
||||
"Kwp.Api.Model.Values.ProjektHauptstatus": { type: "integer", format: "int32", enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] },
|
||||
"Kwp.Api.Service.Dto.Projektampel.DtoProjektampelProjekt": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(
|
||||
["projNr", "projBezeichnung", "beginn", "adresse", "sachBearb", "vertrieb", "auftragssumme"].map((name) => [name, property("string")])
|
||||
),
|
||||
},
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAdresse": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(["adrNrGes", "name", "vorname", "zusatz", "strasse", "ort"].map((name) => [name, property("string")])),
|
||||
},
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAdresseKomplett": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(
|
||||
["adrNrGes", "name", "vorname", "zusatz", "strasse", "ort", "rechnungsmailadresse", "kontakte", "ansprechpartner"].map((name) => [
|
||||
name,
|
||||
property("string"),
|
||||
])
|
||||
),
|
||||
},
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoOrt": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(["ortId", "land", "plz", "ort"].map((name) => [name, property("string")])),
|
||||
},
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoKontakt": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(["kontaktId", "kontaktart", "kontakt", "kontaktName", "ansprechpartnerId"].map((name) => [name, property("string")])),
|
||||
},
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAnsprechpartner": {
|
||||
type: "object",
|
||||
properties: Object.fromEntries(["nachname", "vorname", "ansprechpartnerId", "zusatz", "kontakte"].map((name) => [name, property("string")])),
|
||||
},
|
||||
"Kwp.Api.Model.Values.Adresse.Kontaktart": { type: "integer", format: "int32", enum: [0, 1, 2, 3, 4, 5] },
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
+598
@@ -0,0 +1,598 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { fetchOutboundHttpWithRedirects, OutboundHttpUrlValidationError, readLimitedResponseText } from "@hivegrid/foundation/outbound-http";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
assertKwpResourceCredentials,
|
||||
KwpError,
|
||||
resolveKwpRelayBaseUrl,
|
||||
validateKwpOnlineUrl,
|
||||
type KwpCredentials,
|
||||
type KwpOutboundRequestOptions,
|
||||
} from "./client.js";
|
||||
import {
|
||||
assertKwpReadOperationId,
|
||||
buildKwpCapabilitySemanticContract,
|
||||
getKwpScopedOperation,
|
||||
KWP_SCOPED_OPERATIONS,
|
||||
listKwpCapabilities,
|
||||
parseKwpOperationResponse,
|
||||
validateKwpOperationInput,
|
||||
type KwpCapability,
|
||||
type KwpCapabilitySemanticContract,
|
||||
type KwpOperationInput,
|
||||
type KwpReadOperationId,
|
||||
} from "./scoped-contract.js";
|
||||
|
||||
export const KWP_PROJECT_CAPABILITY = "project-import";
|
||||
export const KWP_PROJECT_ADAPTER_REVISION = "kwp-project-v5";
|
||||
export const KWP_PROJECT_SEARCH_PATH = "/api/Projekt/Search";
|
||||
export const KWP_PROJECT_DETAILS_PATH = "/api/Projektampel/LoadProjektDetails";
|
||||
export const KWP_PROJECT_CATALOG_PATH = "/api/Projektampel/LoadProjekteNachFilter";
|
||||
export const KWP_ADDRESS_DETAILS_PATH = "/api/Adresse/LoadAdressKomplett";
|
||||
export const KWP_OPENAPI_PATH = "/swagger/v1/swagger.json";
|
||||
export const KWP_RESOURCE_BUDGET_PER_MINUTE = 50;
|
||||
export const KWP_SCOPED_CAPABILITY_KEYS: Readonly<Record<KwpCapability, string>> = Object.freeze({
|
||||
activity: "kwp-scoped-activity",
|
||||
address: "kwp-scoped-address",
|
||||
archive: "kwp-scoped-archive",
|
||||
project: "kwp-scoped-project",
|
||||
schedule: "kwp-scoped-schedule",
|
||||
});
|
||||
|
||||
const KWP_RESOURCE_RESPONSE_LIMIT_BYTES = 1024 * 1024;
|
||||
const KWP_PROJECT_CATALOG_RESPONSE_LIMIT_BYTES = 16 * 1024 * 1024;
|
||||
const KWP_OPENAPI_RESPONSE_LIMIT_BYTES = 8 * 1024 * 1024;
|
||||
const KWP_PROJECT_SEARCH_MAX_ENTRIES = 500;
|
||||
const KWP_PROJECT_CATALOG_MAX_ENTRIES = 100_000;
|
||||
const KWP_QUERY_MAX_LENGTH = 191;
|
||||
const KWP_EXTERNAL_ID_MAX_LENGTH = 191;
|
||||
|
||||
const nullableString = z.string().max(2_048).nullable();
|
||||
const optionalNullableString = nullableString.optional().default(null);
|
||||
const int32 = z.number().int().min(-2_147_483_648).max(2_147_483_647);
|
||||
const int64Safe = z.number().int().safe();
|
||||
const kwpStatusSchema = z.number().int().min(0).max(9);
|
||||
|
||||
const rawOrtSchema = z
|
||||
.object({
|
||||
ortId: int32.optional().default(0),
|
||||
land: optionalNullableString,
|
||||
plz: optionalNullableString,
|
||||
ort: optionalNullableString,
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawAddressSummarySchema = z
|
||||
.object({
|
||||
adrNrGes: optionalNullableString,
|
||||
name: optionalNullableString,
|
||||
vorname: optionalNullableString,
|
||||
zusatz: optionalNullableString,
|
||||
strasse: optionalNullableString,
|
||||
ort: rawOrtSchema.optional().default({}),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawContactChannelSchema = z
|
||||
.object({
|
||||
kontaktart: z.number().int().min(0).max(5),
|
||||
kontakt: optionalNullableString,
|
||||
ansprechpartnerId: int64Safe.nullable().optional().default(null),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawContactPersonSchema = z
|
||||
.object({
|
||||
nachname: optionalNullableString,
|
||||
vorname: optionalNullableString,
|
||||
ansprechpartnerId: int64Safe,
|
||||
zusatz: optionalNullableString,
|
||||
kontakte: z.array(rawContactChannelSchema).max(100).nullable().optional().default(null),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawProjectSearchResultSchema = z
|
||||
.object({
|
||||
projNr: optionalNullableString,
|
||||
projBezeichnung: optionalNullableString,
|
||||
projAdr: optionalNullableString,
|
||||
rechAdr: optionalNullableString,
|
||||
bauHrAdr: optionalNullableString,
|
||||
auftragStatus: kwpStatusSchema.optional(),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawProjectDetailsSchema = z
|
||||
.object({
|
||||
projNr: optionalNullableString,
|
||||
projBezeichnung: optionalNullableString,
|
||||
beginn: z.string().datetime({ offset: true }).nullable().optional().default(null),
|
||||
adresse: rawAddressSummarySchema.optional().default({}),
|
||||
auftragssumme: z.number().finite().nullable().optional().default(null),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawProjectCatalogEntrySchema = z
|
||||
.object({
|
||||
projNr: optionalNullableString,
|
||||
anzahlAktivitaeten: int32.optional().default(0),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const rawAddressDetailsSchema = z
|
||||
.object({
|
||||
adrNrGes: optionalNullableString,
|
||||
name: optionalNullableString,
|
||||
vorname: optionalNullableString,
|
||||
zusatz: optionalNullableString,
|
||||
strasse: optionalNullableString,
|
||||
ort: rawOrtSchema.optional().default({}),
|
||||
rechnungsmailadresse: optionalNullableString,
|
||||
kontakte: z.array(rawContactChannelSchema).max(100).nullable().optional().default(null),
|
||||
ansprechpartner: z.array(rawContactPersonSchema).max(100).nullable().optional().default(null),
|
||||
})
|
||||
.strip();
|
||||
|
||||
const openApiSchema = z
|
||||
.object({
|
||||
info: z.object({ version: z.string().min(1).max(64) }).passthrough(),
|
||||
paths: z.record(z.unknown()),
|
||||
components: z.object({ schemas: z.record(z.unknown()) }).passthrough(),
|
||||
})
|
||||
.passthrough();
|
||||
|
||||
export const KWP_PROJECT_STATUS_LABELS = Object.freeze({
|
||||
0: "Noch nicht vergeben",
|
||||
1: "Nicht erhalten",
|
||||
2: "Neu ausgeschrieben",
|
||||
3: "Ersatzangebot",
|
||||
4: "Zurückgestellt",
|
||||
5: "Nicht erhalten: zu teuer",
|
||||
6: "Nicht erhalten: sonstige Gründe",
|
||||
7: "Zugesagt",
|
||||
8: "Erhalten",
|
||||
9: "Abgeschlossen",
|
||||
} as const);
|
||||
|
||||
export type KwpProjectStatus = keyof typeof KWP_PROJECT_STATUS_LABELS;
|
||||
|
||||
export type KwpProjectSearchResult = {
|
||||
readonly externalProjectNumber: string;
|
||||
readonly name: string;
|
||||
readonly projectAddressCode: string | null;
|
||||
readonly invoiceAddressCode: string | null;
|
||||
readonly clientAddressCode: string | null;
|
||||
readonly status: KwpProjectStatus;
|
||||
readonly statusLabel: string;
|
||||
};
|
||||
|
||||
export type KwpProjectDetails = {
|
||||
readonly externalProjectNumber: string;
|
||||
readonly name: string;
|
||||
readonly startDate: string | null;
|
||||
readonly orderValue: number | null;
|
||||
readonly addressCode: string | null;
|
||||
readonly addressName: string | null;
|
||||
};
|
||||
|
||||
export type KwpAddressContactPerson = {
|
||||
readonly externalContactId: string;
|
||||
readonly firstName: string | null;
|
||||
readonly lastName: string | null;
|
||||
readonly addition: string | null;
|
||||
readonly email: string | null;
|
||||
readonly phone: string | null;
|
||||
readonly mobile: string | null;
|
||||
};
|
||||
|
||||
export type KwpAddressDetails = {
|
||||
readonly externalAddressCode: string;
|
||||
readonly name: string | null;
|
||||
readonly firstName: string | null;
|
||||
readonly addition: string | null;
|
||||
readonly street: string | null;
|
||||
readonly postalCode: string | null;
|
||||
readonly city: string | null;
|
||||
readonly country: string | null;
|
||||
readonly invoiceEmail: string | null;
|
||||
readonly email: string | null;
|
||||
readonly phone: string | null;
|
||||
readonly mobile: string | null;
|
||||
readonly contactPeople: readonly KwpAddressContactPerson[];
|
||||
};
|
||||
|
||||
export type KwpSemanticContract = {
|
||||
readonly apiVersion: string;
|
||||
readonly semanticFingerprint: string;
|
||||
readonly consumedContract: Record<string, unknown>;
|
||||
};
|
||||
|
||||
export type KwpResourceTransportDependencies = {
|
||||
readonly consumeBudget: () => Promise<void>;
|
||||
readonly outboundOptions?: KwpOutboundRequestOptions;
|
||||
};
|
||||
|
||||
export function createKwpResourceTransport(credentials: KwpCredentials, dependencies: KwpResourceTransportDependencies) {
|
||||
assertKwpResourceCredentials(credentials);
|
||||
|
||||
return Object.freeze({
|
||||
executeReadOperation: async <T = unknown>(operationId: KwpReadOperationId, input: KwpOperationInput = {}): Promise<T> => {
|
||||
assertKwpReadOperationId(operationId);
|
||||
validateKwpOperationInput(operationId, input);
|
||||
const operation = getKwpScopedOperation(operationId);
|
||||
const value = await requestJson(credentials, dependencies, operation.method, operation.path, input.query, input.body);
|
||||
return parseKwpOperationResponse(operationId, value) as T;
|
||||
},
|
||||
searchProjects: async (query: string): Promise<KwpProjectSearchResult[]> => {
|
||||
const normalizedQuery = normalizeSearchQuery(query);
|
||||
const value = await executeProjectedRead(credentials, dependencies, "projektSearch", { body: { value: normalizedQuery } });
|
||||
const parsed = z.array(rawProjectSearchResultSchema).max(KWP_PROJECT_SEARCH_MAX_ENTRIES).safeParse(value);
|
||||
if (!parsed.success) throw new KwpError("contract_drift");
|
||||
return parsed.data.flatMap(normalizeProjectSearchResult);
|
||||
},
|
||||
listProjectNumbers: async (): Promise<string[]> => {
|
||||
const value = await executeProjectedRead(credentials, dependencies, "projektampelLoadProjekteNachFilter", {});
|
||||
const parsed = z.array(rawProjectCatalogEntrySchema).max(KWP_PROJECT_CATALOG_MAX_ENTRIES).safeParse(value);
|
||||
if (!parsed.success) throw new KwpError("contract_drift");
|
||||
return [...new Set(parsed.data.map((entry) => normalizeNullableIdentifier(entry.projNr)).filter((entry): entry is string => Boolean(entry)))];
|
||||
},
|
||||
loadProjectDetails: async (projectNumber: string): Promise<KwpProjectDetails> => {
|
||||
const normalizedProjectNumber = normalizeExternalId(projectNumber);
|
||||
const value = await executeProjectedRead(credentials, dependencies, "projektampelLoadProjektDetailsGet", { query: { projNr: normalizedProjectNumber } });
|
||||
const parsed = rawProjectDetailsSchema.safeParse(value);
|
||||
if (!parsed.success) throw new KwpError("contract_drift");
|
||||
const externalProjectNumber = requireProviderIdentifier(parsed.data.projNr);
|
||||
if (externalProjectNumber !== normalizedProjectNumber) throw new KwpError("contract_drift");
|
||||
return {
|
||||
externalProjectNumber,
|
||||
name: normalizeRequiredText(parsed.data.projBezeichnung, externalProjectNumber),
|
||||
startDate: parsed.data.beginn ? new Date(parsed.data.beginn).toISOString() : null,
|
||||
orderValue: parsed.data.auftragssumme,
|
||||
addressCode: normalizeNullableIdentifier(parsed.data.adresse.adrNrGes),
|
||||
addressName: normalizeNullableText(parsed.data.adresse.name),
|
||||
};
|
||||
},
|
||||
loadAddressDetails: async (addressCode: string): Promise<KwpAddressDetails> => {
|
||||
const normalizedAddressCode = normalizeExternalId(addressCode);
|
||||
const value = await executeProjectedRead(credentials, dependencies, "adresseLoadAdressKomplett", { query: { adresskuerzel: normalizedAddressCode } });
|
||||
const parsed = rawAddressDetailsSchema.safeParse(value);
|
||||
if (!parsed.success) throw new KwpError("contract_drift");
|
||||
const externalAddressCode = requireProviderIdentifier(parsed.data.adrNrGes);
|
||||
if (externalAddressCode !== normalizedAddressCode) throw new KwpError("contract_drift");
|
||||
const primaryChannels = normalizeChannels(parsed.data.kontakte ?? [], null);
|
||||
return {
|
||||
externalAddressCode,
|
||||
name: normalizeNullableText(parsed.data.name),
|
||||
firstName: normalizeNullableText(parsed.data.vorname),
|
||||
addition: normalizeNullableText(parsed.data.zusatz),
|
||||
street: normalizeNullableText(parsed.data.strasse),
|
||||
postalCode: normalizeNullableText(parsed.data.ort.plz),
|
||||
city: normalizeNullableText(parsed.data.ort.ort),
|
||||
country: normalizeNullableText(parsed.data.ort.land),
|
||||
invoiceEmail: normalizeEmail(parsed.data.rechnungsmailadresse),
|
||||
...primaryChannels,
|
||||
contactPeople: (parsed.data.ansprechpartner ?? []).map((person) => {
|
||||
const channels = normalizeChannels(person.kontakte ?? [], person.ansprechpartnerId);
|
||||
return {
|
||||
externalContactId: String(person.ansprechpartnerId),
|
||||
firstName: normalizeNullableText(person.vorname),
|
||||
lastName: normalizeNullableText(person.nachname),
|
||||
addition: normalizeNullableText(person.zusatz),
|
||||
...channels,
|
||||
};
|
||||
}),
|
||||
};
|
||||
},
|
||||
loadSemanticContract: async (): Promise<KwpSemanticContract> => {
|
||||
const value = await requestOpenApi(credentials, dependencies);
|
||||
return buildKwpSemanticContract(value);
|
||||
},
|
||||
loadScopedSemanticContracts: async (): Promise<readonly KwpCapabilitySemanticContract[]> => {
|
||||
const value = await requestOpenApi(credentials, dependencies);
|
||||
return listKwpCapabilities().map((capability) => buildKwpCapabilitySemanticContract(value, capability));
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export function assertKwpReadOperationAllowed(method: string, path: string): void {
|
||||
const normalizedMethod = method.toUpperCase();
|
||||
const allowed =
|
||||
KWP_SCOPED_OPERATIONS.some((operation) => operation.mode === "read" && operation.method === normalizedMethod && operation.path === path) ||
|
||||
(normalizedMethod === "GET" && path === KWP_OPENAPI_PATH);
|
||||
if (!allowed) throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
export function buildKwpScopedSemanticContracts(value: unknown): Readonly<Record<KwpCapability, KwpCapabilitySemanticContract>> {
|
||||
return Object.fromEntries(listKwpCapabilities().map((capability) => [capability, buildKwpCapabilitySemanticContract(value, capability)])) as Record<
|
||||
KwpCapability,
|
||||
KwpCapabilitySemanticContract
|
||||
>;
|
||||
}
|
||||
|
||||
export function getKwpScopedCapabilityKey(capability: KwpCapability): string {
|
||||
return KWP_SCOPED_CAPABILITY_KEYS[capability];
|
||||
}
|
||||
|
||||
export function buildKwpSemanticContract(value: unknown): KwpSemanticContract {
|
||||
const parsed = openApiSchema.safeParse(value);
|
||||
if (!parsed.success) throw new KwpError("contract_drift");
|
||||
const consumedContract = {
|
||||
operations: {
|
||||
projectSearch: selectOperation(parsed.data.paths, KWP_PROJECT_SEARCH_PATH, "post"),
|
||||
projectDetails: selectOperation(parsed.data.paths, KWP_PROJECT_DETAILS_PATH, "get"),
|
||||
addressDetails: selectOperation(parsed.data.paths, KWP_ADDRESS_DETAILS_PATH, "get"),
|
||||
},
|
||||
schemas: selectConsumedSchemas(parsed.data.components.schemas),
|
||||
};
|
||||
const canonical = canonicalJson(consumedContract);
|
||||
return {
|
||||
apiVersion: parsed.data.info.version,
|
||||
semanticFingerprint: createHash("sha256").update(canonical).digest("hex"),
|
||||
consumedContract,
|
||||
};
|
||||
}
|
||||
|
||||
export function fingerprintKwpSnapshot(value: unknown): string {
|
||||
return createHash("sha256").update(canonicalJson(value)).digest("hex");
|
||||
}
|
||||
|
||||
function normalizeProjectSearchResult(value: z.infer<typeof rawProjectSearchResultSchema>): KwpProjectSearchResult[] {
|
||||
const externalProjectNumber = normalizeNullableIdentifier(value.projNr);
|
||||
if (!externalProjectNumber || value.auftragStatus === undefined) return [];
|
||||
const status = value.auftragStatus as KwpProjectStatus;
|
||||
return [
|
||||
{
|
||||
externalProjectNumber,
|
||||
name: normalizeRequiredText(value.projBezeichnung, externalProjectNumber),
|
||||
projectAddressCode: normalizeNullableIdentifier(value.projAdr),
|
||||
invoiceAddressCode: normalizeNullableIdentifier(value.rechAdr),
|
||||
clientAddressCode: normalizeNullableIdentifier(value.bauHrAdr),
|
||||
status,
|
||||
statusLabel: KWP_PROJECT_STATUS_LABELS[status],
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
function normalizeChannels(channels: readonly z.infer<typeof rawContactChannelSchema>[], contactPersonId: number | null) {
|
||||
const scoped = channels.filter((channel) => channel.ansprechpartnerId === contactPersonId);
|
||||
return {
|
||||
email: normalizeEmail(scoped.find((channel) => channel.kontaktart === 2)?.kontakt ?? null),
|
||||
phone: normalizeNullableText(scoped.find((channel) => channel.kontaktart === 0)?.kontakt ?? null),
|
||||
mobile: normalizeNullableText(scoped.find((channel) => channel.kontaktart === 4)?.kontakt ?? null),
|
||||
};
|
||||
}
|
||||
|
||||
async function requestJson(
|
||||
credentials: KwpCredentials,
|
||||
dependencies: KwpResourceTransportDependencies,
|
||||
method: string,
|
||||
path: string,
|
||||
query?: Readonly<Record<string, unknown>>,
|
||||
body?: unknown
|
||||
): Promise<unknown> {
|
||||
assertKwpReadOperationAllowed(method, path);
|
||||
await dependencies.consumeBudget();
|
||||
const relayBaseUrl = await resolveKwpRelayBaseUrl(credentials.customerCode, dependencies.outboundOptions);
|
||||
const endpoint = new URL(`/relay/${encodeURIComponent(credentials.customerCode)}/pwa${path}`, `${relayBaseUrl}/`);
|
||||
if (credentials.mandantBinding?.kind === "selected" && path !== KWP_OPENAPI_PATH) {
|
||||
endpoint.searchParams.set("mandant", credentials.mandantBinding.code);
|
||||
}
|
||||
for (const [name, value] of Object.entries(query ?? {})) {
|
||||
appendQueryValue(endpoint.searchParams, name, value);
|
||||
}
|
||||
|
||||
await dependencies.consumeBudget();
|
||||
let response: Response;
|
||||
try {
|
||||
response = await fetchOutboundHttpWithRedirects(
|
||||
endpoint.toString(),
|
||||
{
|
||||
method: method.toUpperCase(),
|
||||
headers: {
|
||||
accept: "application/json",
|
||||
authorization: `Bearer ${credentials.accessToken}`,
|
||||
...(body === undefined ? {} : { "content-type": "application/json" }),
|
||||
},
|
||||
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
||||
},
|
||||
{
|
||||
...dependencies.outboundOptions,
|
||||
allowCrossOriginRedirects: false,
|
||||
urlValidator: validateKwpOnlineUrl,
|
||||
}
|
||||
);
|
||||
} catch (error) {
|
||||
if (error instanceof KwpError) throw error;
|
||||
if (error instanceof OutboundHttpUrlValidationError) throw new KwpError("relay_host_invalid");
|
||||
throw new KwpError("provider_outage");
|
||||
}
|
||||
if (!response.ok) throw mapResourceError(response.status);
|
||||
|
||||
let responseText: string;
|
||||
try {
|
||||
const responseLimit =
|
||||
path === KWP_OPENAPI_PATH
|
||||
? KWP_OPENAPI_RESPONSE_LIMIT_BYTES
|
||||
: path === KWP_PROJECT_CATALOG_PATH
|
||||
? KWP_PROJECT_CATALOG_RESPONSE_LIMIT_BYTES
|
||||
: KWP_RESOURCE_RESPONSE_LIMIT_BYTES;
|
||||
const read = await readLimitedResponseText(response, responseLimit);
|
||||
if (read.truncated) throw new KwpError("contract_drift", response.status);
|
||||
responseText = read.body;
|
||||
} catch (error) {
|
||||
if (error instanceof KwpError) throw error;
|
||||
throw new KwpError("contract_drift", response.status);
|
||||
}
|
||||
try {
|
||||
return JSON.parse(responseText) as unknown;
|
||||
} catch {
|
||||
throw new KwpError("contract_drift", response.status);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The project-import domain intentionally validates a smaller Zod projection
|
||||
* than the complete scoped adapter. KWP's live address payload may use `null`
|
||||
* for documented-but-unconsumed object fields. Those provider inconsistencies
|
||||
* must not pause project import while every field HiveGrid actually maps still
|
||||
* satisfies its explicit schema. The generic 77-operation adapter continues to
|
||||
* use the full checked-in OpenAPI validator in executeReadOperation().
|
||||
*/
|
||||
async function executeProjectedRead(
|
||||
credentials: KwpCredentials,
|
||||
dependencies: KwpResourceTransportDependencies,
|
||||
operationId: KwpReadOperationId,
|
||||
input: KwpOperationInput
|
||||
): Promise<unknown> {
|
||||
assertKwpReadOperationId(operationId);
|
||||
validateKwpOperationInput(operationId, input);
|
||||
const operation = getKwpScopedOperation(operationId);
|
||||
return requestJson(credentials, dependencies, operation.method, operation.path, input.query, input.body);
|
||||
}
|
||||
|
||||
async function requestOpenApi(credentials: KwpCredentials, dependencies: KwpResourceTransportDependencies): Promise<unknown> {
|
||||
return requestJson(credentials, dependencies, "GET", KWP_OPENAPI_PATH);
|
||||
}
|
||||
|
||||
function appendQueryValue(target: URLSearchParams, name: string, value: unknown): void {
|
||||
if (value === undefined || value === null) return;
|
||||
if (Array.isArray(value)) {
|
||||
for (const entry of value) appendQueryValue(target, name, entry);
|
||||
return;
|
||||
}
|
||||
if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
target.append(name, String(value));
|
||||
}
|
||||
|
||||
function mapResourceError(status: number): KwpError {
|
||||
if (status === 401) return new KwpError("auth_token_invalid", status);
|
||||
if (status === 403) return new KwpError("auth_scope_missing", status);
|
||||
if (status === 404) return new KwpError("resource_not_found", status);
|
||||
if (status === 429) return new KwpError("rate_limit_exceeded", status);
|
||||
if (status >= 500) return new KwpError("provider_outage", status);
|
||||
return new KwpError("unknown", status);
|
||||
}
|
||||
|
||||
function normalizeSearchQuery(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (normalized.length < 2 || normalized.length > KWP_QUERY_MAX_LENGTH || /[\u0000-\u001f\u007f]/u.test(normalized)) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeExternalId(value: string): string {
|
||||
const normalized = value.trim();
|
||||
if (!normalized || normalized.length > KWP_EXTERNAL_ID_MAX_LENGTH || /[\u0000-\u001f\u007f]/u.test(normalized)) {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function requireProviderIdentifier(value: string | null): string {
|
||||
const normalized = normalizeNullableIdentifier(value);
|
||||
if (!normalized) throw new KwpError("contract_drift");
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeNullableIdentifier(value: string | null): string | null {
|
||||
if (value === null) return null;
|
||||
const normalized = value.trim();
|
||||
if (!normalized || normalized.length > KWP_EXTERNAL_ID_MAX_LENGTH || /[\u0000-\u001f\u007f]/u.test(normalized)) return null;
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function normalizeNullableText(value: string | null): string | null {
|
||||
if (value === null) return null;
|
||||
const normalized = value.trim();
|
||||
return normalized && !/[\u0000-\u001f\u007f]/u.test(normalized) ? normalized.slice(0, 512) : null;
|
||||
}
|
||||
|
||||
function normalizeRequiredText(value: string | null, fallback: string): string {
|
||||
return normalizeNullableText(value) ?? fallback;
|
||||
}
|
||||
|
||||
function normalizeEmail(value: string | null): string | null {
|
||||
const normalized = normalizeNullableText(value)?.toLowerCase() ?? null;
|
||||
return normalized && /^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(normalized) ? normalized : null;
|
||||
}
|
||||
|
||||
function selectOperation(paths: Record<string, unknown>, path: string, method: "get" | "post"): unknown {
|
||||
const pathItem = asRecord(paths[path]);
|
||||
const operation = asRecord(pathItem?.[method]);
|
||||
if (!operation) throw new KwpError("contract_drift");
|
||||
return {
|
||||
method,
|
||||
path,
|
||||
parameters: Array.isArray(operation.parameters)
|
||||
? operation.parameters.map((parameter) => {
|
||||
const record = asRecord(parameter);
|
||||
return record ? { name: record.name, in: record.in, schema: record.schema } : null;
|
||||
})
|
||||
: [],
|
||||
requestSchema: asRecord(asRecord(asRecord(operation.requestBody)?.content)?.["application/json"])?.schema ?? null,
|
||||
responseSchema: asRecord(asRecord(asRecord(asRecord(operation.responses)?.["200"])?.content)?.["application/json"])?.schema ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
const CONSUMED_SCHEMA_FIELDS = Object.freeze({
|
||||
"Kwp.Api.Service.Dto.DtoValue": ["value"],
|
||||
"Kwp.Api.Service.Dto.Projekte.DtoSearchResultProjekt": ["projNr", "projBezeichnung", "projAdr", "rechAdr", "bauHrAdr", "auftragStatus"],
|
||||
"Kwp.Api.Model.Values.ProjektHauptstatus": [],
|
||||
"Kwp.Api.Service.Dto.Projektampel.DtoProjektampelProjekt": ["projNr", "projBezeichnung", "beginn", "adresse", "auftragssumme"],
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAdresse": ["adrNrGes", "name", "vorname", "zusatz", "strasse", "ort"],
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAdresseKomplett": [
|
||||
"adrNrGes",
|
||||
"name",
|
||||
"vorname",
|
||||
"zusatz",
|
||||
"strasse",
|
||||
"ort",
|
||||
"rechnungsmailadresse",
|
||||
"kontakte",
|
||||
"ansprechpartner",
|
||||
],
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoOrt": ["ortId", "land", "plz", "ort"],
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoKontakt": ["kontaktart", "kontakt", "ansprechpartnerId"],
|
||||
"Kwp.Api.Service.Dto.Adressen.DtoAnsprechpartner": ["nachname", "vorname", "ansprechpartnerId", "zusatz", "kontakte"],
|
||||
"Kwp.Api.Model.Values.Adresse.Kontaktart": [],
|
||||
} as const);
|
||||
|
||||
function selectConsumedSchemas(schemas: Record<string, unknown>): Record<string, unknown> {
|
||||
return Object.fromEntries(
|
||||
Object.entries(CONSUMED_SCHEMA_FIELDS).map(([name, fields]) => {
|
||||
const schema = asRecord(schemas[name]);
|
||||
if (!schema) throw new KwpError("contract_drift");
|
||||
const properties = asRecord(schema.properties) ?? {};
|
||||
for (const field of fields) if (!(field in properties)) throw new KwpError("contract_drift");
|
||||
return [
|
||||
name,
|
||||
fields.length === 0
|
||||
? { type: schema.type, format: schema.format, enum: schema.enum }
|
||||
: {
|
||||
type: schema.type,
|
||||
properties: Object.fromEntries(fields.map((field) => [field, properties[field]])),
|
||||
},
|
||||
];
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> | null {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
|
||||
}
|
||||
|
||||
function canonicalJson(value: unknown): string {
|
||||
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
|
||||
if (value && typeof value === "object") {
|
||||
return `{${Object.entries(value as Record<string, unknown>)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, nested]) => `${JSON.stringify(key)}:${canonicalJson(nested)}`)
|
||||
.join(",")}}`;
|
||||
}
|
||||
return JSON.stringify(value) ?? "null";
|
||||
}
|
||||
+199
@@ -0,0 +1,199 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import scopedOpenApi from "./contract/kwp-scoped-openapi.json" with { type: "json" };
|
||||
import {
|
||||
buildKwpCapabilitySemanticContract,
|
||||
getKwpScopedOperation,
|
||||
KWP_SCOPED_OPERATIONS,
|
||||
KWP_SCOPED_OPERATION_INVENTORY,
|
||||
listKwpCapabilities,
|
||||
parseKwpOperationResponse,
|
||||
rejectKwpMutationOperation,
|
||||
validateKwpOperationInput,
|
||||
validateKwpOperationResponse,
|
||||
validateKwpScopedOpenApi,
|
||||
type KwpMutationOperationId,
|
||||
type KwpOperationInput,
|
||||
} from "./scoped-contract.js";
|
||||
|
||||
type JsonRecord = Record<string, unknown>;
|
||||
|
||||
describe("KWP scoped contract", () => {
|
||||
it("keeps the complete licensed inventory explicit and duplicate-free", () => {
|
||||
expect(KWP_SCOPED_OPERATION_INVENTORY).toEqual({
|
||||
sourceOperationCount: 554,
|
||||
scopedOperationCount: 113,
|
||||
readOperationCount: 77,
|
||||
mutationOperationCount: 36,
|
||||
excludedOperationCount: 441,
|
||||
});
|
||||
expect(new Set(KWP_SCOPED_OPERATIONS.map((operation) => operation.id))).toHaveLength(113);
|
||||
expect(new Set(KWP_SCOPED_OPERATIONS.map((operation) => `${operation.method} ${operation.path}`))).toHaveLength(113);
|
||||
expect(KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "read")).toHaveLength(77);
|
||||
expect(KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "mutation")).toHaveLength(36);
|
||||
});
|
||||
|
||||
it("keeps provider documentation markup out of the runtime contract", () => {
|
||||
expect(JSON.stringify(scopedOpenApi)).not.toContain('"description":');
|
||||
});
|
||||
|
||||
it("compiles and fixture-validates every scoped request and response schema", () => {
|
||||
const document = scopedOpenApi as unknown as JsonRecord;
|
||||
for (const operation of KWP_SCOPED_OPERATIONS) {
|
||||
const contract = readOperationContract(document, operation.path, operation.method);
|
||||
const input = buildInputFixture(document, contract);
|
||||
const response = buildResponseFixture(document, contract);
|
||||
|
||||
expect(() => validateKwpOperationInput(operation.id, input)).not.toThrow();
|
||||
expect(() => validateKwpOperationResponse(operation.id, response)).not.toThrow();
|
||||
}
|
||||
});
|
||||
|
||||
it("keeps all mutation contracts unavailable to runtime transport", () => {
|
||||
const mutations = KWP_SCOPED_OPERATIONS.filter((operation) => operation.mode === "mutation");
|
||||
expect(mutations).toHaveLength(36);
|
||||
for (const operation of mutations) {
|
||||
expect(() => rejectKwpMutationOperation(operation.id as KwpMutationOperationId)).toThrowError("invalid_credentials");
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects caller-controlled mandant context", () => {
|
||||
expect(() =>
|
||||
validateKwpOperationInput("projektSearch", {
|
||||
query: { mandant: "other-tenant" },
|
||||
body: { value: "Projekt" },
|
||||
})
|
||||
).toThrowError("invalid_credentials");
|
||||
});
|
||||
|
||||
it("removes forbidden address data from generic adapter responses", () => {
|
||||
const parsed = parseKwpOperationResponse("adresseLoadAdressKomplett", {
|
||||
adrNrGes: "A-1",
|
||||
iban: "DE001234",
|
||||
bank: "Provider Bank",
|
||||
kreditLimit: 12_500,
|
||||
steuerNummer: "TAX-1",
|
||||
geburtstag: "1990-01-01T00:00:00.000Z",
|
||||
hinweis: "internal",
|
||||
bemerkung: "private",
|
||||
benutzerFeld1: "custom",
|
||||
ansprechpartner: [
|
||||
{
|
||||
ansprechpartnerId: 1,
|
||||
nachname: "Kontakt",
|
||||
benutzerFeld2: "nested",
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
expect(parsed).toEqual({
|
||||
adrNrGes: "A-1",
|
||||
ansprechpartner: [
|
||||
{
|
||||
ansprechpartnerId: 1,
|
||||
nachname: "Kontakt",
|
||||
},
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it("isolates semantic drift by capability", () => {
|
||||
validateKwpScopedOpenApi(scopedOpenApi);
|
||||
const baseline = Object.fromEntries(
|
||||
listKwpCapabilities().map((capability) => [capability, buildKwpCapabilitySemanticContract(scopedOpenApi, capability).semanticFingerprint])
|
||||
);
|
||||
const drifted = structuredClone(scopedOpenApi) as unknown as JsonRecord;
|
||||
const paths = drifted.paths as JsonRecord;
|
||||
const addressPath = paths["/api/Adresse/LoadAdressDetails"] as JsonRecord;
|
||||
const addressGet = addressPath.get as JsonRecord;
|
||||
const parameters = addressGet.parameters as JsonRecord[];
|
||||
const addressCode = parameters.find((parameter) => parameter.name === "adresskuerzel");
|
||||
(addressCode!.schema as JsonRecord).maxLength = 190;
|
||||
|
||||
const observed = Object.fromEntries(
|
||||
listKwpCapabilities().map((capability) => [capability, buildKwpCapabilitySemanticContract(drifted, capability).semanticFingerprint])
|
||||
);
|
||||
expect(observed.address).not.toBe(baseline.address);
|
||||
expect(observed.activity).toBe(baseline.activity);
|
||||
expect(observed.archive).toBe(baseline.archive);
|
||||
expect(observed.project).toBe(baseline.project);
|
||||
expect(observed.schedule).toBe(baseline.schedule);
|
||||
});
|
||||
|
||||
it("rejects unknown operation ids without exposing a free path", () => {
|
||||
expect(() => getKwpScopedOperation("freePath" as never)).toThrowError("invalid_credentials");
|
||||
});
|
||||
});
|
||||
|
||||
function readOperationContract(document: JsonRecord, path: string, method: string): JsonRecord {
|
||||
const paths = document.paths as JsonRecord;
|
||||
return (paths[path] as JsonRecord)[method.toLowerCase()] as JsonRecord;
|
||||
}
|
||||
|
||||
function buildInputFixture(document: JsonRecord, operation: JsonRecord): KwpOperationInput {
|
||||
const input: { query?: JsonRecord; body?: unknown } = {};
|
||||
const query: JsonRecord = {};
|
||||
const parameters = Array.isArray(operation.parameters) ? operation.parameters : [];
|
||||
for (const parameterValue of parameters) {
|
||||
const parameter = parameterValue as JsonRecord;
|
||||
if (parameter.in !== "query" || parameter.name === "mandant" || parameter.required !== true) {
|
||||
continue;
|
||||
}
|
||||
query[String(parameter.name)] = buildSchemaFixture(document, parameter.schema);
|
||||
}
|
||||
if (Object.keys(query).length > 0) input.query = query;
|
||||
const requestBody = operation.requestBody as JsonRecord | undefined;
|
||||
const bodySchema = selectContentSchema(requestBody?.content);
|
||||
if (bodySchema) input.body = buildSchemaFixture(document, bodySchema);
|
||||
return input;
|
||||
}
|
||||
|
||||
function buildResponseFixture(document: JsonRecord, operation: JsonRecord): unknown {
|
||||
const responses = operation.responses as JsonRecord;
|
||||
const success = (responses["200"] ?? responses["201"] ?? responses["202"] ?? responses["204"]) as JsonRecord;
|
||||
const schema = selectContentSchema(success?.content);
|
||||
return schema ? buildSchemaFixture(document, schema) : undefined;
|
||||
}
|
||||
|
||||
function selectContentSchema(contentValue: unknown): unknown | null {
|
||||
const content = contentValue as JsonRecord | undefined;
|
||||
for (const type of ["application/json", "text/json", "text/plain"]) {
|
||||
const media = content?.[type] as JsonRecord | undefined;
|
||||
if (media?.schema) return media.schema;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function buildSchemaFixture(document: JsonRecord, schemaValue: unknown): unknown {
|
||||
const schema = schemaValue as JsonRecord;
|
||||
if (typeof schema.$ref === "string") {
|
||||
const name = schema.$ref.replace("#/components/schemas/", "");
|
||||
const components = document.components as JsonRecord;
|
||||
const schemas = components.schemas as JsonRecord;
|
||||
return buildSchemaFixture(document, schemas[name]);
|
||||
}
|
||||
if (schema.nullable === true) return null;
|
||||
if (schema.example !== undefined) return structuredClone(schema.example);
|
||||
if (schema.default !== undefined) return structuredClone(schema.default);
|
||||
if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
|
||||
if (schema.type === "object" || schema.properties) {
|
||||
const properties = (schema.properties ?? {}) as JsonRecord;
|
||||
const required = Array.isArray(schema.required) ? schema.required : [];
|
||||
return Object.fromEntries(required.map((name) => [String(name), buildSchemaFixture(document, properties[String(name)])]));
|
||||
}
|
||||
if (schema.type === "array") {
|
||||
const minimum = typeof schema.minItems === "number" ? schema.minItems : 0;
|
||||
return Array.from({ length: minimum }, () => buildSchemaFixture(document, schema.items));
|
||||
}
|
||||
if (schema.type === "boolean") return false;
|
||||
if (schema.type === "integer" || schema.type === "number") {
|
||||
return typeof schema.minimum === "number" ? schema.minimum : 0;
|
||||
}
|
||||
if (schema.type === "string") {
|
||||
if (schema.format === "date-time") return "2026-07-24T00:00:00.000Z";
|
||||
if (schema.format === "uuid") return "00000000-0000-4000-8000-000000000000";
|
||||
if (schema.format === "uri") return "https://example.invalid/fixture";
|
||||
return "fixture";
|
||||
}
|
||||
return {};
|
||||
}
|
||||
+333
@@ -0,0 +1,333 @@
|
||||
import { createHash } from "node:crypto";
|
||||
|
||||
import { Ajv, type AnySchema, type ValidateFunction } from "ajv";
|
||||
|
||||
import scopedOpenApi from "./contract/kwp-scoped-openapi.json" with { type: "json" };
|
||||
import {
|
||||
KWP_SCOPED_OPERATIONS,
|
||||
type KwpCapability,
|
||||
type KwpMutationOperationId,
|
||||
type KwpReadOperationId,
|
||||
type KwpScopedOperation,
|
||||
type KwpScopedOperationId,
|
||||
} from "./contract/catalog.generated.js";
|
||||
import { KwpError } from "./client.js";
|
||||
|
||||
export {
|
||||
KWP_SCOPED_OPERATIONS,
|
||||
KWP_SCOPED_OPERATION_INVENTORY,
|
||||
type KwpCapability,
|
||||
type KwpMutationOperationId,
|
||||
type KwpReadOperationId,
|
||||
type KwpScopedOperation,
|
||||
type KwpScopedOperationId,
|
||||
} from "./contract/catalog.generated.js";
|
||||
|
||||
export type KwpOperationInput = {
|
||||
readonly query?: Readonly<Record<string, unknown>>;
|
||||
readonly body?: unknown;
|
||||
};
|
||||
|
||||
export type KwpCapabilitySemanticContract = {
|
||||
readonly apiVersion: string;
|
||||
readonly capability: KwpCapability;
|
||||
readonly semanticFingerprint: string;
|
||||
readonly consumedContract: Record<string, unknown>;
|
||||
};
|
||||
|
||||
type OpenApiDocument = {
|
||||
readonly info: { readonly version: string };
|
||||
readonly paths: Readonly<Record<string, unknown>>;
|
||||
readonly components: {
|
||||
readonly schemas: Readonly<Record<string, unknown>>;
|
||||
};
|
||||
};
|
||||
|
||||
type OperationContract = {
|
||||
readonly parameters?: readonly unknown[];
|
||||
readonly requestBody?: unknown;
|
||||
readonly responses?: Readonly<Record<string, unknown>>;
|
||||
};
|
||||
|
||||
const operationById = new Map<KwpScopedOperationId, KwpScopedOperation>(KWP_SCOPED_OPERATIONS.map((operation) => [operation.id, operation]));
|
||||
const validatorByOperation = new Map<KwpScopedOperationId, { readonly input: ValidateFunction; readonly response: ValidateFunction | null }>();
|
||||
const ajv = new Ajv({
|
||||
allErrors: true,
|
||||
removeAdditional: "all",
|
||||
strict: false,
|
||||
validateFormats: false,
|
||||
});
|
||||
const contract = scopedOpenApi as unknown as OpenApiDocument;
|
||||
const KWP_ADDRESS_FORBIDDEN_FIELDS = new Set([
|
||||
"bank",
|
||||
"bemerkung",
|
||||
"benutzerfeld1",
|
||||
"benutzerfeld2",
|
||||
"benutzerfeld3",
|
||||
"benutzerfeld4",
|
||||
"benutzerfeld5",
|
||||
"geburtstag",
|
||||
"hinweis",
|
||||
"iban",
|
||||
"kreditlimit",
|
||||
"steuernummer",
|
||||
"steuerid",
|
||||
"ustid",
|
||||
"ustidnr",
|
||||
]);
|
||||
|
||||
export function getKwpScopedOperation(operationId: KwpScopedOperationId): KwpScopedOperation {
|
||||
const operation = operationById.get(operationId);
|
||||
if (!operation) throw new KwpError("invalid_credentials");
|
||||
return operation;
|
||||
}
|
||||
|
||||
export function assertKwpReadOperationId(operationId: KwpScopedOperationId): asserts operationId is KwpReadOperationId {
|
||||
if (getKwpScopedOperation(operationId).mode !== "read") {
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Mutation contracts are intentionally present for drift/fixture coverage but
|
||||
* cannot become provider calls until VEXT-6 and a later product approval.
|
||||
*/
|
||||
export function rejectKwpMutationOperation(operationId: KwpMutationOperationId): never {
|
||||
const operation = getKwpScopedOperation(operationId);
|
||||
if (operation.mode !== "mutation") throw new KwpError("invalid_credentials");
|
||||
throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
export function validateKwpOperationInput(operationId: KwpScopedOperationId, input: KwpOperationInput): void {
|
||||
assertNoInjectedContext(input);
|
||||
const validators = getOperationValidators(operationId);
|
||||
if (!validators.input(input)) throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
export function validateKwpOperationResponse(operationId: KwpScopedOperationId, value: unknown): void {
|
||||
parseKwpOperationResponse(operationId, value);
|
||||
}
|
||||
|
||||
export function parseKwpOperationResponse(operationId: KwpScopedOperationId, value: unknown): unknown {
|
||||
const validator = getOperationValidators(operationId).response;
|
||||
const operation = getKwpScopedOperation(operationId);
|
||||
const clonedValue = structuredClone(value);
|
||||
const safeValue = operation.capability === "address" ? redactForbiddenAddressFields(clonedValue) : clonedValue;
|
||||
if (validator && !validator(safeValue)) throw new KwpError("contract_drift");
|
||||
if (!validator && value !== undefined && value !== null && value !== "") {
|
||||
throw new KwpError("contract_drift");
|
||||
}
|
||||
return safeValue;
|
||||
}
|
||||
|
||||
export function buildKwpCapabilitySemanticContract(value: unknown, capability: KwpCapability): KwpCapabilitySemanticContract {
|
||||
const live = parseOpenApiDocument(value);
|
||||
const operations = KWP_SCOPED_OPERATIONS.filter((operation) => operation.capability === capability);
|
||||
const selectedPaths: Record<string, Record<string, unknown>> = {};
|
||||
for (const operation of operations) {
|
||||
const pathItem = asRecord(live.paths[operation.path]);
|
||||
const operationContract = asRecord(pathItem?.[operation.method.toLowerCase()]);
|
||||
if (!operationContract) throw new KwpError("contract_drift");
|
||||
selectedPaths[operation.path] ??= {};
|
||||
selectedPaths[operation.path]![operation.method.toLowerCase()] = selectSemanticOperation(operationContract, operation);
|
||||
}
|
||||
const schemaNames = collectReferencedSchemaNames(selectedPaths, live.components.schemas);
|
||||
const schemas = Object.fromEntries([...schemaNames].sort((left, right) => left.localeCompare(right)).map((name) => [name, live.components.schemas[name]]));
|
||||
const consumedContract = {
|
||||
operations: canonicalize(selectedPaths),
|
||||
schemas: canonicalize(schemas),
|
||||
};
|
||||
return {
|
||||
apiVersion: live.info.version,
|
||||
capability,
|
||||
semanticFingerprint: createHash("sha256").update(JSON.stringify(consumedContract)).digest("hex"),
|
||||
consumedContract,
|
||||
};
|
||||
}
|
||||
|
||||
export function validateKwpScopedOpenApi(value: unknown): void {
|
||||
for (const capability of listKwpCapabilities()) {
|
||||
buildKwpCapabilitySemanticContract(value, capability);
|
||||
}
|
||||
}
|
||||
|
||||
export function listKwpCapabilities(): readonly KwpCapability[] {
|
||||
return ["activity", "address", "archive", "project", "schedule"];
|
||||
}
|
||||
|
||||
function getOperationValidators(operationId: KwpScopedOperationId) {
|
||||
const cached = validatorByOperation.get(operationId);
|
||||
if (cached) return cached;
|
||||
const operation = getKwpScopedOperation(operationId);
|
||||
const operationContract = getSnapshotOperationContract(operation);
|
||||
const validators = {
|
||||
input: ajv.compile(buildInputSchema(operationContract)),
|
||||
response: buildResponseSchema(operationContract),
|
||||
};
|
||||
validatorByOperation.set(operationId, validators);
|
||||
return validators;
|
||||
}
|
||||
|
||||
function getSnapshotOperationContract(operation: KwpScopedOperation): OperationContract {
|
||||
const pathItem = asRecord(contract.paths[operation.path]);
|
||||
const value = asRecord(pathItem?.[operation.method.toLowerCase()]);
|
||||
if (!value) throw new KwpError("contract_drift");
|
||||
return value as OperationContract;
|
||||
}
|
||||
|
||||
function buildInputSchema(operation: OperationContract): AnySchema {
|
||||
const queryParameters = (operation.parameters ?? [])
|
||||
.map(asRecord)
|
||||
.filter((parameter): parameter is Record<string, unknown> => parameter !== null && parameter.in === "query" && parameter.name !== "mandant");
|
||||
const queryProperties = Object.fromEntries(queryParameters.map((parameter) => [String(parameter.name), parameter.schema ?? {}]));
|
||||
const requiredQuery = queryParameters.filter((parameter) => parameter.required === true).map((parameter) => String(parameter.name));
|
||||
const requestBody = asRecord(operation.requestBody);
|
||||
const bodySchema = selectJsonSchemaFromContent(requestBody?.content);
|
||||
const properties: Record<string, unknown> = {};
|
||||
const required: string[] = [];
|
||||
if (queryParameters.length > 0) {
|
||||
properties.query = {
|
||||
type: "object",
|
||||
properties: queryProperties,
|
||||
required: requiredQuery,
|
||||
additionalProperties: false,
|
||||
};
|
||||
if (requiredQuery.length > 0) required.push("query");
|
||||
}
|
||||
if (bodySchema) {
|
||||
properties.body = bodySchema;
|
||||
if (requestBody?.required === true) required.push("body");
|
||||
}
|
||||
return withComponents({
|
||||
type: "object",
|
||||
properties,
|
||||
required,
|
||||
additionalProperties: false,
|
||||
});
|
||||
}
|
||||
|
||||
function buildResponseSchema(operation: OperationContract): ValidateFunction | null {
|
||||
const responses = operation.responses ?? {};
|
||||
const success = asRecord(responses["200"] ?? responses["201"] ?? responses["202"] ?? responses["204"]);
|
||||
const responseSchema = selectJsonSchemaFromContent(success?.content);
|
||||
return responseSchema ? ajv.compile(withComponents(responseSchema)) : null;
|
||||
}
|
||||
|
||||
function selectJsonSchemaFromContent(value: unknown): unknown | null {
|
||||
const content = asRecord(value);
|
||||
if (!content) return null;
|
||||
for (const contentType of ["application/json", "text/json", "text/plain"]) {
|
||||
const media = asRecord(content[contentType]);
|
||||
if (media?.schema) return media.schema;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function withComponents(schema: unknown): AnySchema {
|
||||
return {
|
||||
...(asRecord(schema) ?? {}),
|
||||
components: contract.components,
|
||||
} as AnySchema;
|
||||
}
|
||||
|
||||
function assertNoInjectedContext(input: KwpOperationInput): void {
|
||||
const query = input.query ?? {};
|
||||
const forbidden = Object.keys(query).some((name) => name.toLowerCase() === "mandant" || name.toLowerCase() === "x-kwp-client-version");
|
||||
if (forbidden) throw new KwpError("invalid_credentials");
|
||||
}
|
||||
|
||||
function redactForbiddenAddressFields(value: unknown): unknown {
|
||||
if (Array.isArray(value)) return value.map(redactForbiddenAddressFields);
|
||||
const record = asRecord(value);
|
||||
if (!record) return value;
|
||||
return Object.fromEntries(
|
||||
Object.entries(record)
|
||||
.filter(([key]) => !KWP_ADDRESS_FORBIDDEN_FIELDS.has(key.toLowerCase()))
|
||||
.map(([key, nested]) => [key, redactForbiddenAddressFields(nested)])
|
||||
);
|
||||
}
|
||||
|
||||
function parseOpenApiDocument(value: unknown): OpenApiDocument {
|
||||
const document = asRecord(value);
|
||||
const info = asRecord(document?.info);
|
||||
const paths = asRecord(document?.paths);
|
||||
const components = asRecord(document?.components);
|
||||
const schemas = asRecord(components?.schemas);
|
||||
if (!document || typeof info?.version !== "string" || info.version.length === 0 || !paths || !schemas) {
|
||||
throw new KwpError("contract_drift");
|
||||
}
|
||||
return {
|
||||
info: { version: info.version },
|
||||
paths,
|
||||
components: { schemas },
|
||||
};
|
||||
}
|
||||
|
||||
function selectSemanticOperation(operationContract: Record<string, unknown>, operation: KwpScopedOperation): Record<string, unknown> {
|
||||
const parameters = Array.isArray(operationContract.parameters)
|
||||
? operationContract.parameters.map((parameter) => {
|
||||
const record = asRecord(parameter);
|
||||
return record
|
||||
? {
|
||||
name: record.name,
|
||||
in: record.in,
|
||||
required: record.required ?? false,
|
||||
schema: record.schema ?? null,
|
||||
}
|
||||
: null;
|
||||
})
|
||||
: [];
|
||||
const requestBody = asRecord(operationContract.requestBody);
|
||||
const responses = asRecord(operationContract.responses);
|
||||
const success = asRecord(responses?.["200"] ?? responses?.["201"] ?? responses?.["202"] ?? responses?.["204"]);
|
||||
return {
|
||||
id: operation.id,
|
||||
method: operation.method,
|
||||
path: operation.path,
|
||||
mode: operation.mode,
|
||||
parameters,
|
||||
requestSchema: selectJsonSchemaFromContent(requestBody?.content),
|
||||
responseSchema: selectJsonSchemaFromContent(success?.content),
|
||||
};
|
||||
}
|
||||
|
||||
function collectReferencedSchemaNames(value: unknown, schemas: Readonly<Record<string, unknown>>): Set<string> {
|
||||
const found = new Set<string>();
|
||||
const pending = [...findRefs(value)];
|
||||
while (pending.length > 0) {
|
||||
const ref = pending.pop();
|
||||
if (!ref) continue;
|
||||
const prefix = "#/components/schemas/";
|
||||
if (!ref.startsWith(prefix)) throw new KwpError("contract_drift");
|
||||
const name = decodeURIComponent(ref.slice(prefix.length));
|
||||
if (found.has(name)) continue;
|
||||
const schema = schemas[name];
|
||||
if (!schema) throw new KwpError("contract_drift");
|
||||
found.add(name);
|
||||
pending.push(...findRefs(schema));
|
||||
}
|
||||
return found;
|
||||
}
|
||||
|
||||
function findRefs(value: unknown): string[] {
|
||||
if (Array.isArray(value)) return value.flatMap(findRefs);
|
||||
const record = asRecord(value);
|
||||
if (!record) return [];
|
||||
return Object.entries(record).flatMap(([key, nested]) => (key === "$ref" && typeof nested === "string" ? [nested] : findRefs(nested)));
|
||||
}
|
||||
|
||||
function canonicalize(value: unknown): unknown {
|
||||
if (Array.isArray(value)) return value.map(canonicalize);
|
||||
const record = asRecord(value);
|
||||
if (!record) return value;
|
||||
return Object.fromEntries(
|
||||
Object.entries(record)
|
||||
.sort(([left], [right]) => left.localeCompare(right))
|
||||
.map(([key, nested]) => [key, canonicalize(nested)])
|
||||
);
|
||||
}
|
||||
|
||||
function asRecord(value: unknown): Record<string, unknown> | null {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) return null;
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
Loaded 100 of 5955 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user