Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -0,0 +1,70 @@
|
||||
// VA-P23 · Gmail integration adapter (catalog presence + health).
|
||||
//
|
||||
// Same shape as adapters/google-calendar.ts: the Apps-Engine catalog needs a
|
||||
// registered adapter per app key (drift-free, registry.test.ts), but the HEAVY
|
||||
// per-USER mailbox sync does NOT run through the generic AppSyncRun path — it
|
||||
// lives in the email-inbox module (apps/web/app/modules/emailInbox) keyed by
|
||||
// EmailIntegrationMailbox, because mailboxes are per-user with read_own
|
||||
// visibility, not per-tenant DataConnections.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GmailError, fetchGmailUserInfo, refreshGmailAccessToken, resolveGmailOAuthConfig } from "../google/gmailApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
|
||||
export interface GmailCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GmailError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
case "quota_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: GmailCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await fetchGmailUserInfo(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const gmailAdapter: IntegrationAdapter<GmailCreds> = registerIntegrationAdapter<GmailCreds>({
|
||||
key: "gmail",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: GmailCreds): Promise<AdapterTokenRefresh<GmailCreds>> => {
|
||||
const config = resolveGmailOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GmailError("not_configured");
|
||||
}
|
||||
const next = await refreshGmailAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync;
|
||||
// the generic engine sync is a no-op that reports this in Klartext.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
// AK-P16a · Google Calendar integration adapter (catalog presence + health).
|
||||
//
|
||||
// The Apps-Engine catalog needs a registered adapter per app key (drift-free,
|
||||
// registry.test.ts). The HEAVY per-USER bidirectional sync does NOT run through
|
||||
// the generic AppSyncRun path — it lives in the calendar module
|
||||
// (apps/web/app/modules/calendar) keyed by CalendarConnection, because calendar
|
||||
// connections are per-user with leak-protection, not per-tenant DataConnections.
|
||||
//
|
||||
// So this adapter is intentionally thin: it satisfies the contract for catalog
|
||||
// reachability + lets the platform-admin health surface probe a token, and
|
||||
// implements OAuth refresh by delegating to googleCalendarApi. `sync()` reports a
|
||||
// Klartext summary that the per-user engine owns the actual event sync.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GoogleCalendarError, listCalendars, refreshAccessToken, resolveGoogleOAuthConfig } from "../google/googleCalendarApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per CalendarConnection. */
|
||||
export interface GoogleCalendarCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GoogleCalendarError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "calendar.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "calendar.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: GoogleCalendarCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "calendar.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await listCalendars(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "calendar.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const googleCalendarAdapter: IntegrationAdapter<GoogleCalendarCreds> = registerIntegrationAdapter<GoogleCalendarCreds>({
|
||||
key: "google-calendar",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: GoogleCalendarCreds): Promise<AdapterTokenRefresh<GoogleCalendarCreds>> => {
|
||||
const config = resolveGoogleOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GoogleCalendarError("not_configured");
|
||||
}
|
||||
const next = await refreshAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user calendar engine (webhook + cron driven) owns event sync; the
|
||||
// generic engine sync is a no-op that reports this in Klartext.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "calendar.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
// VA-P23 · Microsoft (Outlook/Graph) mail integration adapter (catalog presence
|
||||
// + health). Thin like adapters/gmail.ts — the per-user sync engine lives in the
|
||||
// email-inbox module, this satisfies the catalog/registry drift contract.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter, type AdapterTokenRefresh } from "@hivegrid/foundation";
|
||||
import { GraphMailError, fetchGraphUserProfile, refreshMicrosoftAccessToken, resolveMicrosoftMailOAuthConfig } from "../microsoft/graphMailApi.js";
|
||||
|
||||
/** Decrypted credential shape stored (envelope-encrypted) per mailbox. */
|
||||
export interface MicrosoftMailCreds {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresAt?: string | null;
|
||||
}
|
||||
|
||||
function healthFromError(error: unknown): AdapterResult {
|
||||
if (error instanceof GraphMailError) {
|
||||
switch (error.code) {
|
||||
case "auth_token_expired":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
case "auth_scope_missing":
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.scopeMissing" };
|
||||
case "rate_limit_exceeded":
|
||||
return { ok: true, health: "degraded", messageKey: "emailInbox.health.rateLimited" };
|
||||
case "provider_outage":
|
||||
return { ok: false, health: "degraded", messageKey: "emailInbox.health.providerOutage" };
|
||||
default:
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
}
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.unknown" };
|
||||
}
|
||||
|
||||
async function probe(creds: MicrosoftMailCreds): Promise<AdapterResult> {
|
||||
if (!creds.accessToken) {
|
||||
return { ok: false, health: "broken", messageKey: "emailInbox.health.tokenExpired" };
|
||||
}
|
||||
try {
|
||||
await fetchGraphUserProfile(creds.accessToken);
|
||||
return { ok: true, health: "active", messageKey: "emailInbox.health.active" };
|
||||
} catch (error) {
|
||||
return healthFromError(error);
|
||||
}
|
||||
}
|
||||
|
||||
export const microsoftMailAdapter: IntegrationAdapter<MicrosoftMailCreds> = registerIntegrationAdapter<MicrosoftMailCreds>({
|
||||
key: "microsoft-mail",
|
||||
connectionType: "oauth2",
|
||||
validateConnection: probe,
|
||||
healthCheck: probe,
|
||||
refreshToken: async (creds: MicrosoftMailCreds): Promise<AdapterTokenRefresh<MicrosoftMailCreds>> => {
|
||||
const config = resolveMicrosoftMailOAuthConfig();
|
||||
if (!config) {
|
||||
throw new GraphMailError("not_configured");
|
||||
}
|
||||
const next = await refreshMicrosoftAccessToken(config, creds.refreshToken);
|
||||
return {
|
||||
creds: { accessToken: next.accessToken, refreshToken: next.refreshToken ?? creds.refreshToken, expiresAt: next.expiresAt.toISOString() },
|
||||
expiresAt: next.expiresAt,
|
||||
};
|
||||
},
|
||||
// The per-user email-inbox engine (webhook + cron driven) owns the mail sync.
|
||||
sync: (): Promise<AdapterSyncOutcome> => Promise.resolve({ items: [], summaryKey: "emailInbox.sync.summary.perUserEngine" }),
|
||||
});
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
import { createHmac } from "node:crypto";
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { buildPandaDocAuthHeader, pandaDocByokAdapter, verifyPandaDocWebhookSignature } from "./pandadoc-byok.js";
|
||||
|
||||
describe("PandaDoc BYOK adapter", () => {
|
||||
it("uses the API-Key auth header confirmed by EXT-17", () => {
|
||||
expect(buildPandaDocAuthHeader("secret")).toBe("API-Key secret");
|
||||
});
|
||||
|
||||
it("validates required BYOK credentials", async () => {
|
||||
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k", templateUuid: "tpl" })).resolves.toMatchObject({ ok: true });
|
||||
await expect(pandaDocByokAdapter.validateConnection({ apiKey: "k" })).resolves.toMatchObject({ ok: false, health: "broken" });
|
||||
});
|
||||
|
||||
it("verifies HMAC SHA-256 webhooks over the raw body", () => {
|
||||
const rawBody = JSON.stringify({ event: "document.completed", data: { id: "pd-1" } });
|
||||
const signature = createHmac("sha256", "shared").update(rawBody).digest("hex");
|
||||
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, signature, "shared")).toBe(true);
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, `sha256=${signature}`, "shared")).toBe(true);
|
||||
expect(verifyPandaDocWebhookSignature(rawBody, signature, "other")).toBe(false);
|
||||
});
|
||||
});
|
||||
+54
@@ -0,0 +1,54 @@
|
||||
// AK-P16d · optional PandaDoc BYOK adapter.
|
||||
//
|
||||
// Plane/EXT-17 confirmed the implementation details used here:
|
||||
// Authorization: API-Key <key>, template-driven documents, and webhook HMAC
|
||||
// SHA-256 over the raw request body with the signature supplied by PandaDoc.
|
||||
|
||||
import { createHmac, timingSafeEqual } from "node:crypto";
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
export interface PandaDocByokCreds {
|
||||
readonly apiKey?: string | null;
|
||||
readonly templateUuid?: string | null;
|
||||
readonly webhookSharedKey?: string | null;
|
||||
}
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
const MISSING: AdapterResult = { ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" };
|
||||
|
||||
function validate(creds: PandaDocByokCreds): Promise<AdapterResult> {
|
||||
if (!creds.apiKey || !creds.templateUuid) {
|
||||
return Promise.resolve(MISSING);
|
||||
}
|
||||
return Promise.resolve(ACTIVE);
|
||||
}
|
||||
|
||||
function normalizeSignature(signature: string): string {
|
||||
return signature.startsWith("sha256=") ? signature.slice("sha256=".length) : signature;
|
||||
}
|
||||
|
||||
export function buildPandaDocAuthHeader(apiKey: string): string {
|
||||
return `API-Key ${apiKey}`;
|
||||
}
|
||||
|
||||
export function verifyPandaDocWebhookSignature(rawBody: string | Buffer, signature: string | null | undefined, sharedKey: string | null | undefined): boolean {
|
||||
if (!signature || !sharedKey) return false;
|
||||
const expected = createHmac("sha256", sharedKey).update(rawBody).digest("hex");
|
||||
const received = normalizeSignature(signature);
|
||||
const expectedBuffer = Buffer.from(expected, "hex");
|
||||
const receivedBuffer = Buffer.from(received, "hex");
|
||||
if (expectedBuffer.length !== receivedBuffer.length) return false;
|
||||
return timingSafeEqual(expectedBuffer, receivedBuffer);
|
||||
}
|
||||
|
||||
export const pandaDocByokAdapter: IntegrationAdapter<PandaDocByokCreds> = registerIntegrationAdapter<PandaDocByokCreds>({
|
||||
key: "pandadoc-byok",
|
||||
connectionType: "api_key",
|
||||
validateConnection: validate,
|
||||
healthCheck: validate,
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [],
|
||||
summaryKey: "integrations.sync.summary.noop",
|
||||
}),
|
||||
});
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
// R-P5 (P5) — reference integration adapter (the only adapter shipped in v1).
|
||||
//
|
||||
// Demonstrates the IntegrationAdapter contract end-to-end (validate / health /
|
||||
// sync) without any external provider. Concrete adapters (Gmail/AirCall/Mollie)
|
||||
// follow this shape in their module phases. Registers itself on import (the
|
||||
// registry barrel imports this for its side effect).
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
type SampleCreds = { baseUrl: string; apiKey: string };
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
|
||||
function validate(creds: SampleCreds): Promise<AdapterResult> {
|
||||
if (!creds.baseUrl || !creds.apiKey) {
|
||||
return Promise.resolve({ ok: false, health: "broken", messageKey: "integrations.health.missingCredentials" });
|
||||
}
|
||||
return Promise.resolve(ACTIVE);
|
||||
}
|
||||
|
||||
export const sampleDataSyncAdapter: IntegrationAdapter<SampleCreds> = registerIntegrationAdapter<SampleCreds>({
|
||||
key: "sample-data-sync",
|
||||
connectionType: "rest_api",
|
||||
validateConnection: validate,
|
||||
healthCheck: validate,
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [
|
||||
{ entityType: "contact", externalId: "ext-1", operation: "created", status: "synced" },
|
||||
{ entityType: "contact", externalId: "ext-2", operation: "updated", status: "synced" },
|
||||
],
|
||||
summaryKey: "integrations.sync.summary.ok",
|
||||
}),
|
||||
});
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
// AK-P16d · AD-25 default signature adapter.
|
||||
//
|
||||
// The hardened SES implementation is local to HiveGrid (touch signature,
|
||||
// one-time links, email OTP, audit events, sealed PDF + completion certificate).
|
||||
// This adapter exists so the Apps-Engine catalog/registry can expose and monitor
|
||||
// the capability without requiring provider credentials.
|
||||
|
||||
import { registerIntegrationAdapter, type AdapterResult, type AdapterSyncOutcome, type IntegrationAdapter } from "@hivegrid/foundation";
|
||||
|
||||
type SesSelfhostedCreds = Record<string, never>;
|
||||
|
||||
const ACTIVE: AdapterResult = { ok: true, health: "active", messageKey: "integrations.health.active" };
|
||||
|
||||
export const sesSelfhostedAdapter: IntegrationAdapter<SesSelfhostedCreds> = registerIntegrationAdapter<SesSelfhostedCreds>({
|
||||
key: "ses-selfhosted",
|
||||
connectionType: "rest_api",
|
||||
validateConnection: () => Promise.resolve(ACTIVE),
|
||||
healthCheck: () => Promise.resolve(ACTIVE),
|
||||
sync: (): Promise<AdapterSyncOutcome> =>
|
||||
Promise.resolve({
|
||||
items: [],
|
||||
summaryKey: "integrations.sync.summary.noop",
|
||||
}),
|
||||
});
|
||||
Reference in new issue
Block a user