@teamscala/service-boot 0.23.479 → 0.23.492

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

@@ -1,114 +0,0 @@
-/**
- * @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 { sendResendEmail } from "./resend-client.ts";
-import { applyTemplateVars, lookupTemplate } from "@teamscala/email-template/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;
-		}
-		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 sendResendEmail(decrypted.token, {
-				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

@@ -1,303 +0,0 @@
-/**
- * @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 { sendResendEmail } from "./resend-client.ts";
-import { applyTemplateVars, lookupTemplate } from "@teamscala/email-template/lookup";
-import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import type { PrismaClient } from "@teamscala/db/client";
-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: PrismaClient) => Promise<User | null>;
-	prisma: PrismaClient;
-}
-
-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: PrismaClient,
-	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: PrismaClient,
-	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" };
-		}
-
-		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 sendResendEmail(decrypted.token, {
-				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/agreement-sign-side-effects.ts

@@ -1,192 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Post-signature side effects of public agreement signing: Stripe invoice
- * creation via the payments service, the self-resetting demo harness, and
- * CRM connection of the captured signer.
- *
- * Split out of fn-routers/public-agreement-router.ts (853 lines) —
- * byte-for-byte move; import paths adjusted only.
- */
-
-/**
- * Self-resetting demo harness. If the signed agreement's `proposal_id` is in
- * the `demo-reset-agreements.proposalIds` allow-list, reset its parties to
- * UNSIGNED (signedAt/signature cleared) + clear signed_at/signed_by + status
- * 'sent', so the next person gets a fresh form to test the UI.
- *
- * Keyed on the stable PROPOSAL id, NOT the agreement id: the demo agreement is
- * regenerated under a fresh id whenever the demo proposal is re-accepted, but
- * its `proposal_id` FK is constant — so the allow-list cannot dangle. This
- * deletes the drift class (prevention, not a patrol): the prior design keyed on
- * `agreementIds`, and when the demo was regenerated the list silently pointed
- * at a dead id and the reset became a no-op for weeks. A `proposal_id`-
- * referenced row that doesn't exist is a real proposal being deleted, not a
- * regeneration — a negligible residual the operator would notice directly.
- *
- * Gated strictly by the allow-list — a real agreement is never reset.
- * Best-effort: any failure is swallowed (a demo-reset must never fail the
- * signer's own response). The current signer already has their response (incl.
- * payUrl) before this runs; only the stored record is reset.
- */
-
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { queryRows } from "@teamscala/db/query-rows";
-import type { PrismaClient } from "@teamscala/db/client";
-import type { AgreementParty } from "@teamscala/document-signing/agreement-parties";
-
-/** On full agreement completion, delegate to the payment service over HTTP to
- *  create the Stripe invoice (per payment-is-one-service — all Stripe logic
- *  lives in @teamscala/payment, reached via POST /api/payments/checkout). Never
- *  throws — a payment-setup failure must not undo a completed signature; the
- *  signer is simply not auto-redirected to pay. But every failure mode is
- *  logged at WARN with the actual cause (URL missing, non-2xx, network, parse)
- *  so the silent-fail class the user would otherwise diagnose by hand is
- *  observable in GlitchTip + pm2 logs. */
-export async function invoicePayUrl(
-	agreementId: string,
-	baseUrl: string,
-): Promise<string | null> {
-	const log = getAppLogger();
-	const paymentsUrl = (process.env.SCALA_PAYMENTS_URL ?? "").replace(/\/+$/, "");
-	if (!paymentsUrl) {
-		log.warn(
-			`[publicAgreement] agreement ${agreementId} signed but SCALA_PAYMENTS_URL is unset — no invoice created. Set the env var on scala-sign's service_env row to a pay-internal tunnel URL.`,
-		);
-		return null;
-	}
-	try {
-		const res = await fetch(`${paymentsUrl}/api/payments/checkout`, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ agreementId, baseUrl }),
-		});
-		if (!res.ok) {
-			log.warn(
-				`[publicAgreement] payments checkout returned ${res.status} for agreement ${agreementId} (${paymentsUrl}/api/payments/checkout)`,
-			);
-			return null;
-		}
-		const json = (await res.json()) as { ok?: boolean; hostedInvoiceUrl?: string };
-		if (!json.ok) {
-			log.warn(
-				`[publicAgreement] payments checkout ok=false for agreement ${agreementId}: ${JSON.stringify(json).slice(0, 200)}`,
-			);
-			return null;
-		}
-		return json.hostedInvoiceUrl ?? null;
-	} catch (err) {
-		log.warn(
-			`[publicAgreement] payments checkout threw for agreement ${agreementId} (${paymentsUrl}): ${err instanceof Error ? err.message : String(err)}`,
-		);
-		return null;
-	}
-}
-
-export async function maybeResetDemoAgreement(
-	prisma: PrismaClient,
-	agreementId: string,
-	proposalId: string | null,
-	parties: AgreementParty[],
-): Promise<void> {
-	if (!proposalId) return;
-	try {
-		const rows = await queryRows`
-			SELECT config FROM registry_entries
-			 WHERE type = 'config' AND slug = 'demo-reset-agreements' AND is_active = true
-			 LIMIT 1` as { config: { proposalIds?: string[] } }[];
-		const ids = rows?.[0]?.config?.proposalIds ?? [];
-		if (!Array.isArray(ids) || !ids.includes(proposalId)) return;
-		const reset = parties.map((p) => ({
-			...p,
-			signedAt: null,
-			signature: null,
-			title: null,
-			company: null,
-		}));
-		await prisma.agreements.update({
-			where: { id: agreementId },
-			data: {
-				signature_data: JSON.stringify({ parties: reset }),
-				signed_at: null,
-				signed_by: null,
-				status: "sent",
-			},
-		});
-		getAppLogger().info(`[publicAgreement.sign] demo agreement ${agreementId} auto-reset for re-testing`);
-	} catch {
-		// never fail the signer's response over a demo-reset
-	}
-}
-
-/**
- * Connect a captured signer to the CRM — every signable document lands in
- * client_database, the same find-or-create capture path proposals / public-GPT /
- * assessments already use (scoped by organisation_id + primary_email). Also
- * links agreement.contact_id when the agreement wasn't generated from a proposal
- * (contact_id NULL), so a standalone signed doc still connects to the CRM.
- * Best-effort: a CRM write must never fail the signature (the signature is the
- * legal act; CRM connection is bookkeeping).
- */
-export async function connectSignerToCrm(
-	prisma: PrismaClient,
-	agreement: { id: string; organisation_id?: string | null; contact_id?: string | null },
-	email: string,
-	signerName?: string | null,
-	company?: string | null,
-): Promise<void> {
-	const orgId = agreement.organisation_id;
-	if (!orgId || !email || !prisma?.client_database) return;
-	try {
-		const parts = (signerName ?? "").trim().split(/\s+/).filter(Boolean);
-		const firstName = parts[0] ?? "";
-		const lastName = parts.slice(1).join(" ");
-		const existing = await prisma.client_database.findFirst({
-			where: { organisation_id: orgId, primary_email: email },
-			select: { id: true },
-		});
-		let contactId: string | null = null;
-		if (existing) {
-			contactId = existing.id as string;
-			await prisma.client_database.update({
-				where: { id: existing.id },
-				data: {
-					...(firstName ? { first_name: firstName } : {}),
-					...(lastName ? { last_name: lastName } : {}),
-					...(company ? { company_name: company } : {}),
-					last_updated_by: "agreement-sign",
-				},
-			});
-		} else {
-			const created = await prisma.client_database.create({
-				data: {
-					organisation_id: orgId,
-					first_name: firstName,
-					last_name: lastName,
-					primary_email: email,
-					...(company ? { company_name: company } : {}),
-					lead_source: "agreement-sign",
-					data_source: "public-form",
-					referral_source: agreement.id,
-					lifecycle_stage: "lead",
-					created_by: "agreement-sign",
-					last_updated_by: "agreement-sign",
-				},
-				select: { id: true },
-			});
-			contactId = (created?.id as string) ?? null;
-		}
-		if (contactId && !agreement.contact_id) {
-			await prisma.agreements.update({
-				where: { id: agreement.id },
-				data: { contact_id: contactId },
-			});
-		}
-	} catch (e) {
-		getAppLogger().warn(
-			`[publicAgreement.sign] CRM connect failed (non-fatal): ${e instanceof Error ? e.message : String(e)}`,
-		);
-	}
-}