@teamscala/service-boot 0.23.284

package/src/fn-routers/agreement-completion-email.ts

@@ -0,0 +1,115 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Completion delivery. When an agreement is fully EXECUTED (every party has
+ * signed), email each party their executed copy + a note to download the
+ * Certificate of Completion. Each link is a per-party magic-link (no email gate,
+ * no OTP — see attach-agreement-magic.ts). Best-effort and self-contained: it
+ * loads its own data and swallows every error, so a send failure is logged and
+ * NEVER undoes the signature (the payment-setup non-fatal rule, applied to mail).
+ * Fire-and-forget from the sign handler: `void sendAgreementCompletionEmails(...)`.
+ */
+
+import * as v from "valibot";
+import { getServerClient } from "@teamscala/orpc/server-client-registry";
+import type { PrismaClient } from "@teamscala/db/client";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
+import { sendEmail, initResendClient } from "@teamscala/api-resend/send-email";
+import { applyTemplateVars, lookupTemplate } from "@teamscala/email/templates/lookup";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { signAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
+import { parseAgreementParties } from "@teamscala/document-signing/agreement-parties";
+import { getDefaultEmailSender } from "./email-defaults.ts";
+import { getEmailLinkTtlMs } from "./email-link-ttl.ts";
+
+// Emailed links are opened hours/days later — they must outlive the 30-min
+// in-session token, or the recipient lands on the unauthed gate ("white page").
+
+
+export async function sendAgreementCompletionEmails(
+	agreementId: string,
+	baseUrl: string,
+): Promise<void> {
+	const log = getAppLogger();
+	try {
+		const prisma = (await getServerClient()) as unknown as PrismaClient;
+		const agreement = await prisma.agreements.findFirst({
+			where: { id: agreementId },
+			select: { name: true, page_id: true, signature_data: true },
+		});
+		if (!agreement) return;
+		const parties = parseAgreementParties(agreement.signature_data) ?? [];
+		if (parties.length === 0) return;
+
+		const page = agreement.page_id
+			? await prisma.builda_pages.findFirst({
+					where: { id: agreement.page_id },
+					select: { path: true },
+				})
+			: null;
+		if (!page?.path) return;
+
+		const rawSecret = await loadRegistryConfig(
+			"secret",
+			"resend-api-key",
+			v.looseObject({ token: v.optional(v.string()) }),
+		).catch(() => null);
+		const decrypted = rawSecret
+			? (decryptSecretConfig(rawSecret as never) as { token?: string })
+			: null;
+		if (!decrypted?.token) {
+			log.warn("[completion-email] Resend token unavailable — skipping");
+			return;
+		}
+		initResendClient(decrypted.token);
+		const from = await getDefaultEmailSender();
+
+		const base = baseUrl.replace(/\/+$/, "");
+		log.info(
+			`[completion-email] ${agreementId} executed — emailing ${parties.length} ${parties.length === 1 ? "party" : "parties"}`,
+		);
+		for (const p of parties) {
+			if (!p.email) continue;
+			const token = signAgreementAccessToken(
+				agreementId,
+				p.email,
+				Date.now(),
+				await getEmailLinkTtlMs(),
+			);
+			const url = token
+				? `${base}/api/agreement-magic?a=${encodeURIComponent(agreementId)}&t=${encodeURIComponent(token)}&to=${encodeURIComponent(page.path)}`
+				: `${base}${page.path}`;
+			// Subject + body from the `agreement-completion` email_template row, not
+			// literals here (email-template-registry-type): copy changes are a
+			// registry_edit, not a deploy, and an org can override the row.
+			const tpl = applyTemplateVars(await lookupTemplate("agreement-completion"), {
+				recipientName: p.name || "there",
+				agreementName: agreement.name,
+				url,
+			});
+			const res = await sendEmail({
+				from,
+				to: p.email,
+				subject: tpl.subject,
+				html: tpl.bodyHtml,
+				text: tpl.bodyText,
+			});
+			if (res.success) {
+				log.info(
+					`[completion-email] sent to ${p.email}${res.id ? ` (id ${res.id})` : ""}`,
+				);
+			} else {
+				log.error(
+					`[completion-email] failed to ${p.email}: ${res.error ?? "unknown"}`,
+				);
+			}
+		}
+	} catch (e) {
+		log.error(
+			`[completion-email] non-fatal: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+}

package/src/fn-routers/agreement-send-router.ts

@@ -0,0 +1,303 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * fn.agreementSend.send — authenticated "send for signature" procedure. Emails
+ * each party of an agreement a link to its signing page, stamps the lifecycle
+ * (sent_to / sent_at, status draft→sent), and returns a per-recipient result.
+ *
+ * Off-the-shelf path per building-applications: this is server logic beyond
+ * CRUD, so it is a typed ORPC procedure (not a bespoke endpoint), and it sends
+ * through the shared Resend adapter (@teamscala/api-resend) — the same surface
+ * @teamscala/auth uses for OTP — never a new email integration.
+ *
+ * Per-org sender: emails go FROM the org's display name on the platform's
+ * verified Resend domain ("<Org> via Sign <verified-addr>"), with reply_to set
+ * to the org's contact_email, so replies reach the org without each org needing
+ * its own verified domain. When an org later verifies its own sending domain,
+ * resolveSender is the single place to switch the FROM address.
+ *
+ * Sending is privileged (it reaches real inboxes), so the procedure requires an
+ * authenticated caller — the localhost super-admin bypass authorises operator /
+ * portal-SSR callers; the public signing page cannot invoke it.
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import {
+	decryptSecretConfig,
+	type SecretConfigLike,
+} from "@teamscala/encryption/crypto/secret-config";
+import { sendEmail, initResendClient } from "@teamscala/api-resend/send-email";
+import { applyTemplateVars, lookupTemplate } from "@teamscala/email/templates/lookup";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { signAgreementAccessToken } from "@teamscala/document-signing/agreement-access-token";
+import { resetRlsContext, setRlsContext } from "@teamscala/db/rls-context";
+import { getDefaultEmailSender } from "./email-defaults.ts";
+import { getEmailLinkTtlMs } from "./email-link-ttl.ts";
+
+// Emailed links must outlive the 30-min in-session token (opened hours/days
+// later), else the recipient lands on the unauthed gate ("white page").
+
+interface User {
+	id: string;
+	organisationId: string | null;
+}
+
+interface Context {
+	user: User | null | undefined;
+	headers: Headers;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<User | null>;
+	prisma: any;
+}
+
+const authed = os.$context<Context>().use(async (opt) => {
+	const { context } = opt;
+	let user = context.user;
+	if (!user && context.headers && context.resolveUser) {
+		user = await context.resolveUser(context.headers, context.prisma);
+	}
+	if (!user) {
+		const { ORPCError } = await import("@orpc/server");
+		throw new ORPCError("UNAUTHORIZED", { message: "Authentication required" });
+	}
+	// Audit attribution: set the audit session context so writes (agreements.update)
+	// record the actor (app.current_user_name) — see auth-router.ts for the rationale.
+	const u = user as { id: string; name?: string | null; email?: string };
+	await setRlsContext(context.prisma, {
+		userId: u.id,
+		userName: u.name || u.email,
+		organisationId: user.organisationId,
+	});
+	try {
+		return await opt.next({ context: { ...context, user } });
+	} finally {
+		await resetRlsContext(context.prisma);
+	}
+});
+
+interface Recipient {
+	email: string;
+	name: string;
+}
+
+/** Parse the multi-party roster, or fall back to the single signer columns. */
+function recipientsFor(agreement: {
+	signature_data: unknown;
+	signer_email: unknown;
+	signer_name: unknown;
+}): Recipient[] {
+	const raw = agreement.signature_data;
+	if (typeof raw === "string" && raw.trim().startsWith("{")) {
+		try {
+			const o = JSON.parse(raw) as { parties?: Array<Record<string, unknown>> };
+			if (Array.isArray(o.parties)) {
+				return o.parties
+					.map((p) => ({
+						email: String(p.email ?? "").trim(),
+						name: String(p.name ?? "").trim(),
+					}))
+					.filter((r) => r.email.length > 0);
+			}
+		} catch {
+			/* fall through to single-signer */
+		}
+	}
+	const email = String(agreement.signer_email ?? "").trim();
+	return email ? [{ email, name: String(agreement.signer_name ?? "").trim() }] : [];
+}
+
+/** Extract the bare address from a "Display <addr@domain>" sender string. */
+function bareAddress(sender: string): string {
+	const m = sender.match(/<([^>]+)>/);
+	return (m?.[1] ?? sender).trim();
+}
+
+/**
+ * Resolve the per-org FROM + reply_to. FROM uses the org display name on the
+ * platform's verified Resend address; reply_to is the org's contact email.
+ */
+async function resolveSender(
+	prisma: any,
+	organisationId: string,
+): Promise<{ from: string; replyTo?: string; orgName: string }> {
+	const templates = await loadRegistryConfig(
+		"config",
+		"email-templates",
+		v.looseObject({ sender: v.optional(v.string()) }),
+	).catch(() => ({ sender: undefined }) as { sender?: string });
+	const verifiedAddr = bareAddress(
+		templates.sender ?? (await getDefaultEmailSender()),
+	);
+
+	const profile = await prisma.organisation_profile.findFirst({
+		where: { id: organisationId },
+		select: {
+			company_friendly_name: true,
+			company_name: true,
+			contact_email: true,
+		},
+	});
+	const orgName =
+		(profile?.company_friendly_name ||
+			profile?.company_name ||
+			"") as string;
+	const display = orgName ? `${orgName} via Sign` : "Sign";
+	return {
+		from: `${display} <${verifiedAddr}>`,
+		replyTo: (profile?.contact_email as string) || undefined,
+		orgName: orgName || "the sender",
+	};
+}
+
+
+const sendSchema = v.object({
+	agreementId: v.string(),
+	/** Public base URL of the signing site, e.g. https://sign-dev.scala.business (no trailing slash). */
+	baseUrl: v.string(),
+});
+
+export const agreementSendRouter = {
+	send: authed.input(sendSchema).handler(async ({ input, context }) => {
+		const log = getAppLogger();
+		const prisma = context.prisma;
+		const agreementId = input.agreementId.trim();
+		const baseUrl = input.baseUrl.trim().replace(/\/+$/, "");
+		if (!agreementId || !baseUrl) {
+			return { ok: false as const, error: "agreementId and baseUrl are required" };
+		}
+
+		try {
+			return await runSend(prisma, agreementId, baseUrl, log);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log.error(`[agreementSend] unexpected failure: ${message}`);
+			return { ok: false as const, error: message };
+		}
+	}),
+};
+
+async function runSend(
+	prisma: any,
+	agreementId: string,
+	baseUrl: string,
+	log: ReturnType<typeof getAppLogger>,
+) {
+		const agreement = await prisma.agreements.findFirst({
+			where: { id: agreementId },
+			select: {
+				id: true,
+				name: true,
+				status: true,
+				organisation_id: true,
+				page_id: true,
+				signer_email: true,
+				signer_name: true,
+				signature_data: true,
+			},
+		});
+		if (!agreement) return { ok: false as const, error: "Agreement not found" };
+
+		const page = agreement.page_id
+			? await prisma.builda_pages.findFirst({
+					where: { id: agreement.page_id },
+					select: { path: true },
+				})
+			: null;
+		if (!page?.path) {
+			return { ok: false as const, error: "Agreement has no signing page" };
+		}
+		const url = `${baseUrl}${page.path}`;
+
+		const recipients = recipientsFor(agreement);
+		if (recipients.length === 0) {
+			return { ok: false as const, error: "Agreement has no signer emails" };
+		}
+
+		const sender = await resolveSender(prisma, agreement.organisation_id);
+
+		// Initialise the Resend client from the encrypted secret row, read live
+		// via the registry helper (registry-via-helper) then decrypted.
+		const rawSecret = await loadRegistryConfig(
+			"secret",
+			"resend-api-key",
+			v.looseObject({ token: v.optional(v.string()) }),
+		).catch(() => null);
+		if (!rawSecret) {
+			return { ok: false as const, error: "Resend API key not configured" };
+		}
+		const decrypted = decryptSecretConfig(rawSecret as SecretConfigLike) as { token?: string };
+		if (!decrypted.token) {
+			return { ok: false as const, error: "Resend API key missing token" };
+		}
+		initResendClient(decrypted.token);
+
+		const sent: Array<{ email: string; ok: boolean; id?: string; error?: string }> =
+			[];
+		for (const r of recipients) {
+			// Magic-link: a per-party signed token so this recipient opens the
+			// document directly — no email-entry gate, no OTP. The token is scoped
+			// to {agreementId, this email}; /api/agreement-magic verifies it, sets
+			// the ag_token cookie, and redirects into the page. Falls back to the
+			// plain page URL when the token secret is unavailable.
+			const magicToken = signAgreementAccessToken(
+				agreementId,
+				r.email,
+				Date.now(),
+				await getEmailLinkTtlMs(),
+			);
+			const recipientUrl = magicToken
+				? `${baseUrl}/api/agreement-magic?a=${encodeURIComponent(agreementId)}&t=${encodeURIComponent(magicToken)}&to=${encodeURIComponent(page.path)}`
+				: url;
+			// Subject + body come from the `agreement-signature-request`
+			// email_template row, never from literals here
+			// (email-template-registry-type): changing the copy is a registry_edit,
+			// not a deploy, and an org can override the row per tenant. The `from`
+			// stays computed — it is the verified sender identity, not copy.
+			const tpl = applyTemplateVars(
+				await lookupTemplate("agreement-signature-request"),
+				{
+					hello: r.name ? `Hi ${r.name},` : "Hello,",
+					orgName: sender.orgName,
+					agreementName: agreement.name,
+					url: recipientUrl,
+				},
+			);
+			const res = await sendEmail({
+				from: sender.from,
+				to: r.email,
+				reply_to: sender.replyTo,
+				subject: tpl.subject,
+				html: tpl.bodyHtml,
+				text: tpl.bodyText,
+			});
+			sent.push({
+				email: r.email,
+				ok: res.success,
+				id: res.id,
+				error: res.error,
+			});
+			if (!res.success) {
+				log.error(
+					`[agreementSend] failed to ${r.email}: ${res.error ?? "unknown"}`,
+				);
+			}
+		}
+
+		const anySent = sent.some((s) => s.ok);
+		const now = new Date().toISOString();
+		if (anySent) {
+			await prisma.agreements.update({
+				where: { id: agreementId },
+				data: {
+					sent_to: recipients.map((r) => r.email).join(", "),
+					sent_at: now,
+					...(agreement.status === "draft" ? { status: "sent" } : {}),
+				},
+			});
+		}
+
+		return { ok: anySent, sentAt: anySent ? now : null, url, sent };
+}

package/src/fn-routers/ai-health-router.ts

@@ -0,0 +1,64 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * `fn.aiHealth` — the AI-availability probe the shared chat hook
+ * (`useAIHealthCheck`) polls before showing the chat's health dot. It resolves
+ * the same DB-driven default model the chat engine uses (`ai-default-model`
+ * config → an active `llm_model` row) and reports `{status, mcp, gateway}`;
+ * `status:"ok"` means the chat has a usable model configured.
+ *
+ * Unauthed (a public GPT surface polls it too) and a LIGHTWEIGHT registry read
+ * via the request `prisma` — deliberately NO `@teamscala/chat-completion` import,
+ * so wiring this universal procedure never pulls the AI stack into every
+ * service. Registered into the `fn` namespace by registerFnRouters, so any
+ * chat-capable service answers it instead of 404-ing.
+ */
+
+import { os } from "@orpc/server";
+
+interface Context {
+	prisma: {
+		registry_entries: {
+			findFirst: (args: unknown) => Promise<{ config?: unknown; id?: string } | null>;
+		};
+	};
+}
+
+export interface AiHealthResponse {
+	status: "ok" | "error";
+	mcp: boolean;
+	gateway: boolean;
+	error?: string;
+}
+
+export const aiHealthHandler = os
+	.$context<Context>()
+	.handler(async ({ context }): Promise<AiHealthResponse> => {
+		try {
+			const cfg = await context.prisma.registry_entries.findFirst({
+				where: { type: "config", slug: "ai-default-model", is_active: true },
+				select: { config: true },
+			});
+			const modelKey = (cfg?.config as { model?: string } | null)?.model;
+			if (!modelKey) {
+				return { status: "error", mcp: false, gateway: false, error: "No default AI model configured" };
+			}
+			const model = await context.prisma.registry_entries.findFirst({
+				where: { type: "llm_model", slug: modelKey, is_active: true },
+				select: { id: true },
+			});
+			if (!model) {
+				return {
+					status: "error",
+					mcp: false,
+					gateway: false,
+					error: `Default AI model '${modelKey}' has no active llm_model row`,
+				};
+			}
+			return { status: "ok", mcp: true, gateway: true };
+		} catch (err) {
+			return { status: "error", mcp: false, gateway: false, error: (err as Error).message };
+		}
+	});

package/src/fn-routers/auth-router.ts

@@ -0,0 +1,131 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * ORPC procedures for auth checks (isOrgAdmin, resolveAdminOverride).
+ * Extracted from @teamscala/orpc/fn-router — primitives tier must not
+ * contain application-specific auth logic.
+ */
+
+import { os } from "@orpc/server";
+import { createCache } from "@teamscala/cache/create-cache";
+import { resetRlsContext, setRlsContext } from "@teamscala/db/rls-context";
+
+interface User {
+	id: string;
+	name?: string | null;
+	email?: string;
+	organisationId: string | null;
+}
+
+interface Context {
+	user: User | null | undefined;
+	headers: Headers;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<User | null>;
+	prisma: any;
+	orgId?: string | null;
+}
+
+const authed = os.$context<Context>().use(async (opt) => {
+	const { context } = opt;
+	let user: User | null | undefined = context.user;
+	if (!user && context.headers && context.resolveUser) {
+		user = await context.resolveUser(context.headers, context.prisma);
+	}
+	if (!user) {
+		const { ORPCError } = await import("@orpc/server");
+		throw new ORPCError("UNAUTHORIZED", { message: "Authentication required" });
+	}
+	const orgId = user.organisationId || context.orgId;
+	// Audit attribution: fn procedures are custom-named writes/actions
+	// (deleteEmpty, etc.), so detecting "is write" by method name is unreliable —
+	// set the audit session context (app.current_user_name) for every authed call
+	// so the DB audit trigger records the actor. Same bridge the generated CRUD
+	// protectedProcedure uses; reset in finally to avoid leaking onto the pooled
+	// connection. Without this, fn.* writes record an empty actor ("by .").
+	await setRlsContext(context.prisma, {
+		userId: user.id,
+		userName: user.name || user.email,
+		organisationId: orgId,
+	});
+	try {
+		return await opt.next({ context: { ...context, user, orgId } });
+	} finally {
+		await resetRlsContext(context.prisma);
+	}
+});
+
+const adminCache = createCache<boolean>("service-boot:org-admin", {
+	ttlMs: 5 * 60 * 1000,
+	maxSize: 2000,
+});
+
+async function isOrgAdminCached(
+	userId: string,
+	organisationId: string,
+	prisma: any,
+): Promise<boolean> {
+	const cacheKey = `${userId}:${organisationId}`;
+	const cached = adminCache.get(cacheKey);
+	if (cached !== undefined) return cached;
+
+	try {
+		const membership = await prisma.user_organisation_memberships.findFirst({
+			where: {
+				user_id: userId,
+				organisation_id: organisationId,
+				role: { in: ["admin", "owner"] },
+			},
+			select: { id: true },
+		});
+		const result = !!membership;
+		adminCache.set(cacheKey, result);
+		return result;
+	} catch {
+		return false;
+	}
+}
+
+export const authRouter = {
+	isOrgAdmin: authed.handler(async ({ input, context }) => {
+		const data = input as { userId: string; organisationId: string };
+		if (!data.userId || !data.organisationId) return false;
+		return isOrgAdminCached(data.userId, data.organisationId, context.prisma);
+	}),
+	resolveAdminOverride: authed.handler(async ({ input, context }) => {
+		const data = input as {
+			targetUserId?: string;
+			adminOverride?: boolean;
+		};
+		const targetUserId = data.targetUserId as string | undefined;
+		if (!targetUserId) return null;
+		if (targetUserId === (context.user as any)?.id) return null;
+		if (!data.adminOverride) {
+			throw new Error(
+				`This tool does not support admin override. Remove targetUserId from the request.`,
+			);
+		}
+		const userId = (context.user as any)?.id;
+		const organisationId = (context as any).orgId;
+		if (!userId || !organisationId) {
+			throw new Error(
+				`Admin override requires both user and organisation context.`,
+			);
+		}
+		const admin = await isOrgAdminCached(
+			userId,
+			organisationId,
+			context.prisma,
+		);
+		if (!admin) {
+			throw new Error(
+				`Access denied: you must be an org admin or owner to view another user's data.`,
+			);
+		}
+		return targetUserId;
+	}),
+};
+
+export type { Context, User };
+export { authed };

