Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,130 @@
// VA-P23 · provider-agnostic EmailProviderAdapter contract (M09 Block J).
//
// Two implementations ship in v2: GmailAdapter.server.ts and
// MicrosoftMailAdapter.server.ts. The adapter is a thin PROVIDER BOUNDARY:
// given decrypted creds it performs one network op and returns provider-neutral
// data. The per-user orchestration (cursor persistence, message upserts,
// auto-match, activity) lives in the sync services/worker tasks, not here.
//
// Neutral types deliberately avoid provider naming so both providers (and later
// ones) map into the same domain shapes.
import type { MappedEmailAddress, MappedEmailMessage } from "@hivegrid/integrations";
/** A mailbox's decrypted OAuth credentials (the engine handles envelope crypto). */
export interface EmailCreds {
readonly accessToken: string;
readonly refreshToken: string;
readonly expiresAt?: Date | null;
}
export interface EmailTokens {
readonly accessToken: string;
/** Present on the initial code exchange (Graph also rotates it on refresh). */
readonly refreshToken?: string;
readonly expiresAt: Date;
readonly scopes: readonly string[];
}
export interface EmailAccount {
readonly email: string;
readonly accountId: string;
readonly displayName?: string;
}
// The neutral message/address shapes are SHARED with the worker sync tasks and
// live in @hivegrid/integrations (email-message-mapping.ts) — one mapping, no
// drift between connect-time and cron-time sync.
export type NeutralAddress = MappedEmailAddress;
export type NeutralMessage = MappedEmailMessage;
export interface NeutralAttachmentMeta {
readonly attachmentId: string;
readonly filename: string;
readonly mimeType: string | null;
readonly sizeBytes: number;
}
export interface NeutralAttachmentContent extends NeutralAttachmentMeta {
/** Standard base64 (not base64url) so it can stream into storage directly. */
readonly contentBase64: string;
}
/** One page of the incremental (or initial) pull. */
export interface MailDeltaResult {
readonly messages: readonly NeutralMessage[];
/** Persist as the folder cursor when present (page set complete). */
readonly nextCursor?: string;
/** Continue paging within the same drain when present. */
readonly nextPageToken?: string;
/** True when the provider expired the cursor → bounded full resync. */
readonly fullResyncRequired?: boolean;
}
export interface MailWebhookSubscription {
readonly subscriptionId: string;
readonly expiresAt: Date | null;
/** Provider anchor delivered on subscribe (Gmail historyId); null for Graph. */
readonly initialCursor: string | null;
}
export interface SendMailInput {
readonly to: readonly NeutralAddress[];
readonly cc?: readonly NeutralAddress[];
readonly bcc?: readonly NeutralAddress[];
readonly subject: string;
readonly bodyHtml: string;
readonly bodyText?: string;
readonly attachments?: ReadonlyArray<{ filename: string; mimeType: string; contentBase64: string }>;
/** Reply threading: provider thread + the message-id being answered. */
readonly providerThreadId?: string | null;
readonly inReplyToInternetMessageId?: string | null;
readonly referencesInternetMessageIds?: readonly string[];
}
export interface SendMailResult {
/** Graph sendMail returns 202 without an id → null (sent-items delta dedupes). */
readonly providerMessageId: string | null;
readonly providerThreadId: string | null;
}
/**
* Folder identifiers a sync cursor is keyed by. Gmail history is mailbox-global
* → the single pseudo-folder "*"; Graph delta is per real folder.
*/
export const GMAIL_GLOBAL_FOLDER = "*";
export const GRAPH_SYNC_FOLDERS = ["inbox", "sentitems"] as const;
export interface EmailProviderAdapter {
readonly provider: "gmail" | "microsoft";
/** True only when the provider OAuth config is present (env). */
isConfigured(): boolean;
buildAuthorizationUrl(state: string): string;
exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }>;
refreshTokens(refreshToken: string): Promise<EmailTokens>;
/**
* Subscribe the mailbox to push notifications. `notificationUrl` is the public
* webhook endpoint; `clientState` the per-mailbox verification secret.
*/
subscribeWebhook(creds: EmailCreds, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription>;
/** Renew an expiring subscription (Graph PATCH; Gmail re-issues the watch). */
renewWebhook(creds: EmailCreds, subscriptionId: string, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription>;
revokeWebhook(creds: EmailCreds, subscriptionId: string): Promise<void>;
/** Best-effort provider-side token revoke (Graph has none → no-op). */
revokeTokens(creds: EmailCreds): Promise<void>;
/**
* Pull messages for one folder. `cursor` is the stored incremental cursor
* (Gmail historyId / Graph deltaLink); absent → bounded initial pull from
* `initialSince`. `pageToken` continues a multi-page drain.
*/
fetchMessages(
creds: EmailCreds,
folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult>;
getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null>;
sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult>;
markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void>;
listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]>;
downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null>;
}
@@ -0,0 +1,209 @@
// VA-P23 · Gmail implementation of the provider-agnostic EmailProviderAdapter.
//
// Maps the neutral domain shapes to/from the shared @hivegrid/integrations Gmail
// REST client. No Prisma here — the adapter only does network I/O against Google
// and provider↔neutral mapping. Token storage/crypto + orchestration live in the
// connection/sync services (mirrors GoogleCalendarAdapter.server.ts).
import {
GmailError,
buildGmailAuthorizationUrl,
buildRfc2822Message,
exchangeGmailCodeForTokens,
fetchGmailUserInfo,
getAttachment,
getMessage,
listHistory,
listMessageIds,
mapGmailMessage,
modifyMessageLabels,
refreshGmailAccessToken,
resolveGmailOAuthConfig,
revokeGmailToken,
sendRawMessage,
stopWatchMailbox,
toBase64Url,
watchMailbox,
type GmailOAuthConfig,
} from "@hivegrid/integrations";
import {
GMAIL_GLOBAL_FOLDER,
type EmailAccount,
type EmailCreds,
type EmailProviderAdapter,
type EmailTokens,
type MailDeltaResult,
type MailWebhookSubscription,
type NeutralAttachmentContent,
type NeutralAttachmentMeta,
type NeutralMessage,
type SendMailInput,
type SendMailResult,
} from "./EmailProviderAdapter";
/** Thrown when the OAuth config (VEXT-5 env) is absent — surfaced as Klartext. */
export class EmailInboxNotConfiguredError extends Error {
constructor(provider: string) {
super(`email_inbox_not_configured:${provider}`);
this.name = "EmailInboxNotConfiguredError";
}
}
function requireConfig(): GmailOAuthConfig {
const config = resolveGmailOAuthConfig();
if (!config) {
throw new EmailInboxNotConfiguredError("gmail");
}
return config;
}
/** Initial-sync query: bounded window, no spam/trash (M09 Block D). */
function initialSyncQuery(initialSince: Date | undefined): string {
const days = initialSince ? Math.max(1, Math.ceil((Date.now() - initialSince.getTime()) / 86_400_000)) : 90;
return `newer_than:${days}d -in:spam -in:trash`;
}
async function fetchMapped(accessToken: string, messageIds: readonly string[]): Promise<NeutralMessage[]> {
const messages: NeutralMessage[] = [];
for (const id of messageIds) {
try {
const raw = await getMessage(accessToken, id, "full");
messages.push(mapGmailMessage(raw));
} catch (error) {
// A message deleted between listing and fetching is not an error.
if (error instanceof GmailError && error.code === "message_not_found") {
continue;
}
throw error;
}
}
return messages;
}
export const gmailProviderAdapter: EmailProviderAdapter = {
provider: "gmail",
isConfigured(): boolean {
return resolveGmailOAuthConfig() !== null;
},
buildAuthorizationUrl(state: string): string {
return buildGmailAuthorizationUrl(requireConfig(), state);
},
async exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }> {
const config = requireConfig();
const tokenSet = await exchangeGmailCodeForTokens(config, code);
const info = await fetchGmailUserInfo(tokenSet.accessToken);
return {
tokens: { accessToken: tokenSet.accessToken, refreshToken: tokenSet.refreshToken, expiresAt: tokenSet.expiresAt, scopes: tokenSet.scopes },
account: { email: info.email, accountId: info.sub },
};
},
async refreshTokens(refreshToken: string): Promise<EmailTokens> {
const set = await refreshGmailAccessToken(requireConfig(), refreshToken);
return { accessToken: set.accessToken, refreshToken: set.refreshToken, expiresAt: set.expiresAt, scopes: set.scopes };
},
async subscribeWebhook(creds: EmailCreds): Promise<MailWebhookSubscription> {
const config = requireConfig();
const watch = await watchMailbox(creds.accessToken, config.pubsubTopic);
// Gmail has no per-watch id; the mailbox address routes the push. We anchor
// the incremental sync at the watch's historyId.
return { subscriptionId: `gmail-watch`, expiresAt: watch.expiresAt, initialCursor: watch.historyId || null };
},
async renewWebhook(creds: EmailCreds): Promise<MailWebhookSubscription> {
// Gmail renewal = re-issue users.watch (watches expire after ~7 days).
return this.subscribeWebhook(creds, "", "");
},
async revokeWebhook(creds: EmailCreds): Promise<void> {
await stopWatchMailbox(creds.accessToken);
},
async revokeTokens(creds: EmailCreds): Promise<void> {
await revokeGmailToken(creds.refreshToken || creds.accessToken);
},
async fetchMessages(
creds: EmailCreds,
_folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult> {
// Incremental: history since the stored historyId cursor.
if (opts.cursor) {
try {
const page = await listHistory(creds.accessToken, opts.cursor, opts.pageToken ?? undefined);
const messages = await fetchMapped(creds.accessToken, page.addedMessageIds);
return { messages, nextCursor: page.historyId, nextPageToken: page.nextPageToken };
} catch (error) {
if (error instanceof GmailError && error.fullResyncRequired) {
return { messages: [], fullResyncRequired: true };
}
throw error;
}
}
// Initial bounded pull (resumable via pageToken persisted in the cursor row).
const page = await listMessageIds(creds.accessToken, {
q: initialSyncQuery(opts.initialSince),
pageToken: opts.pageToken ?? undefined,
maxResults: 50,
});
const messages = await fetchMapped(creds.accessToken, page.messageIds);
return { messages, nextPageToken: page.nextPageToken };
},
async getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null> {
try {
return mapGmailMessage(await getMessage(creds.accessToken, providerMessageId, "full"));
} catch (error) {
if (error instanceof GmailError && error.code === "message_not_found") {
return null;
}
throw error;
}
},
async sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult> {
const info = await fetchGmailUserInfo(creds.accessToken);
const raw = buildRfc2822Message({
fromAddress: info.email,
to: input.to,
cc: input.cc,
bcc: input.bcc,
subject: input.subject,
bodyHtml: input.bodyHtml,
inReplyToInternetMessageId: input.inReplyToInternetMessageId,
referencesInternetMessageIds: input.referencesInternetMessageIds,
attachments: input.attachments,
});
const result = await sendRawMessage(creds.accessToken, toBase64Url(raw), input.providerThreadId ?? undefined);
return { providerMessageId: result.id, providerThreadId: result.threadId ?? null };
},
async markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void> {
await modifyMessageLabels(creds.accessToken, providerMessageId, isRead ? { removeLabelIds: ["UNREAD"] } : { addLabelIds: ["UNREAD"] });
},
async listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]> {
const message = await this.getMessage(creds, providerMessageId);
return message ? [...message.attachments] : [];
},
async downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null> {
const metas = await this.listAttachments(creds, providerMessageId);
const meta = metas.find((m) => m.attachmentId === attachmentId);
if (!meta) {
return null;
}
const body = await getAttachment(creds.accessToken, providerMessageId, attachmentId);
// Gmail returns base64url → normalize to standard base64 for storage.
const normalized = body.data.replace(/-/g, "+").replace(/_/g, "/");
return { ...meta, sizeBytes: body.size || meta.sizeBytes, contentBase64: normalized };
},
};
// Keep the pseudo-folder key exported for the sync services (cursor rows).
export { GMAIL_GLOBAL_FOLDER };
@@ -0,0 +1,182 @@
// VA-P23 · Microsoft Graph implementation of the EmailProviderAdapter.
//
// Maps the neutral domain shapes to/from the shared @hivegrid/integrations Graph
// REST client. No Prisma here. Graph specifics (M09 Block D/G): subscriptions
// live ~3 days (renewal cron PATCHes), delta is PER FOLDER (inbox + sentitems),
// and sendMail answers 202 without a message id → the caller mirrors locally and
// the sent-items delta dedupes via internetMessageId.
import {
GraphMailError,
buildInitialDeltaUrl,
buildMicrosoftAuthorizationUrl,
createMailSubscription,
deleteMailSubscription,
exchangeMicrosoftCodeForTokens,
fetchDeltaPage,
fetchGraphUserProfile,
getGraphAttachment,
getGraphMessage,
listGraphAttachments,
mapGraphMessage,
refreshMicrosoftAccessToken,
renewMailSubscription,
resolveMicrosoftMailOAuthConfig,
sendGraphMail,
setGraphMessageRead,
type MicrosoftMailOAuthConfig,
} from "@hivegrid/integrations";
import {
type EmailAccount,
type EmailCreds,
type EmailProviderAdapter,
type EmailTokens,
type MailDeltaResult,
type MailWebhookSubscription,
type NeutralAttachmentContent,
type NeutralAttachmentMeta,
type NeutralMessage,
type SendMailInput,
type SendMailResult,
} from "./EmailProviderAdapter";
import { EmailInboxNotConfiguredError } from "./GmailAdapter.server";
function requireConfig(): MicrosoftMailOAuthConfig {
const config = resolveMicrosoftMailOAuthConfig();
if (!config) {
throw new EmailInboxNotConfiguredError("microsoft");
}
return config;
}
export const microsoftMailProviderAdapter: EmailProviderAdapter = {
provider: "microsoft",
isConfigured(): boolean {
return resolveMicrosoftMailOAuthConfig() !== null;
},
buildAuthorizationUrl(state: string): string {
return buildMicrosoftAuthorizationUrl(requireConfig(), state);
},
async exchangeCode(code: string): Promise<{ tokens: EmailTokens; account: EmailAccount }> {
const config = requireConfig();
const tokenSet = await exchangeMicrosoftCodeForTokens(config, code);
const profile = await fetchGraphUserProfile(tokenSet.accessToken);
return {
tokens: { accessToken: tokenSet.accessToken, refreshToken: tokenSet.refreshToken, expiresAt: tokenSet.expiresAt, scopes: tokenSet.scopes },
account: { email: profile.email, accountId: profile.id, displayName: profile.displayName },
};
},
async refreshTokens(refreshToken: string): Promise<EmailTokens> {
const set = await refreshMicrosoftAccessToken(requireConfig(), refreshToken);
return { accessToken: set.accessToken, refreshToken: set.refreshToken, expiresAt: set.expiresAt, scopes: set.scopes };
},
async subscribeWebhook(creds: EmailCreds, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription> {
const subscription = await createMailSubscription(creds.accessToken, notificationUrl, clientState);
return { subscriptionId: subscription.id, expiresAt: subscription.expiresAt, initialCursor: null };
},
async renewWebhook(creds: EmailCreds, subscriptionId: string, notificationUrl: string, clientState: string): Promise<MailWebhookSubscription> {
try {
const renewed = await renewMailSubscription(creds.accessToken, subscriptionId);
return { subscriptionId: renewed.id, expiresAt: renewed.expiresAt, initialCursor: null };
} catch (error) {
// Already expired at Microsoft → re-create instead of renew.
if (error instanceof GraphMailError && error.code === "subscription_failed") {
return this.subscribeWebhook(creds, notificationUrl, clientState);
}
throw error;
}
},
async revokeWebhook(creds: EmailCreds, subscriptionId: string): Promise<void> {
await deleteMailSubscription(creds.accessToken, subscriptionId);
},
async revokeTokens(): Promise<void> {
// The Microsoft identity platform has no app-side delegated-token revoke —
// disconnect drops the ciphertexts + subscription (documented in the service).
},
async fetchMessages(
creds: EmailCreds,
folderId: string,
opts: { cursor?: string | null; pageToken?: string | null; initialSince?: Date },
): Promise<MailDeltaResult> {
// Graph paging: cursor = @odata.deltaLink, pageToken = @odata.nextLink —
// both are followed verbatim; absent both, start a bounded initial delta.
const url =
opts.pageToken ??
opts.cursor ??
buildInitialDeltaUrl(folderId, opts.initialSince ? opts.initialSince.toISOString() : undefined);
try {
const page = await fetchDeltaPage(creds.accessToken, url);
const messages = page.messages
.filter((m) => !m["@removed"])
.map((m) => mapGraphMessage(m, folderId));
return { messages, nextCursor: page.deltaLink, nextPageToken: page.nextLink };
} catch (error) {
if (error instanceof GraphMailError && error.fullResyncRequired) {
return { messages: [], fullResyncRequired: true };
}
throw error;
}
},
async getMessage(creds: EmailCreds, providerMessageId: string): Promise<NeutralMessage | null> {
try {
const message = await getGraphMessage(creds.accessToken, providerMessageId);
// Folder context is unknown on a direct fetch — inbox mapping is neutral
// here; the caller preserves the stored direction on upsert.
return mapGraphMessage(message, "inbox");
} catch (error) {
if (error instanceof GraphMailError && error.code === "message_not_found") {
return null;
}
throw error;
}
},
async sendMessage(creds: EmailCreds, input: SendMailInput): Promise<SendMailResult> {
await sendGraphMail(creds.accessToken, {
subject: input.subject,
bodyHtml: input.bodyHtml,
to: input.to,
cc: input.cc,
bcc: input.bcc,
attachments: input.attachments?.map((a) => ({ name: a.filename, contentType: a.mimeType, contentBase64: a.contentBase64 })),
inReplyToInternetMessageId: input.inReplyToInternetMessageId ?? undefined,
});
// 202 without an id — the sent-items delta ingests the provider copy and
// dedupes onto the local outbound mirror via internetMessageId.
return { providerMessageId: null, providerThreadId: input.providerThreadId ?? null };
},
async markRead(creds: EmailCreds, providerMessageId: string, isRead: boolean): Promise<void> {
await setGraphMessageRead(creds.accessToken, providerMessageId, isRead);
},
async listAttachments(creds: EmailCreds, providerMessageId: string): Promise<NeutralAttachmentMeta[]> {
const list = await listGraphAttachments(creds.accessToken, providerMessageId);
return list.map((a) => ({ attachmentId: a.id, filename: a.name, mimeType: a.contentType ?? null, sizeBytes: a.sizeBytes }));
},
async downloadAttachment(creds: EmailCreds, providerMessageId: string, attachmentId: string): Promise<NeutralAttachmentContent | null> {
const attachment = await getGraphAttachment(creds.accessToken, providerMessageId, attachmentId);
if (!attachment.contentBase64) {
// >3 MB needs the $value stream — deferred (v1 size cap in the caller).
return null;
}
return {
attachmentId: attachment.id,
filename: attachment.name,
mimeType: attachment.contentType ?? null,
sizeBytes: attachment.sizeBytes,
contentBase64: attachment.contentBase64,
};
},
};