package/src/fn-routers/cache-admin-router.ts

@@ -0,0 +1,50 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * `fn.cacheAdmin` — ORPC procedures for in-process cache enable/disable/flush.
+ * Replaces the former `/api/data/cache-monitor/*` HANDLER_MAP entries
+ * (orpc-is-the-only-api: every API surface is a typed ORPC procedure, never a
+ * hand-written Hono route). Calls through @teamscala/cache/registry — the
+ * platform-singleton cache surface (cache-is-the-only-cache).
+ */
+
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { authed } from "./auth-router.ts";
+
+const nameSchema = v.object({
+	name: v.pipe(v.string(), v.minLength(1)),
+});
+
+export const cacheAdminRouter = {
+	enable: authed
+		.input(nameSchema)
+		.handler(async ({ input }) => {
+			const { cacheRegistry } = await import("@teamscala/cache/registry");
+			cacheRegistry.enable(input.name);
+			return { ok: true, name: input.name };
+		}),
+
+	disable: authed
+		.input(nameSchema)
+		.handler(async ({ input }) => {
+			const { cacheRegistry } = await import("@teamscala/cache/registry");
+			cacheRegistry.disable(input.name);
+			return { ok: true, name: input.name };
+		}),
+
+	flush: authed
+		.input(v.object({ name: v.optional(v.string()) }))
+		.handler(async ({ input }) => {
+			const { cacheRegistry } = await import("@teamscala/cache/registry");
+			if (input.name) {
+				cacheRegistry.flush(input.name);
+				return { flushed: 1 };
+			}
+			const count = cacheRegistry.getAll().length;
+			cacheRegistry.flush();
+			return { flushed: count };
+		}),
+};